8.3
general documentation
cs_multigrid.cpp File Reference
#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_base_accel.h"
#include "cs_blas.h"
#include "cs_dispatch.h"
#include "cs_file.h"
#include "cs_grid.h"
#include "cs_halo.h"
#include "cs_log.h"
#include "cs_matrix.h"
#include "cs_matrix_default.h"
#include "cs_matrix_spmv_cuda.h"
#include "cs_matrix_util.h"
#include "cs_mesh.h"
#include "cs_mesh_quantities.h"
#include "cs_multigrid_smoother.h"
#include "cs_post.h"
#include "cs_sles.h"
#include "cs_sles_it.h"
#include "cs_sles_pc.h"
#include "cs_timer.h"
#include "cs_time_plot.h"
#include "cs_time_step.h"
#include "cs_multigrid.h"
+ Include dependency graph for cs_multigrid.cpp:

Functions

void cs_multigrid_initialize (void)
 Initialize multigrid solver API. More...
 
void cs_multigrid_finalize (void)
 Finalize multigrid solver API. More...
 
void cs_multigrid_set_max_grid_level_for_device (int level)
 Set maximum grid level which should run on device (i.e. GPU). More...
 
cs_multigrid_tcs_multigrid_define (int f_id, const char *name, cs_multigrid_type_t mg_type)
 Define and associate a multigrid sparse linear system solver for a given field or equation name. More...
 
cs_multigrid_tcs_multigrid_create (cs_multigrid_type_t mg_type)
 Create multigrid linear system solver info and context. More...
 
void cs_multigrid_destroy (void **context)
 Destroy multigrid linear system solver info and context. More...
 
void * cs_multigrid_copy (const void *context)
 Create multigrid sparse linear system solver info and context based on existing info and context. More...
 
void cs_multigrid_log (const void *context, cs_log_t log_type)
 Log multigrid solver info. More...
 
void cs_multigrid_set_coarsening_options (cs_multigrid_t *mg, int aggregation_limit, cs_grid_coarsening_t coarsening_type, int n_max_levels, cs_gnum_t min_g_rows, double p0p1_relax, int postprocess_block_size)
 Set multigrid coarsening parameters. More...
 
void cs_multigrid_set_coarsening_options_fine_grid (cs_multigrid_t *mg, int f_settings_threshold, int aggregation_limit, cs_grid_coarsening_t coarsening_type)
 Set specific multigrid coarsening parameters for fine grids. More...
 
void cs_multigrid_set_solver_options (cs_multigrid_t *mg, cs_sles_it_type_t descent_smoother_type, cs_sles_it_type_t ascent_smoother_type, cs_sles_it_type_t coarse_solver_type, int n_max_cycles, int n_max_iter_descent, int n_max_iter_ascent, int n_max_iter_coarse, int poly_degree_descent, int poly_degree_ascent, int poly_degree_coarse, double precision_mult_descent, double precision_mult_ascent, double precision_mult_coarse)
 Set multigrid parameters for associated iterative solvers. More...
 
void cs_multigrid_set_solver_options_d (cs_multigrid_t *mg, cs_sles_it_type_t descent_smoother_type, cs_sles_it_type_t ascent_smoother_type, cs_sles_it_type_t coarse_solver_type, int n_max_iter_descent, int n_max_iter_ascent, int n_max_iter_coarse, int poly_degree_descent, int poly_degree_ascent, int poly_degree_coarse)
 Set multigrid device solver parameters for associated iterative solvers. More...
 
void cs_multigrid_set_max_cycles (cs_multigrid_t *mg, int n_max_cycles)
 Set the max. number of cycles for a multigrid. More...
 
bool cs_multigrid_need_msr (const cs_multigrid_t *mg)
 Indicate if a multigrid solver requires an MSR matrix input. More...
 
void cs_multigrid_setup (void *context, const char *name, const cs_matrix_t *a, int verbosity)
 Setup multigrid sparse linear equation solver. More...
 
void cs_multigrid_setup_conv_diff (void *context, const char *name, const cs_matrix_t *a, bool conv_diff, int verbosity)
 Setup multigrid sparse linear equation solver. More...
 
cs_sles_convergence_state_t cs_multigrid_solve (void *context, const char *name, const cs_matrix_t *a, int verbosity, double precision, double r_norm, int *n_iter, double *residual, const cs_real_t *rhs, cs_real_t *vx_ini, cs_real_t *vx, size_t aux_size, void *aux_vectors)
 Call multigrid sparse linear equation solver. More...
 
void cs_multigrid_free (void *context)
 Free multigrid sparse linear equation solver setup context. More...
 
