programmer's documentation
Typedefs | Enumerations | Functions | Variables
cs_sles_it.h File Reference
#include "cs_base.h"
#include "cs_halo_perio.h"
#include "cs_matrix.h"
#include "cs_time_plot.h"
#include "cs_sles.h"
#include "cs_sles_pc.h"
Include dependency graph for cs_sles_it.h:

Go to the source code of this file.

Typedefs

typedef struct _cs_sles_it_t cs_sles_it_t
 

Enumerations

enum  cs_sles_it_type_t {
  CS_SLES_PCG, CS_SLES_JACOBI, CS_SLES_BICGSTAB, CS_SLES_BICGSTAB2,
  CS_SLES_GMRES, CS_SLES_P_GAUSS_SEIDEL, CS_SLES_PCR3, CS_SLES_N_IT_TYPES
}
 Iterative solver types. More...
 

Functions

cs_sles_it_tcs_sles_it_define (int f_id, const char *name, cs_sles_it_type_t solver_type, int poly_degree, int n_max_iter)
 Define and associate an iterative sparse linear system solver for a given field or equation name. More...
 
cs_sles_it_tcs_sles_it_create (cs_sles_it_type_t solver_type, int poly_degree, int n_max_iter, bool update_stats)
 Create iterative sparse linear system solver info and context. More...
 
void cs_sles_it_destroy (void **context)
 Destroy iterative sparse linear system solver info and context. More...
 
void * cs_sles_it_copy (const void *context)
 Create iterative sparse linear system solver info and context based on existing info and context. More...
 
void cs_sles_it_setup (void *context, const char *name, const cs_matrix_t *a, int verbosity)
 Setup iterative sparse linear equation solver. More...
 
cs_sles_convergence_state_t cs_sles_it_solve (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)
 Call iterative sparse linear equation solver. More...
 
void cs_sles_it_free (void *context)
 Free iterative sparse linear equation solver setup context. More...
 
void cs_sles_it_log (const void *context, cs_log_t log_type)
 Log sparse linear equation solver info. More...
 
cs_sles_it_type_t cs_sles_it_get_type (const cs_sles_it_t *context)
 Return iterative solver type. More...
 
double cs_sles_it_get_last_initial_residue (const cs_sles_it_t *context)
 Return the initial residue for the previous solve operation with a solver. More...
 
cs_sles_pc_tcs_sles_it_get_pc (cs_sles_it_t *context)
 Return a preconditioner context for an iterative sparse linear equation solver. More...
 
void cs_sles_it_transfer_pc (cs_sles_it_t *context, cs_sles_pc_t **pc)
 Assign a preconditioner to an iterative sparse linear equation solver, transfering its ownership to to solver context. More...
 
void cs_sles_it_set_shareable (cs_sles_it_t *context, const cs_sles_it_t *shareable)
 Associate a similar info and context object with which some setup data may be shared. More...
 
void cs_sles_it_assign_order (cs_sles_it_t *context, cs_lnum_t **order)
 Assign ordering to iterative solver. More...
 
void cs_sles_it_set_symmetric (cs_sles_it_t *context, bool symmetric)
 Assign symmetric option to iterative solver. More...
 
cs_lnum_t cs_sles_it_get_pcg_single_reduction (void)
 Query mean number of rows under which Conjugate Gradient algorithm uses the single-reduction variant. More...
 
void cs_sles_it_set_pcg_single_reduction (cs_lnum_t threshold)
 Set mean number of rows under which Conjugate Gradient algorithm should use the single-reduction variant. More...
 
void cs_sles_it_log_parallel_options (void)
 Log the current global settings relative to parallelism. More...
 
void cs_sles_it_error_post_and_abort (void *context, cs_sles_convergence_state_t state, const char *name, const cs_matrix_t *a, cs_halo_rotation_t rotation_mode, const cs_real_t *rhs, cs_real_t *vx)
 Error handler for iterative sparse linear equation solver. More...
 
void cs_sles_it_set_plot_options (cs_sles_it_t *context, const char *base_name, bool use_iteration)
 Set plotting options for an iterative sparse linear equation solver. More...
 
void cs_sles_it_assign_plot (cs_sles_it_t *context, cs_time_plot_t *time_plot, int time_stamp)
 Assign existing time plot to iterative sparse linear equation solver. More...
 

Variables

const char * cs_sles_it_type_name []
 

Typedef Documentation

typedef struct _cs_sles_it_t cs_sles_it_t

Enumeration Type Documentation

Iterative solver types.

Enumerator
CS_SLES_PCG 

Preconditioned conjugate gradient

CS_SLES_JACOBI 

Jacobi

CS_SLES_BICGSTAB 

Preconditioned BiCGstab (biconjugate gradient stabilized)

CS_SLES_BICGSTAB2 

Preconditioned BiCGstab2 (biconjugate gradient stabilized)

