A full mathematical description will follow later, but for now we outline some algorithmic steps here. More...

Inheritance diagram for solvers.api.CollocatedMG.CollocatedMG:

[legend]

Collaboration diagram for solvers.api.CollocatedMG.CollocatedMG:

Public Member Functions
	__init__ (self, name, unknowns_per_vertex, dimensions, min_h, max_h, local_assembly_matrix, local_assembly_matrix_scaling, mass_matrix, mass_matrix_scaling, correction_matrix, correction_matrix_scaling, solver_tolerance, pre_smoothing_steps, post_smoothing_steps, descend_order, restriction_matrix, prolongation_matrix, coarsest_level=0, smoother_relaxation=0.6, plot_predicate="true")

	add_to_Peano4_datamodel (self, datamodel, verbose)

	add_use_statements (self, observer)
	This routine should still be called even if overwritten in child class.

	add_to_create_grid (self, observer)

	add_to_init_solution (self, observer)
	Solution initialisation.

	add_to_solve (self, observer)

	add_to_plot (self, observer)

	add_implementation_files_to_project (self, namespace, output, subdirectory="")
	The solver creates two classes: An abstract base class and its implementations.

	get_vertex_merge_method (self)

Public Member Functions inherited from solvers.api.Solver.Solver
	typename (self)

	instance_name (self)
	Return the name of the object that will be created for this solver.

	create_readme_descriptor (self)

	add_to_abstract_solver (self, header, implementation)

	add_to_vertex_data (self, name, size)
	Add in extra attributes on the fly.

	add_to_cell_data (self, name, size)
	Add in extra attributes on the fly.

	add_to_face_data (self, name, size)
	Add in extra attributes on the fly.

	name (self)

	__str__ (self)

Data Fields
	max_h

	min_h

Data Fields inherited from solvers.api.Solver.Solver
	min_h

	max_h

Detailed Description

A full mathematical description will follow later, but for now we outline some algorithmic steps here.

We borrow heavily from the original Collocated Solver. See matrixfree_collocated_solver.

We intialise by setting the values for u and the RHS in implementation files. So far this has been tested with the standard poisson set up ( \( 8\pi^2 sin(x)sin(y) \) on the rhs, with zeroes in the initial guess). We do this only on the finest level, and every other level receives 0.

We enumerate each level according to its coarseness. Ie the top level is marked as 0, and we increase this number as we refine.

Algorithmic Blueprint

On the finest level:
- Solve with Jacobi for a pre-determined number of pre-smoothing steps. Use standard mass matrix
- On the final sweep, we take the final residual and write this into the rhs of the vertex and one level above. We set its initial guess to 0.
- We then move up one level coarser
On the next level up:
- Solve with Jacobi for a pre-determined number of pre-smoothing steps. Use identity instead of mass matrix
- On the final sweep, we take the final residual and write this into the rhs of the vertex and one level above. We set its initial guess to 0.
- We then move up one level coarser
We continue until we are on the coarsest level. We then solve with Jacobi for the predetermined number of pre-smoothing steps.
We then solve on the coarsest level with the predetermined number of post-smoothing steps.
- After this, we move one level finer
On the next level down:
- When we touch a vertex for the first time, we add prolongation of the solution from the level above to our solution.
- We then solve with the predetermined number of post-smoothing steps
- After this, we move one level finer
We continue until we reach the finest level, at which point we add prolongation from the level above, and run for predetermined number of post-smoothing steps. We then go back to step 1.

Every time we run a sweep on the finest level, we update the global residuals. We terminate when the solution on the finest level conforms to the given stopping criterion.

Implementation

We have 4 fundamental action sets, which we discuss here in order of invocation. Each of their operations is guarded by a bool function that lives in the abstract solver class.

UpdateSolution

See also: mghype.matrixfree.solvers.api.actionsets.CollocatedMGSolver.UpdateSolution

This is where we take the residual and diag, and set the solution on vertices to \( u + du = u + \omega / (diag * residual) \). We want to avoid zero-divsion, as reset the diagonal every sweep, meaning we need to wait until the second pre/post-smoothing sweep to update the solution. We also need to make sure we finalise the solution updates before we restrict/prolongate as well. updateSolution() in the abstract solver class handles all of this behaviour.

To make sure the solver works in multiple trees, we tell the vertices that lie on parallel domain boundaries to share residual and diagonal with each other, to make sure contributions from neighbouring cells are registered properly. See get_vertex_merge_method in this class.

