My Project
programmer's documentation
|
Go to the source code of this file.
Typedefs | |
typedef struct _cs_sles_t | cs_sles_t |
typedef void() | cs_sles_setup_t(void *context, const char *name, const cs_matrix_t *a, int verbosity) |
Function pointer for pre-resolution setup of a linear system's context. More... | |
typedef cs_sles_convergence_state_t() | cs_sles_solve_t(void *context, const char *name, const cs_matrix_t *a, int verbosity, cs_halo_rotation_t rotation_mode, double precision, double r_norm, int *n_iter, double *residue, const cs_real_t *rhs, cs_real_t *vx, size_t aux_size, void *aux_vectors) |
Function pointer for resolution of a linear system. More... | |
typedef void() | cs_sles_free_t(void *context) |
Function pointer for freeing of a linear system's context data. More... | |
typedef void() | cs_sles_log_t(const void *context, cs_log_t log_type) |
Function pointer for logging of linear solver history and performance data. More... | |
typedef void *() | cs_sles_copy_t(const void *context) |
Function pointer for creation of a solver context based on the copy of another. More... | |
typedef void() | cs_sles_destroy_t(void **context) |
typedef bool() | cs_sles_error_handler_t(cs_sles_t *sles, cs_sles_convergence_state_t state, const cs_matrix_t *a, cs_halo_rotation_t rotation_mode, const cs_real_t *rhs, cs_real_t *vx) |
Function pointer for handling of non-convergence when solving a linear system. More... | |
typedef void() | cs_sles_define_t(int f_id, const char *name, const cs_matrix_t *a) |
Function pointer for the default definition of a sparse linear equation solver. More... | |
typedef int() | cs_sles_verbosity_t(int f_id, const char *name) |
Function pointer for the default definition of a sparse linear equation solver's verbosity. More... | |
Enumerations | |
enum | cs_sles_convergence_state_t { CS_SLES_DIVERGED = -3, CS_SLES_BREAKDOWN = -2, CS_SLES_MAX_ITERATION = -1, CS_SLES_ITERATING = 0, CS_SLES_CONVERGED = 1 } |
Convergence status indicator. More... | |
Functions | |
void | cs_sles_initialize (void) |
Initialize sparse linear equation solver API. More... | |
void | cs_sles_finalize (void) |
Finalize sparse linear equation solver API. More... | |
void | cs_sles_log (cs_log_t log_type) |
Log sparse linear equation solver info. More... | |
cs_sles_t * | cs_sles_find (int f_id, const char *name) |
Return pointer to linear system object, based on matching field id or system name. More... | |
cs_sles_t * | cs_sles_find_or_add (int f_id, const char *name) |
Return pointer to linear system object, based on matching field id or system name. More... | |
void | cs_sles_push (int f_id, const char *name) |
Temporarily replace field id with name for matching calls to cs_sles_setup, cs_sles_solve, cs_sles_free, and other operations involving access through a field id. More... | |
void | cs_sles_pop (int f_id) |
Restore behavior temporarily modified by cs_sles_push. More... | |
cs_sles_t * | cs_sles_define (int f_id, const char *name, void *context, const char *type_name, cs_sles_setup_t *setup_func, cs_sles_solve_t *solve_func, cs_sles_free_t *free_func, cs_sles_log_t *log_func, cs_sles_copy_t *copy_func, cs_sles_destroy_t *destroy_func) |
Define sparse linear equation solver for a given field or equation name. More... | |
void | cs_sles_set_verbosity (cs_sles_t *sles, int verbosity) |
Set the verbosity for a given linear equation solver. More... | |
int | cs_sles_get_verbosity (cs_sles_t *sles) |
Get the verbosity for a given linear equation solver. More... | |
void | cs_sles_set_post_output (cs_sles_t *sles, int writer_id) |
Activate postprocessing output for a given linear equation solver. More... | |
int | cs_sles_get_post_output (cs_sles_t *sles) |
Return the id of the associated writer if postprocessing output is active for a given linear equation solver. More... | |
const char * | cs_sles_get_type (cs_sles_t *sles) |
Return type name of solver context. More... | |
void * | cs_sles_get_context (cs_sles_t *sles) |
Return pointer to solver context structure pointer. More... | |
int | cs_sles_get_f_id (const cs_sles_t *sles) |
Return field id associated with a given sparse linear equation solver. More... | |
const char * | cs_sles_get_name (const cs_sles_t *sles) |
Return name associated with a given sparse linear equation solver. More... | |
void | cs_sles_setup (cs_sles_t *sles, const cs_matrix_t *a) |
Setup sparse linear equation solver. More... | |
cs_sles_convergence_state_t | cs_sles_solve (cs_sles_t *sles, const cs_matrix_t *a, cs_halo_rotation_t rotation_mode, double precision, double r_norm, int *n_iter, double *residue, const cs_real_t *rhs, cs_real_t *vx, size_t aux_size, void *aux_vectors) |
General sparse linear system resolution. More... | |
void | cs_sles_free (cs_sles_t *sles) |
Free sparse linear equation solver setup. More... | |
int | cs_sles_copy (cs_sles_t *dest, const cs_sles_t *src) |
Copy the definition of a sparse linear equation solver to another. More... | |
void | cs_sles_set_error_handler (cs_sles_t *sles, cs_sles_error_handler_t *error_handler_func) |
Associate a convergence error handler to a given sparse linear equation solver. More... | |
cs_sles_define_t * | cs_sles_get_default_define (void) |
Return pointer to default sparse linear solver definition function. More... | |
void | cs_sles_set_default_define (cs_sles_define_t *define_func) |
Set default sparse linear solver definition function. More... | |
void | cs_sles_set_default_verbosity (cs_sles_verbosity_t *verbosity_func) |
Set default verbosity definition function. More... | |
void | cs_sles_post_error_output_def (const char *name, int mesh_id, cs_halo_rotation_t rotation_mode, const cs_matrix_t *a, const cs_real_t *rhs, cs_real_t *vx) |
Output default post-processing data for failed system convergence. More... | |
void | cs_sles_post_output_var (const char *name, int mesh_id, int location_id, int writer_id, int diag_block_size, cs_real_t var[]) |
Output post-processing variable related to system convergence. More... | |
const char * | cs_sles_base_name (int f_id, const char *name) |
Return base name associated to a field id, name couple. More... | |
const char * | cs_sles_name (int f_id, const char *name) |
Return name associated to a field id, name couple. More... | |
cs_sles_copy_t |
Function pointer for creation of a solver context based on the copy of another.
The new context copies the settings of the copied context, but not its setup data and logged info, such as performance data.
This type of function is optional, but enables associating different solvers to related systems (to differentiate logging) while using the same settings by default.
[in] | context | context to copy |
cs_sles_define_t |
Function pointer for the default definition of a sparse linear equation solver.
The function may be associated using cs_sles_set_default_define, so that it may provide a definition that will be used when cs_sles_setup or cs_sles_solve is used for a system for which no matching call to cs_sles_define has been done.
The function should call cs_sles_define with arguments f_id
and name
, and appropriately chosen function pointers.
A pointer to the matrix of the system to be solved is also provided, so that the corresponding information may be used to better choose defaults.
[in] | f_id | associated field id, or < 0 |
[in] | name | associated name if f_id < 0, or NULL |
[in] | a | matrix |
cs_sles_destroy_t |
Function pointer for destruction of a linear system solver context.
This function should free all context data, and will be called for each system when cs_sles_finalize is called.
[in,out] | context | pointer to solver context |
cs_sles_error_handler_t |
Function pointer for handling of non-convergence when solving a linear system.
Such a function is optional, and may be used for a variety of purposes, such as logging, postprocessing, re-trying with different parameters, aborting the run, or any combination thereof.
An error handler may be associated with a given solver context using cs_sles_set_error_handler, in which case it will be called whenever convergence fails.
[in,out] | sles | pointer to solver object |
[in] | status | convergence status |
[in] | a | matrix |
[in] | rotation_mode | Halo update option for rotational periodicity |
[in] | rhs | Right hand side |
[out] | vx | System solution |
cs_sles_free_t |
Function pointer for freeing of a linear system's context data.
Note that this function should free resolution-related data, such as multigrid hierarchy, preconditioning, and any other temporary arrays or objects required for resolution, but should not free the whole context, as info used for logging (especially performance data) should be maintained.
[in,out] | context | pointer to solver context. |
cs_sles_log_t |
Function pointer for logging of linear solver history and performance data.
This function will be called for each solver when cs_sles_finalize is called.
[in] | context | pointer to solver context |
[in] | log_type | log type |
cs_sles_setup_t |
Function pointer for pre-resolution setup of a linear system's context.
This setup may include building a multigrid hierarchy, or a preconditioner.
Use of this type of function is optional: the context is expected to maintain state, so that if a cs_sles_solve_t function is called before a cs_sles_setup_t function, the latter will be called automatically.
[in,out] | context | pointer to solver context |
[in] | name | pointer to name of linear system |
[in] | a | matrix |
[in] | verbosity | associated verbosity |
cs_sles_solve_t |
Function pointer for resolution of a linear system.
If the associated cs_sles_setup_t function has not been called before this function, it will be called automatically.
The solution context setup by this call (or that of the matching cs_sles_setup_t function) will be maintained until the matching cs_sles_free_t function is called.
The matrix is not expected to change between successive calls, although the right hand side may. If the matrix changes, the associated cs_sles_setup_t or cs_sles_free_t function must be called between solves.
The system is considered to have converged when residue/r_norm <= precision, residue being the L2 norm of a.vx-rhs.
[in,out] | context | pointer to solver context |
[in] | name | pointer to name of linear system |
[in] | a | matrix |
[in] | verbosity | associated verbosity |
[in] | rotation_mode | halo update option for rotational periodicity |
[in] | precision | solver precision |
[in] | r_norm | residue normalization |
[out] | n_iter | number of "equivalent" iterations |
[out] | residue | residue |
[in] | rhs | right hand side |
[out] | vx | system solution |
[in] | aux_size | number of elements in aux_vectors |
aux_vectors | optional working area (internal allocation if NULL) |
typedef struct _cs_sles_t cs_sles_t |
cs_sles_verbosity_t |
Function pointer for the default definition of a sparse linear equation solver's verbosity.
The function may be associated using cs_sles_set_default_verbosity, so that it may provide a definition that will be used when cs_sles_find_or_add is called.
[in] | f_id | associated field id, or < 0 |
[in] | name | associated name if f_id < 0, or NULL |
Convergence status indicator.
const char* cs_sles_base_name | ( | int | f_id, |
const char * | name | ||
) |
Return base name associated to a field id, name couple.
This is simply a utility function which will return its name argument if f_id < 0, and the associated field's name or label otherwise.
[in] | f_id | associated field id, or < 0 |
[in] | name | associated name if f_id < 0, or NULL |
This is simply a utility function which will return its name argument if f_id < 0, and the associated field's name or label otherwise.
[in] | f_id | associated field id, or < 0 |
[in] | name | associated name if f_id < 0, or NULL |
Copy the definition of a sparse linear equation solver to another.
The intended use of this function is to allow associating different solvers to related systems, so as to differentiate logging, while using the same settings by default.
If the source solver does not provide a cs_sles_copy_t function, No modification is done to the solver. If the copy function is available, the context is copied, as are the matching function pointers.
If previous settings have been defined and used, they are saved as per cs_sles_define.
[in,out] | dest | pointer to destination solver object |
[in] | src | pointer to source solver object |
cs_sles_t* cs_sles_define | ( | int | f_id, |
const char * | name, | ||
void * | context, | ||
const char * | type_name, | ||
cs_sles_setup_t * | setup_func, | ||
cs_sles_solve_t * | solve_func, | ||
cs_sles_free_t * | free_func, | ||
cs_sles_log_t * | log_func, | ||
cs_sles_copy_t * | copy_func, | ||
cs_sles_destroy_t * | destroy_func | ||
) |
Define sparse linear equation solver for a given field or equation name.
If this system did not previously exist, it is added to the list of "known" systems.
The context pointer is used to point to a structure adapted to the function pointers given here, and combined with those functions, allows using both built-in, external, or user-defined solvers.
It is recommended the context type name provided here directly relate to the associated structure type (for example, "cs_sles_it_t" or "cs_multigrid_t").
[in] | f_id | associated field id, or < 0 |
[in] | name | associated name if f_id < 0, or NULL |
[in,out] | context | pointer to solver context management structure (cs_sles subsystem becomes owner) |
[in] | type_name | context structure or object type name |
[in] | setup_func | pointer to system setup function |
[in] | solve_func | pointer to system solution function (also calls setup_func if not done yet or free_func called since last solve) |
[in] | free_func | pointer function freeing system setup |
[in] | log_func | pointer to system info logging function (optional, but recommended) |
[in] | copy_func | pointer to settings copy function (optional) |
[in] | destroy_func | pointer to function destroying solver context (called with cs_sles_finalize or with a new call to this function for the same system) |
void cs_sles_finalize | ( | void | ) |
Finalize sparse linear equation solver API.
cs_sles_t* cs_sles_find | ( | int | f_id, |
const char * | name | ||
) |
Return pointer to linear system object, based on matching field id or system name.
If this system did not previously exist, NULL is returned.
[in] | f_id | associated field id, or < 0 |
[in] | name | associated name if f_id < 0, or NULL |
cs_sles_t* cs_sles_find_or_add | ( | int | f_id, |
const char * | name | ||
) |
Return pointer to linear system object, based on matching field id or system name.
If this system did not previously exist, it is created and added to to the list of "known" systems. In this case, it will be usable only if cs_sles_define() is called for the same field id and name (in which case calling the present function is redundant), or if cs_sles_set_sefault_define() has been previously used to define the default solver policy.
[in] | f_id | associated field id, or < 0 |
[in] | name | associated name if f_id < 0, or NULL |
void cs_sles_free | ( | cs_sles_t * | sles | ) |
Free sparse linear equation solver setup.
This function frees resolution-related data, such as multigrid hierarchy, preconditioning, and any other temporary arrays or objects required for resolution, but maintains context information such as that used for logging (especially performance data).
[in,out] | sles | pointer to solver object |
void* cs_sles_get_context | ( | cs_sles_t * | sles | ) |
Return pointer to solver context structure pointer.
The context structure depends on the type of solver used, which may in turn be determined by the string returned by cs_sles_get_type(). If may be used by appropriate functions specific to that type.
[in] | sles | pointer to solver object |
cs_sles_define_t* cs_sles_get_default_define | ( | void | ) |
Return pointer to default sparse linear solver definition function.
The associated function will be used to provide a definition when cs_sles_setup or cs_sles_solve is used for a system for which no matching call to cs_sles_define has been done.
int cs_sles_get_f_id | ( | const cs_sles_t * | sles | ) |
Return field id associated with a given sparse linear equation solver.
[in] | sles | pointer to solver object |
const char* cs_sles_get_name | ( | const cs_sles_t * | sles | ) |
Return name associated with a given sparse linear equation solver.
This is simply a utility function which will return its name argument if f_id < 0, and the associated field's name or label otherwise.
[in] | sles | pointer to solver object |
int cs_sles_get_post_output | ( | cs_sles_t * | sles | ) |
Return the id of the associated writer if postprocessing output is active for a given linear equation solver.
[in] | sles | pointer to solver object |
const char* cs_sles_get_type | ( | cs_sles_t * | sles | ) |
Return type name of solver context.
The returned string is intended to help determine which type is associated with the void * pointer returned by cs_sles_get_context for a given solver definition, so as to be able to call additional specific functions beyond the generic functions assigned to a cs_sles_t object.
If no type_name string was associated to the solver upon its definition by cs_sles_define, or it has not been defined yet, the string returned is "<undefined>". It is recommended the type name provided cs_sles_define directly relate to the associated structure type (for example, "cs_sles_it_t" or "cs_multigrid_t").
[in] | sles | pointer to solver object |
int cs_sles_get_verbosity | ( | cs_sles_t * | sles | ) |
Get the verbosity for a given linear equation solver.
This verbosity will be used by cs_sles_setup and cs_sles_solve.
[in,out] | sles | pointer to solver object |
void cs_sles_initialize | ( | void | ) |
Initialize sparse linear equation solver API.
void cs_sles_log | ( | cs_log_t | log_type | ) |
Log sparse linear equation solver info.
[in] | log_type | log type (CS_LOG_SETUP or CS_LOG_PERFORMANCE) |
const char* cs_sles_name | ( | int | f_id, |
const char * | name | ||
) |
Return name associated to a field id, name couple.
[in] | f_id | associated field id, or < 0 |
[in] | name | associated name if f_id < 0, or NULL |
void cs_sles_pop | ( | int | f_id | ) |
Restore behavior temporarily modified by cs_sles_push.
[in] | f_id | associated field id, or < 0 |
[in] | f_id | associated field id, or < 0 |
void cs_sles_post_error_output_def | ( | const char * | name, |
int | mesh_id, | ||
cs_halo_rotation_t | rotation_mode, | ||
const cs_matrix_t * | a, | ||
const cs_real_t * | rhs, | ||
cs_real_t * | vx | ||
) |
Output default post-processing data for failed system convergence.
[in] | name | variable name |
[in] | mesh_id | id of error output mesh, or 0 if none |
[in] | rotation_mode | halo update option for rotational periodicity |
[in] | a | linear equation matrix |
[in] | rhs | right hand side |
[in,out] | vx | current system solution |
void cs_sles_post_output_var | ( | const char * | name, |
int | mesh_id, | ||
int | location_id, | ||
int | writer_id, | ||
int | diag_block_size, | ||
cs_real_t | var[] | ||
) |
Output post-processing variable related to system convergence.
[in] | name | variable name |
[in] | mesh_id | id of error output mesh, or 0 if none |
[in] | location_id | mesh location id (cells or vertices) |
[in] | writer_id | id of specified associated writer, or CS_POST_WRITER_ALL_ASSOCIATED for all |
[in] | diag_block_size | block size for diagonal |
[in,out] | var | variable values |
void cs_sles_push | ( | int | f_id, |
const char * | name | ||
) |
Temporarily replace field id with name for matching calls to cs_sles_setup, cs_sles_solve, cs_sles_free, and other operations involving access through a field id.
ivar
value, but specific solver options must still be set. In the future, a more consistent mechanism (using a zero ivar
value or designing a cleaner method to handle those exceptional cases) is preferred. As such, only a stack depth of 1 is allowed.[in] | f_id | associated field id, or < 0 |
[in] | name | associated name if f_id < 0, or NULL |
ivar
value, but specific solver options must still be set. In the future, a more consistent mechanism (using a zero ivar
value or designing a cleaner method to handle those exceptional cases) is preferred. As such, only a stack depth of 1 is allowed.[in] | f_id | associated field id, or < 0 |
[in] | name | associated name if f_id < 0, or NULL |
void cs_sles_set_default_define | ( | cs_sles_define_t * | define_func | ) |
Set default sparse linear solver definition function.
The provided function will be used to provide a definition when cs_sles_setup or cs_sles_solve is used for a system for which no matching call to cs_sles_define has been done.
[in] | define_func | pointer to default definition function |
void cs_sles_set_default_verbosity | ( | cs_sles_verbosity_t * | verbosity_func | ) |
Set default verbosity definition function.
The provided function will be used to define the verbosity when cs_sles_find_or_add is called.
[in] | verbosity_func | pointer to default verbosity function |
void cs_sles_set_error_handler | ( | cs_sles_t * | sles, |
cs_sles_error_handler_t * | error_handler_func | ||
) |
Associate a convergence error handler to a given sparse linear equation solver.
The error will be called whenever convergence fails. To dissassociate the error handler, this function may be called with handler
= NULL.
The association will only be successful if the matching solver has already been defined.
[in,out] | sles | pointer to solver object |
[in] | error_handler_func | pointer to convergence error handler function |
void cs_sles_set_post_output | ( | cs_sles_t * | sles, |
int | writer_id | ||
) |
Activate postprocessing output for a given linear equation solver.
This allows the output of the residual at the end of each solution series, using a single postprocessing writer. By default, no output is activated.
[in,out] | sles | pointer to solver object |
[in] | writer_id | id of the writer |
void cs_sles_set_verbosity | ( | cs_sles_t * | sles, |
int | verbosity | ||
) |
Set the verbosity for a given linear equation solver.
This verbosity will be used by cs_sles_setup and cs_sles_solve.
By default, the verbosity is set to 0, or the value returned by the function set with cs_sles_set_default_define().
[in,out] | sles | pointer to solver object |
[in] | verbosity | verbosity level |
void cs_sles_setup | ( | cs_sles_t * | sles, |
const cs_matrix_t * | a | ||
) |
Setup sparse linear equation solver.
Use of this function is optional: if a cs_sles_solve is called for the same system before this function is called, the latter will be called automatically.
If no options were previously provided for the matching system, default options will be used.
[in,out] | sles | pointer to solver object |
[in] | a | matrix |
cs_sles_convergence_state_t cs_sles_solve | ( | cs_sles_t * | sles, |
const cs_matrix_t * | a, | ||
cs_halo_rotation_t | rotation_mode, | ||
double | precision, | ||
double | r_norm, | ||
int * | n_iter, | ||
double * | residue, | ||
const cs_real_t * | rhs, | ||
cs_real_t * | vx, | ||
size_t | aux_size, | ||
void * | aux_vectors | ||
) |
General sparse linear system resolution.
If no options were previously provided for the matching system, default options will be used.
Note that if cs_sles_setup was previously called for this system, and cs_sles_free has not been called since, the matrix provided should be the same. The optional separation between the two stages is intended to allow amortizing the cost of setup over multiple solutions.
The system is considered to have converged when residue/r_norm <= precision, residue being the L2 norm of a.vx-rhs.
[in,out] | sles | pointer to solver object |
[in] | a | matrix |
[in] | rotation_mode | halo update option for rotational periodicity |
[in] | precision | solver precision |
[in] | r_norm | residue normalization |
[out] | n_iter | number of "equivalent" iterations |
[out] | residue | residue |
[in] | rhs | right hand side |
[in,out] | vx | system solution |
[in] | aux_size | size of aux_vectors (in bytes) |
aux_vectors | optional working area (internal allocation if NULL) |