cs_sles_pc_tcs_multigrid_pc_create (cs_multigrid_type_t mg_type)
 Create a multigrid preconditioner. More...
 
bool cs_multigrid_error_post_and_abort (cs_sles_t *sles, cs_sles_convergence_state_t state, const cs_matrix_t *a, const cs_real_t rhs[], cs_real_t vx[])
 Error handler for multigrid sparse linear equation solver. More...
 
void cs_multigrid_set_plot_options (cs_multigrid_t *mg, const char *base_name, bool use_iteration)
 Set plotting options for multigrid. More...
 
void cs_multigrid_get_merge_options (const cs_multigrid_t *mg, int *rank_stride, int *rows_mean_threshold, cs_gnum_t *rows_glob_threshold)
 Query the global multigrid parameters for parallel grid merging. More...
 
void cs_multigrid_set_merge_options (cs_multigrid_t *mg, int rank_stride, int rows_mean_threshold, cs_gnum_t rows_glob_threshold)
 Set global multigrid parameters for parallel grid merging behavior. More...
 
const cs_grid_tcs_multigrid_get_grid (const cs_multigrid_t *mg, int level)
 Return a pointer to a grid associated with a given multigrid setup and level. More...
 

Function Documentation

◆ cs_multigrid_copy()

void * cs_multigrid_copy ( const void *  context)

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

Parameters
[in]contextpointer to reference info and context (actual type: cs_multigrid_t *)
Returns
pointer to newly created solver info object (actual type: cs_multigrid_t *)

◆ cs_multigrid_create()

cs_multigrid_t * cs_multigrid_create ( cs_multigrid_type_t  mg_type)

Create multigrid linear system solver info and context.

The multigrid variant is an ACM (Additive Corrective Multigrid) method.

Parameters
[in]mg_typetype of multigrid algorithm to use
Returns
pointer to new multigrid info and context

◆ cs_multigrid_define()

cs_multigrid_t * cs_multigrid_define ( int  f_id,
const char *  name,
cs_multigrid_type_t  mg_type 
)

Define and associate a multigrid 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_multigrid_create.

Note that this function returns a pointer directly to the multigrid solver management structure. This may be used to set further options, for example calling cs_multigrid_set_coarsening_options and cs_multigrid_set_solver_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 nullptr
[in]mg_typetype of multigrid algorithm to use
Returns
pointer to new multigrid info and context

◆ cs_multigrid_destroy()

void cs_multigrid_destroy ( void **  context)

Destroy multigrid linear system solver info and context.

Parameters
[in,out]contextpointer to multigrid linear solver info (actual type: cs_multigrid_t **)

◆ cs_multigrid_error_post_and_abort()

bool cs_multigrid_error_post_and_abort ( cs_sles_t sles,
cs_sles_convergence_state_t  state,
const cs_matrix_t a,
const cs_real_t  rhs[],
cs_real_t  vx[] 
)

Error handler for multigrid 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]slespointer to solver object
[in]stateconvergence state
[in]amatrix
[in]rhsright hand side
[in,out]vxsystem solution
Returns
false (do not attempt new solve)

◆ cs_multigrid_finalize()

void cs_multigrid_finalize ( void  )

Finalize multigrid solver API.

◆ cs_multigrid_free()

void cs_multigrid_free ( void *  context)

Free multigrid sparse linear equation solver setup context.

This function frees resolution-related data, incuding the current grid hierarchy, but does not free the whole context, as info used for logging (especially performance data) is maintained.

Parameters
[in,out]contextpointer to multigrid solver info and context (actual type: cs_multigrid_t *)

◆ cs_multigrid_get_grid()

const cs_grid_t * cs_multigrid_get_grid ( const cs_multigrid_t mg,
int  level 
)

Return a pointer to a grid associated with a given multigrid setup and level.

If the multigrid hierarchy is not set up, or a level coarser than the coarsest level is requested, nullptr is returned.

Parameters
[in]mgpointer to multigrid info and context
[in]levellevel of the requested grid (or -1 for coarsest)
Returns
pointer to grid of requested level (nullptr id not present)

◆ cs_multigrid_get_merge_options()

void cs_multigrid_get_merge_options ( const cs_multigrid_t mg,
int *  rank_stride,
int *  rows_mean_threshold,
cs_gnum_t rows_glob_threshold 
)

Query the global multigrid parameters for parallel grid merging.

