3.3.2 Advanced Multiphase Macros

For most standard UDFs written for multiphase models (e.g., source term, material property, profile functions), variables that your function needs (domain pointers, thread pointers, etc.) are passed directly to your UDF as arguments by the solver in the solution process. All you need to do is hook the UDF to your model and everything is taken care of. For example, if your multiphase UDF defines a custom profile for a particular boundary zone (using DEFINE_PROFILE) and is hooked to the appropriate phase or mixture in ANSYS FLUENT in the relevant boundary condition dialog box, then appropriate phase or mixture variables will be passed to your function by the solver at run-time.

There may, however, be more complex functions you wish to write that require a variable that is not directly passed through its arguments. DEFINE_ADJUST and DEFINE_INIT functions, for example, are passed mixture domain variables only. If a UDF requires a phase domain pointer, instead, then it will need to utilize macros presented in this section to retrieve it. ON_DEMAND UDFS aren't directly passed any variables through their arguments. Consequently, any on demand function that requires access to phase or domain variables will also need to utilize macros presented in this section to retrieve them.

Recall that when you are writing UDFs for multiphase models , you will need to keep in mind the hierarchy of structures within ANSYS FLUENT (see Section  1.10.1 for details). The particular domain or thread structure that gets passed into your UDF from the solver depends on the DEFINE macro you are using, as well as the domain the function is hooked to (either through the graphical user interface, or hardwired in the code). As mentioned above, it also may depend on the multiphase model that you are using. Refer to Section  1.10.1 and, in particular, Figure  1.10.1 for a discussion on hierarchy of structures within ANSYS FLUENT.

Phase Domain Pointer ( DOMAIN_SUB_DOMAIN)

There are two ways you can get access to a specific phase (or subdomain) pointer within the mixture domain. You can use either the DOMAIN_SUB_DOMAIN macro (described below) or Get_Domain, which is described below.

DOMAIN_SUB_DOMAIN has two arguments: mixture_domain and phase_domain_index. The function returns the phase pointer subdomain for the given phase_domain_index. Note that DOMAIN_SUB_DOMAIN is similar in implementation to the THREAD_SUB_THREAD macro described in Section  3.3.2.

int phase_domain_index = 0;             /* primary phase index is 0 */
Domain *mixture_domain;
Domain *subdomain = DOMAIN_SUB_DOMAIN(mixture_domain,phase_domain_index);

mixture_domain is a pointer to the mixture-level domain. It is automatically passed to your UDF by the ANSYS FLUENT solver when you use a DEFINE macro that contains a domain variable argument (e.g., DEFINE_ADJUST) and your UDF is hooked to the mixture. Otherwise, if the mixture_domain is not explicitly passed to your UDF, you will need to use another utility macro to retrieve it (e.g., Get_Domain(1)) before calling sub_domain_loop.

phase_domain_index is an index of subdomain pointers. It is an integer that starts with 0 for the primary phase and is incremented by one for each secondary phase. phase_domain_index is automatically passed to your UDF by the ANSYS FLUENT solver when you use a DEFINE macro that contains a phase domain index argument ( DEFINE_EXCHANGE_PROPERTY, DEFINE_VECTOR_EXCHANGE_PROPERTY) and your UDF is hooked to a specific interaction phase. Otherwise, you will need to hard code the integer value of phase_domain_index to the DOMAIN_SUB_DOMAIN macro. If your multiphase model has only two phases defined, then phase_domain_index is 0 for the primary phase, and 1 for the secondary phase. However, if you have more than one secondary phase defined for your multiphase model, you will need to use the PHASE_DOMAIN_INDEX utility to retrieve the corresponding phase_domain_index for the given domain. See Section  3.3.2 for details.

Phase-Level Thread Pointer ( THREAD_SUB_THREAD)

The THREAD_SUB_THREAD macro can be used to retrieve the phase-level thread (subthread) pointer, given the phase domain index. THREAD_SUB_THREAD has two arguments: mixture_thread and phase_domain_index. The function returns the phase-level thread pointer for the given phase_domain_index. Note that THREAD_SUB_THREAD is similar in implementation to the DOMAIN_SUB_DOMAIN macro described in Section  3.3.2.

int phase_domain_index = 0;             /* primary phase index is 0  */
Thread *mixture_thread;              /* mixture-level thread pointer */
Thread *subthread = THREAD_SUB_THREAD(mixture_thread,phase_domain_index);

mixture_thread is a pointer to a mixture-level thread. It is automatically passed to your UDF by the ANSYS FLUENT solver when you use a DEFINE macro that contains a variable thread argument (e.g., DEFINE_PROFILE), and the function is hooked to the mixture. Otherwise, if the mixture thread pointer is not explicitly passed to your UDF, then you will need to use the Lookup_Thread utility macro to retrieve it (see Section  3.2.6).

