7.1
general documentation
cs_sles.h File Reference
#include "cs_base.h"
#include "cs_log.h"
#include "cs_halo_perio.h"
#include "cs_matrix.h"
+ Include dependency graph for cs_sles.h:

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, 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, 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_tcs_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_tcs_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_tcs_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, 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_tcs_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, 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...
 

Typedef Documentation

◆ cs_sles_copy_t

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.

Parameters
[in]contextcontext to copy
Returns
pointer to newly created context

◆ cs_sles_define_t

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.

Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL
[in]amatrix

◆ cs_sles_destroy_t

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.

Parameters
[in,out]contextpointer to solver context

◆ cs_sles_error_handler_t

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.

Parameters
[in,out]slespointer to solver object
[in]statusconvergence status
[in]amatrix
[in]rhsRight hand side
[out]vxSystem solution
Returns
true if solve should be re-executed, false otherwise

◆ cs_sles_free_t

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.

Parameters
[in,out]contextpointer to solver context.

◆ cs_sles_log_t

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.

Parameters
[in]contextpointer to solver context
[in]log_typelog type

◆ cs_sles_setup_t

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.

Parameters
[in,out]contextpointer to solver context
[in]namepointer to name of linear system
[in]amatrix
[in]verbosityassociated verbosity

◆ cs_sles_solve_t

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.

Parameters
[in,out]contextpointer to solver context
[in]namepointer to name of linear system
[in]amatrix
[in]verbosityassociated verbosity
[in]precisionsolver precision
[in]r_normresidue normalization
[out]n_iternumber of "equivalent" iterations
[out]residueresidue
[in]rhsright hand side
[out]vxsystem solution
[in]aux_sizenumber of elements in aux_vectors
aux_vectorsoptional working area (internal allocation if NULL)
Returns
convergence status

◆ cs_sles_t

typedef struct _cs_sles_t cs_sles_t

◆ cs_sles_verbosity_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.

Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL
Returns
default verbosity value

Enumeration Type Documentation

◆ cs_sles_convergence_state_t

Convergence status indicator.

Enumerator
CS_SLES_DIVERGED 

The solver has diverged

CS_SLES_BREAKDOWN 

The solver has broken down, and cannot make any more progress

CS_SLES_MAX_ITERATION 

Maximum number of iterations has been reached, without reaching the required convergence

CS_SLES_ITERATING 

The solver is iterating

CS_SLES_CONVERGED 

The solver has converged

The preconditioner has converged

Function Documentation

◆ cs_sles_base_name()

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.

Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL
Returns
pointer to associated linear system object, 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.

Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL
Returns
pointer to base name associated to the field id, name couple

◆ cs_sles_copy()

int cs_sles_copy ( cs_sles_t dest,
const cs_sles_t src 
)

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.

Parameters
[in,out]destpointer to destination solver object
[in]srcpointer to source solver object
Returns
0 in case of success, 1 in case of failure

◆ cs_sles_define()

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").

Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL
[in,out]contextpointer to solver context management structure (cs_sles subsystem becomes owner)
[in]type_namecontext structure or object type name
[in]setup_funcpointer to system setup function
[in]solve_funcpointer to system solution function (also calls setup_func if not done yet or free_func called since last solve)
[in]free_funcpointer function freeing system setup
[in]log_funcpointer to system info logging function (optional, but recommended)
[in]copy_funcpointer to settings copy function (optional)
[in]destroy_funcpointer to function destroying solver context (called with cs_sles_finalize or with a new call to this function for the same system)
Returns
pointer to associated linear system object

◆ cs_sles_finalize()

void cs_sles_finalize ( void  )

Finalize sparse linear equation solver API.

◆ cs_sles_find()

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.

Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL
Returns
pointer to associated linear system object, or NULL

◆ cs_sles_find_or_add()

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.

Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL
Returns
pointer to associated linear system object, or NULL

◆ cs_sles_free()

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).

Parameters
[in,out]slespointer to solver object

◆ cs_sles_get_context()

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.

Parameters
[in]slespointer to solver object
Returns
pointer to solver-specific linear system info and context

◆ cs_sles_get_default_define()

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.

Returns
define_func pointer to default definition function

