cs_multigrid.c 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_blas.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_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.c:

Functions
void	cs_multigrid_initialize (void)
	Initialize multigrid solver API. More...
void	cs_multigrid_finalize (void)
	Finalize multigrid solver API. More...
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. More...
cs_multigrid_t *	cs_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, int coarsening_type, int n_max_levels, cs_gnum_t min_g_rows, double p0p1_relax, int postprocess)
	Set multigrid coarsening parameters. 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_max_cycles (cs_multigrid_t *mg, int n_max_cycles)
	Set the max. number of cycles for a multigrid. More...
cs_sles_it_type_t	cs_multigrid_get_fine_solver_type (const cs_multigrid_t *mg)
	Return solver type used on fine mesh. 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 *residue, const cs_real_t *rhs, 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_t *	cs_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_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. 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]

context

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

type 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_id	associated field id, or < 0
[in]	name	associated name if f_id < 0, or NULL
[in]	mg_type	type 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]

context

pointer 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]	sles	pointer to solver object
[in]	state	convergence state
[in]	a	matrix
[in]	rhs	right hand side
[in,out]	vx	system 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]

context

pointer to multigrid solver info and context (actual type: cs_multigrid_t *)

cs_multigrid_get_fine_solver_type()

cs_sles_it_type_t cs_multigrid_get_fine_solver_type

(

const cs_multigrid_t *

mg

)

Return solver type used on fine mesh.

Parameters

[in]

mg

pointer to multigrid info and context

Returns

type of smoother for descent (used for fine mesh)

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, NULL is returned.

Parameters

[in]	mg	pointer to multigrid info and context
[in]	level	level of the requested grid (or -1 for coarsest)

Returns

pointer to grid of requested level (NULL 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]	mg	pointer to multigrid info and context
[out]	rank_stride	number of ranks over which merging takes place, or NULL
[out]	rows_mean_threshold	mean number of rows under which merging should be applied, or NULL
[out]	rows_glob_threshold	global number of rows under which merging should be applied, or NULL

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]	context	pointer to iterative solver info and context (actual type: cs_multigrid_t *)
[in]	log_type	log type

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_type

type 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,
		int	coarsening_type,
		int	n_max_levels,
		cs_gnum_t	min_g_rows,
		double	p0p1_relax,
		int	postprocess
	)

Set multigrid coarsening parameters.

Parameters

[in,out]	mg	pointer to multigrid info and context
[in]	aggregation_limit	maximum allowed fine rows per coarse row
[in]	coarsening_type	coarsening type; see cs_grid_coarsening_t
[in]	n_max_levels	maximum number of grid levels
[in]	min_g_rows	global number of rows on coarse grids under which no coarsening occurs
[in]	p0p1_relax	p0/p1 relaxation_parameter
[in]	postprocess	if > 0, postprocess coarsening (uses coarse row numbers modulo this value)

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]	mg	pointer to multigrid info and context
[in]	n_max_cycles	maximum number of cycles

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]	mg	pointer to multigrid info and context
[in]	rank_stride	number of ranks over which merging takes place
[in]	rows_mean_threshold	mean number of rows under which merging should be applied
[in]	rows_glob_threshold	global 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]	mg	pointer to multigrid info and context
[in]	base_name	base plot name to activate, NULL otherwise
[in]	use_iteration	if 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.

Parameters

[in,out]	mg	pointer to multigrid info and context
[in]	descent_smoother_type	type of smoother for descent
[in]	ascent_smoother_type	type of smoother for ascent
[in]	coarse_solver_type	type of solver for coarsest grid
[in]	n_max_cycles	maximum number of cycles
[in]	n_max_iter_descent	maximum iterations per descent smoothing
[in]	n_max_iter_ascent	maximum iterations per ascent smoothing
[in]	n_max_iter_coarse	maximum iterations per coarsest solution
[in]	poly_degree_descent	preconditioning polynomial degree for descent phases (0: diagonal)
[in]	poly_degree_ascent	preconditioning polynomial degree for ascent phases (0: diagonal)
[in]	poly_degree_coarse	preconditioning polynomial degree for coarse solver (0: diagonal)
[in]	precision_mult_descent	precision multiplier for descent smoothers (levels >= 1)
[in]	precision_mult_ascent	precision multiplier for ascent smoothers
[in]	precision_mult_coarse	precision multiplier for coarsest grid

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]	context	pointer to multigrid solver info and context (actual type: cs_multigrid_t *)
[in]	name	pointer to name of linear system
[in]	a	associated matrix
[in]	verbosity	associated 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]	context	pointer to multigrid solver info and context (actual type: cs_multigrid_t *)
[in]	name	pointer to name of linear system
[in]	a	associated matrix
[in]	conv_diff	convection-diffusion mode
[in]	verbosity	associated 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 *	residue,
		const cs_real_t *	rhs,
		cs_real_t *	vx,
		size_t	aux_size,
		void *	aux_vectors
	)

Call multigrid sparse linear equation solver.

Parameters

[in,out]	context	pointer to multigrid solver info and context (actual type: cs_multigrid_t *)
[in]	name	pointer to name of linear system
[in]	a	matrix
[in]	verbosity	associated verbosity
[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