cs_sles.c File Reference

Sparse linear equation solver driver. More...

#include "cs_defs.h"
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <assert.h>
#include <math.h>
#include "bft_mem.h"
#include "bft_error.h"
#include "bft_printf.h"
#include "cs_base.h"
#include "cs_blas.h"
#include "cs_field.h"
#include "cs_log.h"
#include "cs_halo.h"
#include "cs_map.h"
#include "cs_mesh.h"
#include "cs_mesh_location.h"
#include "cs_matrix.h"
#include "cs_matrix_default.h"
#include "cs_matrix_util.h"
#include "cs_parall.h"
#include "cs_post.h"
#include "cs_timer.h"
#include "cs_timer_stats.h"
#include "cs_time_step.h"
#include "cs_sles.h"

Include dependency graph for cs_sles.c:

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

Detailed Description

Sparse linear equation solver driver.

Sparse linear equation solver preconditioner driver and simple preconditioners.

The Sparse Linear Equation Solver subsystem is designed to allow both simple usage of built-in solvers, and plugging of solvers from external libraries.

As the options associated with different solvers may be very varied, this subsystem is based on the use of a series of callback functions which may be associated with a given linear system (defined either by field id for quick and recurrent access, or by unique system name). It is possible to provide a default function so calls for the resolution of systems not specified before can be handled.

To summarize, the functions here define a linear system solver driver, with the real work being done by functions bound to this model. The main intent is to help manage passing varied user options to the solvers, and handling consistency of logging.

As the options associated with different preconditioners may be very varied, this subsystem is based on the use of a series of callback functions which may be associated with a given preconditioner.

To summarize, the functions here define a preconditioner driver, with the real work being done by functions bound to this model. The main intent is to help manage passing varied user options to the preconditioners, and handling consistency of logging.

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_id	associated field id, or < 0
[in]	name	associated 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]	dest	pointer to destination solver object
[in]	src	pointer 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_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)

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_id	associated field id, or < 0
[in]	name	associated 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_id	associated field id, or < 0
[in]	name	associated 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]

sles

pointer 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]

sles

pointer 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]

sles

pointer 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]

sles

pointer 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]

sles

pointer 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]

sles

pointer 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]

sles

pointer 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_type

log 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_id	associated field id, or < 0
[in]	name	associated 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_id

associated field id, or < 0

cs_sles_post_error_output_def()

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.

Parameters

[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

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]	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

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_c_bindings::codits (codits) 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_id	associated field id, or < 0
[in]	name	associated 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_func

pointer 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_func

pointer 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]	sles	pointer to solver object
[in]	error_handler_func	pointer 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]	sles	pointer to solver object
[in]	writer_id	id 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]	sles	pointer to solver object
[in]	verbosity	verbosity 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]	sles	pointer to solver object
[in]	a	matrix

cs_sles_solve()

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.

Parameters

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

Returns

convergence state