This action set also makes sure that the RHS is correctly consolidated - we write our restrictions into the vertex field NewRhs. When we touch a vertex for the first time after restriction, we make sure that the rhs is set to the value of what we restricted (ie the newrhs).

Ditto for delta after prolongation.

Prolongation

See also: mghype.matrixfree.solvers.api.actionsets.CollocatedMGSolver.Prolongation

When we touch a vertex on the coarse level, we set the delta field to be \( U - OldU \). When we touch a vertex on the fine level, we prolongate the coarse delta into the fine level delta. On the next sweep, we update the fine solution to be \( u + delta \).

The abstract solver just needs to check if its smoothing state is set to prolongation, so the logic is much simpler.

ResetAndUpdateResidual

See also: mghype.matrixfree.solvers.api.actionsets.CollocatedMGSolver.ResetAndUpdateResidual

When we touch the vertex for the first time, we reset residual and diag to 0, or apply boundary conditions. When we touch the cell for the first time, we perform the jacobi iteration and write the residual into the \( 2^D \) adjacent vertices.

The abstract solver class does this if updateResidual() returns true, which it does when:

The refinement level matches the active level
The smoothing state is presmoothing or postsmoothing

Restriction

See also: mghype.matrixfree.solvers.api.actionsets.CollocatedMGSolver.Restriction

When we touch a coarse vertex for the first time, we reset everything to 0, i.e. rhs and solution. When we touch a fine vertex for the first time, we hand over to the mghype::matrixfree::solvers::cgmultigrid::restrictToNextLevel which writes the fine level residual into the newRhs of the level above.

Infrastructure

You can now specify the number of levels that you want to use in the solver itself. The finest level is set by the refinement of the mesh and is currently determined at runtime when the mesh is descended for the first time. If we find that the finest level isn't at least one larger than the coarest level, we throw a std::runtime_error.

Definition at line 22 of file CollocatedMG.py.

Constructor & Destructor Documentation

◆ init()

solvers.api.CollocatedMG.CollocatedMG.__init__	(	self,
		name,
		unknowns_per_vertex,
		dimensions,
		min_h,
		max_h,
		local_assembly_matrix,
		local_assembly_matrix_scaling,
		mass_matrix,
		mass_matrix_scaling,
		correction_matrix,
		correction_matrix_scaling,
		solver_tolerance,
		pre_smoothing_steps,
		post_smoothing_steps,
		descend_order,
		restriction_matrix,
		prolongation_matrix,
		coarsest_level = `0`,
		smoother_relaxation = `0.6`,
		plot_predicate = `"true"`
	)

Reimplemented from solvers.api.Solver.Solver.

Reimplemented in solvers.api.CollocatedMGSingleThreaded.CollocatedMGSingleThreaded.

Definition at line 119 of file CollocatedMG.py.

References solvers.api.CollocatedMG.CollocatedMG.__init__().

Referenced by solvers.api.CollocatedMG.CollocatedMG.__init__().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Function Documentation

◆ add_implementation_files_to_project()

solvers.api.CollocatedMG.CollocatedMG.add_implementation_files_to_project	(	self,
		namespace,
		output,
		subdirectory = `""`
	)

The solver creates two classes: An abstract base class and its implementations.

The abstract base class will be overwritten if there is one in the directory. I pipe all the Python constants into this base class, so they are available in the C++ code.

Definition at line 263 of file CollocatedMG.py.

References peano4.api.output.ActionSet.ActionSet.__class__, peano4.api.output.Jinja2TemplatedHeaderImplementationFilePair.Jinja2TemplatedHeaderImplementationFilePair.__class__, and peano4.api.output.TemplatedHeaderFile.TemplatedHeaderFile.__class__.

◆ add_to_create_grid()

solvers.api.CollocatedMG.CollocatedMG.add_to_create_grid	(	self,
		observer
	)

Definition at line 211 of file CollocatedMG.py.

◆ add_to_init_solution()

solvers.api.CollocatedMG.CollocatedMG.add_to_init_solution	(	self,
		observer
	)

Solution initialisation.

Definition at line 214 of file CollocatedMG.py.

◆ add_to_Peano4_datamodel()

solvers.api.CollocatedMG.CollocatedMG.add_to_Peano4_datamodel	(	self,
		datamodel,
		verbose
	)

Reimplemented from solvers.api.Solver.Solver.

Definition at line 205 of file CollocatedMG.py.

References solvers.api.CollocatedMG.CollocatedMG.add_to_Peano4_datamodel().

Referenced by solvers.api.CollocatedMG.CollocatedMG.add_to_Peano4_datamodel().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ add_to_plot()