CS_SLES_GMRES 

Preconditioned GMRES (generalized minimum residual)

CS_SLES_P_GAUSS_SEIDEL 

Process-local Gauss-Seidel

CS_SLES_PCR3 

3-layer conjugate residual

CS_SLES_N_IT_TYPES 

Function Documentation

void cs_sles_it_assign_order ( cs_sles_it_t context,
cs_lnum_t **  order 
)

Assign ordering to iterative solver.

The solver context takes ownership of the order array (i.e. it will handle its later deallocation).

This is useful only for Process-local Gauss-Seidel.

Parameters
[in,out]contextpointer to iterative solver info and context
[in,out]orderpointer to ordering array
void cs_sles_it_assign_plot ( cs_sles_it_t context,
cs_time_plot_t time_plot,
int  time_stamp 
)

Assign existing time plot to iterative sparse linear equation solver.

This is useful mainly when a time plot has a longer lifecycle than the linear solver context, such as inside a multigrid solver.

Parameters
[in,out]contextpointer to iterative solver info and context
[in]time_plotpointer to time plot structure
[in]time_stampassociated time stamp
void* cs_sles_it_copy ( const void *  context)

Create iterative sparse linear system solver info and context based on existing info and context.

Parameters
[in]contextpointer to reference info and context (actual type: cs_sles_it_t *)
Returns
pointer to newly created solver info object. (actual type: cs_sles_it_t *)
cs_sles_it_t* cs_sles_it_create ( cs_sles_it_type_t  solver_type,
int  poly_degree,
int  n_max_iter,
bool  update_stats 
)

Create iterative sparse linear system solver info and context.

Parameters
[in]solver_typetype of solver (PCG, Jacobi, ...)
[in]poly_degreepreconditioning polynomial degree (0: diagonal; -1: non-preconditioned; see Iterative linear solvers. for details)
[in]n_max_itermaximum number of iterations
[in]update_statsautomatic solver statistics indicator
Returns
pointer to newly created solver info object.
cs_sles_it_t* cs_sles_it_define ( int  f_id,
const char *  name,
cs_sles_it_type_t  solver_type,
int  poly_degree,
int  n_max_iter 
)

Define and associate an iterative sparse linear system solver for a given field or equation name.

If this system did not previously exist, it is added to the list of "known" systems. Otherwise, its definition is replaced by the one defined here.

This is a utility function: if finer control is needed, see cs_sles_define and cs_sles_it_create.

Note that this function returns a pointer directly to the iterative solver management structure. This may be used to set further options, for example using cs_sles_it_set_plot_options. If needed, cs_sles_find may be used to obtain a pointer to the matching cs_sles_t container.

Parameters
[in]f_idassociated field id, or < 0
[in]nameassociated name if f_id < 0, or NULL
[in]solver_typetype of solver (PCG, Jacobi, ...)
[in]poly_degreepreconditioning polynomial degree (0: diagonal; -1: non-preconditioned)
[in]n_max_itermaximum number of iterations
Returns
pointer to newly created iterative solver info object.
void cs_sles_it_destroy ( void **  context)

Destroy iterative sparse linear system solver info and context.

Parameters
[in,out]contextpointer to iterative solver info and context (actual type: cs_sles_it_t **)
void cs_sles_it_error_post_and_abort ( void *  context,
cs_sles_convergence_state_t  state,
const char *  name,
const cs_matrix_t a,
cs_halo_rotation_t  rotation_mode,
const cs_real_t rhs,
cs_real_t vx 
)

Error handler for iterative sparse linear equation solver.

In case of divergence or breakdown, this error handler outputs postprocessing data to assist debugging, then aborts the run. It does nothing in case the maximum iteration count is reached.

Parameters
[in,out]contextpointer to iterative solver info and context (actual type: cs_sles_it_t *)
[in]stateconvergence state
[in]namepointer to name of linear system
[in]amatrix
[in]rotation_modehalo update option for rotational periodicity
[in]rhsright hand side
[in,out]vxsystem solution
void cs_sles_it_free ( void *  context)

Free iterative sparse linear equation solver setup context.

This function frees resolution-related data, such as buffers and preconditioning but does not free the whole context, as info used for logging (especially performance data) is maintained.

Parameters
[in,out]contextpointer to iterative solver info and context (actual type: cs_sles_it_t *)
double cs_sles_it_get_last_initial_residue ( const cs_sles_it_t context)

Return the initial residue for the previous solve operation with a solver.

This is useful for convergence tests when this solver is used as a preconditioning smoother.

This operation is only valid between calls to cs_sles_it_setup (or cs_sles_it_solve) and cs_sles_it_free. It returns -1 otherwise.

Parameters
[in]contextpointer to iterative solver info and context
Returns
initial residue from last call to cs_sles_solve with this solver
cs_sles_pc_t* cs_sles_it_get_pc ( cs_sles_it_t context)