Parameters
[in]mgpointer to multigrid info and context
[out]rank_stridenumber of ranks over which merging takes place, or nullptr
[out]rows_mean_thresholdmean number of rows under which merging should be applied, or nullptr
[out]rows_glob_thresholdglobal number of rows under which merging should be applied, or nullptr

◆ cs_multigrid_initialize()

void cs_multigrid_initialize ( void  )

Initialize multigrid solver API.

◆ cs_multigrid_log()

void cs_multigrid_log ( const void *  context,
cs_log_t  log_type 
)

Log multigrid solver info.

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

◆ cs_multigrid_need_msr()

bool cs_multigrid_need_msr ( const cs_multigrid_t mg)

Indicate if a multigrid solver requires an MSR matrix input.

Parameters
[in]mgpointer to multigrid info and context
Returns
true if MSR is needed, false otherwise.

◆ cs_multigrid_pc_create()

cs_sles_pc_t * cs_multigrid_pc_create ( cs_multigrid_type_t  mg_type)

Create a multigrid preconditioner.

Parameters
[in]mg_typetype of multigrid algorithm to use
Returns
pointer to newly created preconditioner object.

◆ cs_multigrid_set_coarsening_options()

void cs_multigrid_set_coarsening_options ( cs_multigrid_t mg,
int  aggregation_limit,
cs_grid_coarsening_t  coarsening_type,
int  n_max_levels,
cs_gnum_t  min_g_rows,
double  p0p1_relax,
int  postprocess_block_size 
)

Set multigrid coarsening parameters.

Parameters
[in,out]mgpointer to multigrid info and context
[in]aggregation_limitmaximum allowed fine rows per coarse row
[in]coarsening_typecoarsening type; see cs_grid_coarsening_t
[in]n_max_levelsmaximum number of grid levels
[in]min_g_rowsglobal number of rows on coarse grids under which no coarsening occurs
[in]p0p1_relaxp0/p1 relaxation_parameter
[in]postprocessif > 0, postprocess coarsening (uses coarse row numbers modulo this value)

◆ cs_multigrid_set_coarsening_options_fine_grid()

void cs_multigrid_set_coarsening_options_fine_grid ( cs_multigrid_t mg,
int  f_settings_threshold,
int  aggregation_limit,
cs_grid_coarsening_t  coarsening_type 
)

Set specific multigrid coarsening parameters for fine grids.

Parameters
[in,out]mgpointer to multigrid info and context
[in]f_settings_thresholdgrids of this level or higher use standard (coarse grid) settings.
[in]aggregation_limitmaximum allowed fine rows per coarse row
[in]coarsening_typecoarsening type; see cs_grid_coarsening_t

◆ cs_multigrid_set_max_cycles()

void cs_multigrid_set_max_cycles ( cs_multigrid_t mg,
int  n_max_cycles 
)

Set the max. number of cycles for a multigrid.

Parameters
[in,out]mgpointer to multigrid info and context
[in]n_max_cyclesmaximum number of cycles

◆ cs_multigrid_set_max_grid_level_for_device()

void cs_multigrid_set_max_grid_level_for_device ( int  level)

Set maximum grid level which should run on device (i.e. GPU).

◆ cs_multigrid_set_merge_options()

void cs_multigrid_set_merge_options ( cs_multigrid_t mg,
int  rank_stride,
int  rows_mean_threshold,
cs_gnum_t  rows_glob_threshold 
)

Set global multigrid parameters for parallel grid merging behavior.

Parameters
[in,out]mgpointer to multigrid info and context
[in]rank_stridenumber of ranks over which merging takes place
[in]rows_mean_thresholdmean number of rows under which merging should be applied
[in]rows_glob_thresholdglobal number of rows under which merging should be applied

◆ cs_multigrid_set_plot_options()

void cs_multigrid_set_plot_options ( cs_multigrid_t mg,
const char *  base_name,
bool  use_iteration 
)

Set plotting options for multigrid.

Parameters
[in,out]mgpointer to multigrid info and context
[in]base_namebase plot name to activate, nullptr otherwise
[in]use_iterationif true, use iteration as time stamp otherwise, use wall clock time

◆ cs_multigrid_set_solver_options()

void cs_multigrid_set_solver_options ( cs_multigrid_t mg,
cs_sles_it_type_t  descent_smoother_type,
cs_sles_it_type_t  ascent_smoother_type,
cs_sles_it_type_t  coarse_solver_type,
int  n_max_cycles,
int  n_max_iter_descent,
int  n_max_iter_ascent,
int  n_max_iter_coarse,
int  poly_degree_descent,
int  poly_degree_ascent,
int  poly_degree_coarse,
double  precision_mult_descent,
double  precision_mult_ascent,
double  precision_mult_coarse 
)