solvers.api.CollocatedMG.CollocatedMG.add_to_plot	(	self,
		observer
	)

Definition at line 241 of file CollocatedMG.py.

References solvers.api.CollocatedDLinearDiscretisationWithPointJacobi.CollocatedDLinearDiscretisationWithPointJacobi._plot_predicate, solvers.api.CollocatedMG.CollocatedMG._plot_predicate, solvers.api.ContinuousGalerkinDiscretisationGaussLobattoWithBlockJacobi.ContinuousGalerkinDiscretisationGaussLobattoWithBlockJacobi._plot_predicate, and solvers.api.DiscontinuousGalerkinDiscretisationPointWiseRiemannSolver.DiscontinuousGalerkinDiscretisationPointWiseRiemannSolver._plot_predicate.

◆ add_to_solve()

solvers.api.CollocatedMG.CollocatedMG.add_to_solve	(	self,
		observer
	)

Reimplemented in solvers.api.CollocatedMGSingleThreaded.CollocatedMGSingleThreaded.

Definition at line 223 of file CollocatedMG.py.

References solvers.api.CollocatedDLinearDiscretisationWithPointJacobi.CollocatedDLinearDiscretisationWithPointJacobi._basic_descend_order, solvers.api.CollocatedMG.CollocatedMG._basic_descend_order, and solvers.api.ContinuousGalerkinDiscretisationGaussLobattoWithBlockJacobi.ContinuousGalerkinDiscretisationGaussLobattoWithBlockJacobi._basic_descend_order.

◆ add_use_statements()

solvers.api.CollocatedMG.CollocatedMG.add_use_statements	(	self,
		observer
	)

This routine should still be called even if overwritten in child class.

Reimplemented from solvers.api.Solver.Solver.

Definition at line 208 of file CollocatedMG.py.

References solvers.api.CollocatedMG.CollocatedMG.add_use_statements().

Referenced by solvers.api.CollocatedMG.CollocatedMG.add_use_statements().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_vertex_merge_method()

solvers.api.CollocatedMG.CollocatedMG.get_vertex_merge_method ( self )

Reimplemented in solvers.api.CollocatedMGSingleThreaded.CollocatedMGSingleThreaded.

Definition at line 337 of file CollocatedMG.py.

References solvers.api.Solver.Solver.instance_name(), and api.solvers.Solver.Solver.instance_name().

Referenced by solvers.api.CollocatedDLinearDiscretisationWithPointJacobi.CollocatedDLinearDiscretisationWithPointJacobi.__init__().

Here is the call graph for this function:

Here is the caller graph for this function:

Field Documentation

◆ _basic_descend_order

solvers.api.CollocatedMG.CollocatedMG._basic_descend_order

protected

Definition at line 200 of file CollocatedMG.py.

Referenced by solvers.api.CollocatedDLinearDiscretisationWithPointJacobi.CollocatedDLinearDiscretisationWithPointJacobi.add_to_solve(), solvers.api.CollocatedMG.CollocatedMG.add_to_solve(), solvers.api.CollocatedMGSingleThreaded.CollocatedMGSingleThreaded.add_to_solve(), and solvers.api.ContinuousGalerkinDiscretisationGaussLobattoWithBlockJacobi.ContinuousGalerkinDiscretisationGaussLobattoWithBlockJacobi.add_to_solve().

◆ _coarsest_level

solvers.api.CollocatedMG.CollocatedMG._coarsest_level

protected

Definition at line 154 of file CollocatedMG.py.

◆ _correction_matrix

solvers.api.CollocatedMG.CollocatedMG._correction_matrix

protected

Definition at line 196 of file CollocatedMG.py.

◆ _correction_matrix_scaling

solvers.api.CollocatedMG.CollocatedMG._correction_matrix_scaling

protected

Definition at line 197 of file CollocatedMG.py.

◆ _local_assembly_matrix

solvers.api.CollocatedMG.CollocatedMG._local_assembly_matrix

protected

Definition at line 191 of file CollocatedMG.py.

◆ _local_assembly_matrix_scaling

solvers.api.CollocatedMG.CollocatedMG._local_assembly_matrix_scaling

protected

Definition at line 192 of file CollocatedMG.py.

◆ _mass_matrix

solvers.api.CollocatedMG.CollocatedMG._mass_matrix

protected

Definition at line 194 of file CollocatedMG.py.

◆ _mass_matrix_scaling

solvers.api.CollocatedMG.CollocatedMG._mass_matrix_scaling