◆ cs_sles_get_f_id()

int cs_sles_get_f_id ( const cs_sles_t sles)

Return field id associated with a given sparse linear equation solver.

Parameters
[in]slespointer to solver object
Returns
associated field id (or -1 if defined by name)

◆ cs_sles_get_name()

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.

Parameters
[in]slespointer to solver object
Returns
pointer to associated linear system object name

◆ cs_sles_get_post_output()

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.

Parameters
[in]slespointer to solver object
Returns
id od associated writer, or 0

◆ cs_sles_get_type()

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").

Parameters
[in]slespointer to solver object
Returns
pointer to linear system solver specific type name

◆ cs_sles_get_verbosity()

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.

Parameters
[in,out]slespointer to solver object
Returns
verbosity level

◆ cs_sles_initialize()

void cs_sles_initialize ( void  )

Initialize sparse linear equation solver API.

◆ cs_sles_log()

void cs_sles_log ( cs_log_t  log_type)

Log sparse linear equation solver info.

Parameters
[in]log_typelog type (CS_LOG_SETUP or CS_LOG_PERFORMANCE)

◆ cs_sles_name()

const char* cs_sles_name ( int  f_id,
const char *  name 
)

Return name associated to a field id, name couple.

Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL
Returns
pointer to name associated to the field id, name couple

◆ cs_sles_pop()

void cs_sles_pop ( int  f_id)

Restore behavior temporarily modified by cs_sles_push.

Deprecated:
This function matches cs_sles_push, which is deprecated.
Parameters
[in]f_idassociated field id, or < 0
Deprecated:
This function matches cs_sles_push, which is deprecated.
Parameters
[in]f_idassociated field id, or < 0

◆ cs_sles_post_error_output_def()

void cs_sles_post_error_output_def ( const char *  name,
int  mesh_id,
const cs_matrix_t a,
const cs_real_t rhs,
cs_real_t vx 
)

Output default post-processing data for failed system convergence.

Parameters
[in]namevariable name
[in]mesh_idid of error output mesh, or 0 if none
[in]alinear equation matrix
[in]rhsright hand side
[in,out]vxcurrent system solution

◆ cs_sles_post_output_var()

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.

Parameters
[in]namevariable name
[in]mesh_idid of error output mesh, or 0 if none
[in]location_idmesh location id (cells or vertices)
[in]writer_idid of specified associated writer, or CS_POST_WRITER_ALL_ASSOCIATED for all
[in]diag_block_sizeblock size for diagonal
[in,out]varvariable values

◆ cs_sles_push()

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.

Deprecated:
This function is provided to allow some peculiar calling sequences, in which cs_equation_iterative_solve_scalar is called with a nonzero 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.
Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL
Deprecated:
This function is provided to allow some peculiar calling sequences, in which cs_equation_iterative_solve_scalar is called with a nonzero 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.
Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL

◆ cs_sles_set_default_define()

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.

Parameters
[in]define_funcpointer to default definition function

◆ cs_sles_set_default_verbosity()

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.

Parameters
[in]verbosity_funcpointer to default verbosity function

◆ cs_sles_set_error_handler()

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.

Parameters
[in,out]slespointer to solver object
[in]error_handler_funcpointer to convergence error handler function

◆ cs_sles_set_post_output()

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.

Parameters
[in,out]slespointer to solver object
[in]writer_idid of the writer

◆ cs_sles_set_verbosity()

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().

Parameters
[in,out]slespointer to solver object
[in]verbosityverbosity level

◆ cs_sles_setup()

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.

Parameters
[in,out]slespointer to solver object
[in]amatrix

◆ cs_sles_solve()

cs_sles_convergence_state_t cs_sles_solve ( cs_sles_t sles,
const cs_matrix_t a,
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.

Parameters
[in,out]slespointer to solver object
[in]amatrix
[in]precisionsolver precision
[in]r_normresidue normalization
[out]n_iternumber of "equivalent" iterations
[out]residueresidue
[in]rhsright hand side
[in,out]vxsystem solution
[in]aux_sizesize of aux_vectors (in bytes)
aux_vectorsoptional working area (internal allocation if NULL)
Returns
convergence state