phase_domain_index is an index of subdomain pointers. It is an integer that starts with 0 for the primary phase and is incremented by one for each secondary phase. phase_domain_index is automatically passed to your UDF by the ANSYS FLUENT solver when you use a DEFINE macro that contains a phase domain index argument ( DEFINE_EXCHANGE_PROPERTY, DEFINE_VECTOR_EXCHANGE_PROPERTY) and your UDF is hooked to a specific interaction phase. (See Section  2.4.2 for an example UDF.) Otherwise, you will need to hard code the integer value of phase_domain_index to the THREAD_SUB_THREAD macro. If your multiphase model has only two phases defined, then phase_domain_index is 0 for the primary phase, and 1 for the secondary phase. However, if you have more than one secondary phase defined for your multiphase model, you will need to use the PHASE_DOMAIN_INDEX utility to retrieve the corresponding phase_domain_index for the given domain. See Section  3.3.2 for details.

Phase Thread Pointer Array ( THREAD_SUB_THREAD)

The THREAD_SUB_THREADS macro can be used to retrieve the pointer array, pt, whose elements contain pointers to phase-level threads (subthreads). THREADS_SUB_THREADS has one argument, mixture_thread.

Thread *mixture_thread;
Thread **pt;   /* initialize pt   */
pt = THREAD_SUB_THREADS(mixture_thread);

mixture_thread is a pointer to a mixture-level thread which can represent a cell thread or a face thread. It is automatically passed to your UDF by the ANSYS FLUENT solver when you use a DEFINE macro that contains a variable thread argument (e.g., DEFINE_PROFILE), and the function is hooked to the mixture. Otherwise, if the mixture thread pointer is not explicitly passed to your UDF, then you will need to use another method to retrieve it. For example you can use the Lookup_Thread utility macro (see Section  3.2.6).

pt[i], an element in the array, is a pointer to the corresponding phase-level thread for the $i$th phase, where i is the phase_domain_index. You can use pt[i] as an argument to some cell variable macros when you want to retrieve specific phase information at a cell. For example, C_R(c,pt[i]) can be used to return the density of the $i$th phase fluid at cell c. The pointer pt[i] can also be retrieved using THREAD_SUB_THREAD, discussed in Section  3.3.2, using i as an argument. The phase_domain_index can be retrieved using the PHASE_DOMAIN_INDEX macro. See Section  3.3.2 for details.

Mixture Domain Pointer ( DOMAIN_SUPER_DOMAIN)

You can use DOMAIN_SUPER_DOMAIN when your UDF has access to a particular phase-level domain (subdomain) pointer, and you want to retrieve the mixture-level domain pointer. DOMAIN_SUPER_DOMAIN has one argument, subdomain. Note that DOMAIN_SUPER_DOMAIN is similar in implementation to the THREAD_SUPER_THREAD macro described in Section  3.3.2.

Domain *subdomain;
Domain *mixture_domain = DOMAIN_SUPER_DOMAIN(subdomain);

subdomain is a pointer to a phase-level domain within the multiphase mixture. It is automatically passed to your UDF by the ANSYS FLUENT solver when you use a DEFINE macro that contains a domain variable argument (e.g., DEFINE_ADJUST), and the function is hooked to a primary or secondary phase in the mixture. Note that in the current version of ANSYS FLUENT, DOMAIN_SUPER_DOMAIN will return the same pointer as Get_Domain(1). Therefore, if a subdomain pointer is available in your UDF, it is recommended that the DOMAIN_SUPER_DOMAIN macro be used instead of the Get_Domain macro to avoid potential incompatibility issues with future releases of ANSYS FLUENT.

Mixture Thread Pointer ( THREAD_SUPER_THREAD)

You can use the THREAD_SUPER_THREAD macro when your UDF has access to a particular phase-level thread (subthread) pointer, and you want to retrieve the mixture-level thread pointer. THREAD_SUPER_THREAD has one argument, subthread.

Thread *subthread;
Thread *mixture_thread = THREAD_SUPER_THREAD(subthread);

subthread is a pointer to a particular phase-level thread within the multiphase mixture. It is automatically passed to your UDF by the ANSYS FLUENT solver when you use a DEFINE macro that contains a thread variable argument (e.g., DEFINE_PROFILE, and the function is hooked to a primary or secondary phase in the mixture. Note that THREAD_SUPER_THREAD is similar in implementation to the DOMAIN_SUPER_DOMAIN macro described in Section  3.3.2.

Domain ID ( DOMAIN_ID)

You can use DOMAIN_ID when you want to access the domain_id that corresponds to a given phase-level domain pointer. DOMAIN_ID has one argument, subdomain, which is the pointer to a phase-level domain. The default domain_id value for the top-level domain (mixture) is 1. That is, if the domain pointer that is passed to DOMAIN_ID is the mixture-level domain pointer, then the function will return a value of 1. Note that the domain_id that is returned by the macro is the same integer ID that is displayed in the graphical user interface when you select the desired phase in the Phases task page in ANSYS FLUENT.

Domain *subdomain;
int domain_id = DOMAIN_ID(subdomain);

Phase Domain Index ( PHASE_DOMAIN_INDEX)

The PHASE_DOMAIN_INDEX macro retrieves the phase_domain_index for a given phase-level domain (subdomain) pointer. PHASE_DOMAIN_INDEX has one argument, subdomain, which is the pointer to a phase-level domain. phase_domain_index is an index of subdomain pointers. It is an integer that starts with 0 for the primary phase and is incremented by one for each secondary phase.

Domain *subdomain;
int phase_domain_index = PHASE_DOMAIN_INDEX(subdomain);