 |
7.0
general documentation
|
|
|
7.0
general documentation
|
|
In addition to the settings defined with a setup.xml file and usually defined using the GUI, both basic and more advanced settings and models can be defined using user-defined functions, called at specific points in the code's execution.
As mentioned in the case structure description, and step by step preparation documentation, all C, C++, and Fortran files located directly in a case's SRC subdirectory will be automatically compiled and linked with the solver during a run's initialization stage.
This section provides basic information regarding the use of such functions.
User-defined functions usually allow for more complete or detailed settings than those defined through the GUI, and can be combined with them. All settings defined through the GUI (except for the activation of non-default physical or turbulence models) can be overridden in the matching user-defined functions, so the recommended practice is to define all that is possible using the GUI, and user-defined functions for the rest.
It is possible, though not recommended, to define a computation solely through user-defined functions, without using an XML setup or needing the GUI. This is not recommended for general use, as consistency checking and upgrading to a later version require much more effort, but might be useful for application specific or embedded models.
In most cases, a given user function reference may be found in the C or Fortran file of the same name.
When both C and Fortran versions of a given function of function series exist, the C version may be prefixed by cs, while the fortran version may be prefixed by cs_f. The Fortran version is usually called first, so the C function has the "last word". For example, cs_user_extra_operations may be found in the cs_user_extra_operations.c file, while cs_f_user_extra_operations is in cs_user_extra_operations.f90.
For advanced settings, many settings involve passing pointers to callback functions which will be be called at specific call points.
Callback functions need to match a specific profile (i.e. type and number of arguments) based on their role, but can otherwise be named in any manner, so choosing a self_explanatory name is recommended.
In most of this user documentation both callback function and function pointer terms may be used interchangeably. To be precise, callbacks are assigned using function pointers.
Many illustrations are provided in the examples section of the documentation. The matching files are also found under the src/cs_user_examples directory, in the source tree, or under ${install_prefix}/code_saturne/user_sources/EXAMPLES in most installations).
When multiple examples are provided, example file names are defined by appending the name of the matching example to the matching reference file name. For example, general examples for user source terms are provided in cs_user_source_terms-base.c, while examples specific to advanced turbulence model modification are found in cs_user_source_terms-turbulence.c
The user is encouraged to check which examples are available, and to study those that are relevant to a given setup.
Comparing template and example files with a graphical file comparison tool should help the user highlight the matching sections from the examples, so it is recommended as good practice for those not already very familiar with those user functions. Code blocks from examples can of course be cherry-picked and adapted to the user's needs. indiscriminately copying complete files to use only a fraction of the examples therein is considered bad practice, as it leads to confusing code, and is a form of cargo-cult programming.
The following sections lists some of the most frequently used user-defined functions, and their associated roles. It is not by any means exhaustive (for a full list, inspect all files in the source tree's src/user directory, or ${install_prefix}/code_saturne/user_sources/REFERENCE in most installations).
The following functions are called before the resolution stage, and before even the mesh is read. As a consequence, acess to mesh elements and counts, and any field or other array value defined on the mesh, is not available in these functions (though some settings may involve setting pointers to callback functions which will be able to access those elements.
cs_user_model (in cs_user_parameters.c)
Allows defining user scalars (species), variances, or activating a specific physical model (by setting cs_physical_model_type_t entry values in the cs_glob_physical_model_flag array).
It is called before all other physical or numerical oriented user functions (only system settings and mesh definitions are called earlier), so that the the variable and property fields implied by those models are instanciated and available in the following user function call points.
The equivalent Fortran function is named usppmo.
Allows defining which zones (based on mesh groups or geometric criteria) will be used for the computation. This allows advanced definitions, such as time-evolving zones based un user callback functions, in addition to the basic definitions provided by the GUI..
It is called before all physical or numerical oriented user functions.
cs_user_parameters (in cs_user_parameters.c)
Allows defining most general settings, such as reference physical properties model and numerical settings for main variable and property fields, etc. By default, settings should go here.
It is called before all other physical or numerical oriented user functions (only system settings and mesh definitions are called earlier), so that the the variable and property fields implied by those models are instanciated and available in the following user function call points.
The equivalent Fortran function is named usppmo.
cs_user_postprocess_writers, cs_user_postprocess_meshes, and cs_user_postprocess_probes (in cs_user_postprocess.c)
May be used to define or modify postprocessing extracts using the supported output formats, using the mesh and writer concepts.
cs_user_combustion (in cs_user_parameters.f90)
Allows specifying calculation options specific to the selected combustion model (gas, pulverized coal, or heavy fuel).
Contains several user subroutines used to define atmospheric model settings such as ground properties and 1-d atmospheric profiles.
Allows defining physical, numerical and post-processing options for the Lagrangian model (dispersed phase).
Allows performing various mesh modifications during the preprocessing stage.
Allows setting the initial values of variables and properties. In case of computation restart, the values from the restart files are loaded before this function is called, so can be either further modified or left alone.
cs_user_extra_operations_initialize (in cs_user_extra_operations.c)
Called just after cs_user_initialization (with only a few updates for some specific models in between), this function is used for more general operation than simply initializing variables.
Since it is placed in the same file as cs_user_extra_operations, it may be used to initialize user variables or structures local to that file before time stepping.
Allows defining variable physical property (such as fluid density, viscosity ...) values. It is called at each time step to allow for updating the relevant fields.
Allows defining complex boundary conditions.
Allows defining complex source terms.
cs_user_postprocess_values (in cs_user_postprocess.c)
May be used to output locally-computed volume or surface values, such as formulas involving fields, or for fine grained association of given fields with different writers.
Allows defining variable physical property (such as fluid density, viscosity ...) values. It is called at each time step to allow for updating the relevant fields.
cs_user_lagr_boundary_conditions and cs_user_lagr_volume_conditions
Allow defining and modifying boundary conditions and volume injections for the Lagrangian particles (dispersed phase).
uscfx1 and uscfx2 (in cs_user_parameters.f90)
Allow setting managing options specific to the compressible model.
cs_user_extra_operations_finalize (in cs_user_extra_operations.c)
Called just after the time stepping/resolution stage, this function allows handling operations required only at the end of the computation (such as some specific post-processing extracts), and possibly cleaning up and freeing structures used in the main cs_user_extra_operations function.
When compiling user sources in a case's SRC directory, the order of compilation is not based on any dependency check. This is not an issue for additional user C or C++ code, but can be an issue for Fortran code with user-defined modules.
If a file named cs_user_modules.f90 is present, it will be compiled before any other Fortran file. So if needed, user-defined modules should be defined in that file, to ensure they are available in other user subroutines.
The main variables and structures reference provides descriptions and recommendations for variables needed in user-defined functions.
1.8.13