protected

Definition at line 195 of file CollocatedMG.py.

◆ _plot_predicate

solvers.api.CollocatedMG.CollocatedMG._plot_predicate

protected

Definition at line 203 of file CollocatedMG.py.

Referenced by solvers.api.CollocatedDLinearDiscretisationWithPointJacobi.CollocatedDLinearDiscretisationWithPointJacobi.add_to_plot(), solvers.api.CollocatedMG.CollocatedMG.add_to_plot(), and solvers.api.ContinuousGalerkinDiscretisationGaussLobattoWithBlockJacobi.ContinuousGalerkinDiscretisationGaussLobattoWithBlockJacobi.add_to_plot().

◆ _post_smoothing_steps

solvers.api.CollocatedMG.CollocatedMG._post_smoothing_steps

protected

Definition at line 149 of file CollocatedMG.py.

◆ _pre_smoothing_steps

solvers.api.CollocatedMG.CollocatedMG._pre_smoothing_steps

protected

Definition at line 148 of file CollocatedMG.py.

◆ _prolongation_matrix

solvers.api.CollocatedMG.CollocatedMG._prolongation_matrix

protected

Definition at line 152 of file CollocatedMG.py.

◆ _restriction_matrix

solvers.api.CollocatedMG.CollocatedMG._restriction_matrix

protected

Definition at line 151 of file CollocatedMG.py.

◆ _smoother_relaxation

solvers.api.CollocatedMG.CollocatedMG._smoother_relaxation

protected

Definition at line 202 of file CollocatedMG.py.

◆ _solver_tolerance

solvers.api.CollocatedMG.CollocatedMG._solver_tolerance

protected

Definition at line 198 of file CollocatedMG.py.

◆ _unknowns_per_vertex_node

solvers.api.CollocatedMG.CollocatedMG._unknowns_per_vertex_node

protected

Definition at line 163 of file CollocatedMG.py.

◆ max_h

solvers.api.CollocatedMG.CollocatedMG.max_h

Definition at line 212 of file CollocatedMG.py.

Referenced by solvers.api.Solver.Solver.__str__(), exaparty.api.particle.Particle.Particle.readme_descriptor(), and tarch.plotter.api.filters.ExtractMeshResolution.ExtractMeshResolution.render().

◆ min_h

solvers.api.CollocatedMG.CollocatedMG.min_h

Definition at line 282 of file CollocatedMG.py.

Referenced by solvers.api.Solver.Solver.__str__(), exaparty.api.particle.Particle.Particle.readme_descriptor(), and tarch.plotter.api.filters.ExtractMeshResolution.ExtractMeshResolution.render().

The documentation for this class was generated from the following file:

src/mghype/matrixfree/solvers/api/CollocatedMG.py

Protected Attributes
	_pre_smoothing_steps

	_post_smoothing_steps

	_restriction_matrix

	_prolongation_matrix

	_coarsest_level

	_unknowns_per_vertex_node

	_local_assembly_matrix

	_local_assembly_matrix_scaling

	_mass_matrix

	_mass_matrix_scaling

	_correction_matrix

	_correction_matrix_scaling

	_solver_tolerance

	_basic_descend_order

	_smoother_relaxation

	_plot_predicate

Protected Attributes inherited from solvers.api.Solver.Solver
	_name

	_vertex_data

	_face_data

	_cell_data

	_abstract_solver_header_extras

	_abstract_solver_implementation_extras

Public Member Functions

Data Fields

Protected Attributes

Detailed Description

Algorithmic Blueprint

Implementation

UpdateSolution

Prolongation

ResetAndUpdateResidual

Restriction

Infrastructure

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ add_implementation_files_to_project()

◆ add_to_create_grid()

◆ add_to_init_solution()

◆ add_to_Peano4_datamodel()

◆ add_to_plot()

◆ add_to_solve()

◆ add_use_statements()

◆ get_vertex_merge_method()

Field Documentation

◆ _basic_descend_order

◆ _coarsest_level

◆ _correction_matrix

◆ _correction_matrix_scaling

◆ _local_assembly_matrix

◆ _local_assembly_matrix_scaling

◆ _mass_matrix

◆ _mass_matrix_scaling

◆ _plot_predicate

◆ _post_smoothing_steps

◆ _pre_smoothing_steps

◆ _prolongation_matrix

◆ _restriction_matrix

◆ _smoother_relaxation

◆ _solver_tolerance

◆ _unknowns_per_vertex_node

◆ max_h

◆ min_h

◆ init()