Return a preconditioner context for an iterative sparse linear equation solver.

This allows modifying parameters of a non default (Jacobi or polynomial) preconditioner.

Parameters
[in]contextpointer to iterative solver info and context
Returns
pointer to preconditoner context
cs_lnum_t cs_sles_it_get_pcg_single_reduction ( void  )

Query mean number of rows under which Conjugate Gradient algorithm uses the single-reduction variant.

The single-reduction variant requires only one parallel sum per iteration (instead of 2), at the cost of additional vector operations, so it tends to be more expensive when the number of matrix rows per MPI rank is high, then becomes cheaper when the MPI latency cost becomes more significant.

This option is ignored for non-parallel runs, so 0 is returned.

Returns
mean number of rows per active rank under which the single-reduction variant will be used
cs_sles_it_type_t cs_sles_it_get_type ( const cs_sles_it_t context)

Return iterative solver type.

Parameters
[in]contextpointer to iterative solver info and context
Returns
selected solver type
void cs_sles_it_log ( const void *  context,
cs_log_t  log_type 
)

Log sparse linear equation solver info.

Parameters
[in]contextpointer to iterative solver info and context (actual type: cs_sles_it_t *)
[in]log_typelog type
void cs_sles_it_log_parallel_options ( void  )

Log the current global settings relative to parallelism.

void cs_sles_it_set_pcg_single_reduction ( cs_lnum_t  threshold)

Set mean number of rows under which Conjugate Gradient algorithm should use the single-reduction variant.

The single-reduction variant requires only one parallel sum per iteration (instead of 2), at the cost of additional vector operations, so it tends to be more expensive when the number of matrix rows per MPI rank is high, then becomes cheaper when the MPI latency cost becomes more significant.

This option is ignored for non-parallel runs.

Parameters
[in]thresholdmean number of rows per active rank under which the single-reduction variant will be used
void cs_sles_it_set_plot_options ( cs_sles_it_t context,
const char *  base_name,
bool  use_iteration 
)

Set plotting options for an iterative sparse linear equation solver.

Parameters
[in,out]contextpointer to iterative solver info and context
[in]base_namebase plot name to activate, NULL otherwise
[in]use_iterationif true, use iteration as time stamp otherwise, use wall clock time
void cs_sles_it_set_shareable ( cs_sles_it_t context,
const cs_sles_it_t shareable 
)

Associate a similar info and context object with which some setup data may be shared.

This is especially useful for sharing preconditioning data between similar solver contexts (for example ascending and descending multigrid smoothers based on the same matrix).

For preconditioning data to be effectively shared, cs_sles_it_setup (or cs_sles_it_solve) must be called on shareable before being called on context (without cs_sles_it_free being called in between, of course).

It is the caller's responsibility to ensure the context is not used for a cs_sles_it_setup or cs_sles_it_solve operation after the shareable object has been destroyed (normally by cs_sles_it_destroy).

Parameters
[in,out]contextpointer to iterative solver info and context
[in]shareablepointer to iterative solver info and context whose context may be shared
void cs_sles_it_set_symmetric ( cs_sles_it_t context,
bool  symmetric 
)

Assign symmetric option to iterative solver.

This is useful only for Process-local Gauss-Seidel.

Parameters
[in,out]contextpointer to iterative solver info and context
[in]symmetricsymmetric if true
void cs_sles_it_setup ( void *  context,
const char *  name,
const cs_matrix_t a,
int  verbosity 
)

Setup iterative sparse linear equation solver.

Parameters
[in,out]contextpointer to iterative solver info and context (actual type: cs_sles_it_t *)
[in]namepointer to system name
[in]aassociated matrix
[in]verbosityassociated verbosity
cs_sles_convergence_state_t cs_sles_it_solve ( 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 
)

Call iterative sparse linear equation solver.

Parameters
[in,out]contextpointer to iterative solver info and context (actual type: cs_sles_it_t *)
[in]namepointer to system name
[in]amatrix
[in]verbosityassociated verbosity
[in]rotation_modehalo update option for rotational periodicity
[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_sizenumber of elements in aux_vectors (in bytes)
aux_vectorsoptional working area (internal allocation if NULL)
Returns
convergence state
void cs_sles_it_transfer_pc ( cs_sles_it_t context,
cs_sles_pc_t **  pc 
)

Assign a preconditioner to an iterative sparse linear equation solver, transfering its ownership to to solver context.

This allows assigning a non default (Jacobi or polynomial) preconditioner.

The input pointer is set to NULL to make it clear the caller does not own the preconditioner anymore, though the context can be accessed using cs_sles_it_get_pc.

Parameters
[in,out]contextpointer to iterative solver info and context
[in,out]pcpointer to preconditoner context

Variable Documentation

const char* cs_sles_it_type_name[]