Set multigrid parameters for associated iterative solvers.

On a GPU, some parameters may be replaced by the closest GPU equivalents. For finer control, use cs_multigrid_set_coarsening_options_d after calling this function to modify parameters for solvers running on device.

Parameters
[in,out]mgpointer to multigrid info and context
[in]descent_smoother_typetype of smoother for descent
[in]ascent_smoother_typetype of smoother for ascent
[in]coarse_solver_typetype of solver for coarsest grid
[in]n_max_cyclesmaximum number of cycles
[in]n_max_iter_descentmaximum iterations per descent smoothing
[in]n_max_iter_ascentmaximum iterations per ascent smoothing
[in]n_max_iter_coarsemaximum iterations per coarsest solution
[in]poly_degree_descentpreconditioning polynomial degree for descent phases (0: diagonal)
[in]poly_degree_ascentpreconditioning polynomial degree for ascent phases (0: diagonal)
[in]poly_degree_coarsepreconditioning polynomial degree for coarse solver (0: diagonal)
[in]precision_mult_descentprecision multiplier for descent smoothers (levels >= 1)
[in]precision_mult_ascentprecision multiplier for ascent smoothers
[in]precision_mult_coarseprecision multiplier for coarsest grid

◆ cs_multigrid_set_solver_options_d()

void cs_multigrid_set_solver_options_d ( cs_multigrid_t mg,
cs_sles_it_type_t  descent_smoother_type,
cs_sles_it_type_t  ascent_smoother_type,
cs_sles_it_type_t  coarse_solver_type,
int  n_max_iter_descent,
int  n_max_iter_ascent,
int  n_max_iter_coarse,
int  poly_degree_descent,
int  poly_degree_ascent,
int  poly_degree_coarse 
)

Set multigrid device solver parameters for associated iterative solvers.

Parameters
[in,out]mgpointer to multigrid info and context
[in]descent_smoother_typetype of smoother for descent
[in]ascent_smoother_typetype of smoother for ascent
[in]coarse_solver_typetype of solver for coarsest grid
[in]n_max_iter_descentmaximum iterations per descent smoothing
[in]n_max_iter_ascentmaximum iterations per ascent smoothing
[in]n_max_iter_coarsemaximum iterations per coarsest solution
[in]poly_degree_descentpreconditioning polynomial degree for descent phases (0: diagonal)
[in]poly_degree_ascentpreconditioning polynomial degree for ascent phases (0: diagonal)
[in]poly_degree_coarsepreconditioning polynomial degree for coarse solver (0: diagonal)

◆ cs_multigrid_setup()

void cs_multigrid_setup ( void *  context,
const char *  name,
const cs_matrix_t a,
int  verbosity 
)

Setup multigrid sparse linear equation solver.

Parameters
[in,out]contextpointer to multigrid solver info and context (actual type: cs_multigrid_t *)
[in]namepointer to name of linear system
[in]aassociated matrix
[in]verbosityassociated verbosity

◆ cs_multigrid_setup_conv_diff()

void cs_multigrid_setup_conv_diff ( void *  context,
const char *  name,
const cs_matrix_t a,
bool  conv_diff,
int  verbosity 
)

Setup multigrid sparse linear equation solver.

Parameters
[in,out]contextpointer to multigrid solver info and context (actual type: cs_multigrid_t *)
[in]namepointer to name of linear system
[in]aassociated matrix
[in]conv_diffconvection-diffusion mode
[in]verbosityassociated verbosity

◆ cs_multigrid_solve()

cs_sles_convergence_state_t cs_multigrid_solve ( void *  context,
const char *  name,
const cs_matrix_t a,
int  verbosity,
double  precision,
double  r_norm,
int *  n_iter,
double *  residual,
const cs_real_t rhs,
cs_real_t vx_ini,
cs_real_t vx,
size_t  aux_size,
void *  aux_vectors 
)

Call multigrid sparse linear equation solver.

Parameters
[in,out]contextpointer to multigrid solver info and context (actual type: cs_multigrid_t *)
[in]namepointer to name of linear system
[in]amatrix
[in]verbosityassociated verbosity
[in]precisionsolver precision
[in]r_normresidual normalization
[out]n_iternumber of "equivalent" iterations
[out]residualresidual
[in]rhsright hand side
[in]vx_iniinitial system solution (vx if nonzero, nullptr if zero)
[in,out]vxsystem solution
[in]aux_sizesize of aux_vectors (in bytes)
aux_vectorsoptional working area (internal allocation if nullptr)
Returns
convergence state