p.Chaos.LinearSystem.Preconditioner

p.Chaos.LinearSystem.Preconditioner

#Overview

name: p.Chaos.LinearSystem.Preconditioner

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.LinearSystem.Preconditioner is to control the type of preconditioner used in the Chaos linear system solver. It is used in the physics simulation system, specifically within the Chaos module of Unreal Engine 5.

This setting variable is primarily used in the Chaos subsystem, which is an experimental physics engine in Unreal Engine 5. It’s referenced in the BlockSparseLinearSystem.cpp file, which suggests it’s part of the linear system solver used in physics simulations.

The value of this variable is set through a console variable (CVar) system, allowing it to be changed at runtime. It’s associated with the PreconditionerType variable, which is an integer that determines the type of preconditioner to use.

The PreconditionerType variable interacts directly with p.Chaos.LinearSystem.Preconditioner. It’s used in a switch statement to determine which preconditioner to use in the Solve function of the TBlockSparseSymmetricLinearSystem class.

Developers must be aware that this variable affects the performance and stability of the physics simulation. Different preconditioners can have varying effects on convergence speed and accuracy of the linear system solver.

Best practices when using this variable include:

  1. Understanding the trade-offs between different preconditioner types.
  2. Testing the impact of different preconditioners on your specific physics simulation scenarios.
  3. Monitoring performance metrics when changing this variable.

Regarding the associated variable PreconditionerType:

The purpose of PreconditionerType is to store the integer value that represents the chosen preconditioner type. It’s used internally within the Chaos module to select the appropriate preconditioner in the linear system solver.

This variable is set to a default value of EPreconditionerType::Diagonal (which is likely 0) and can be modified through the p.Chaos.LinearSystem.Preconditioner console variable.

PreconditionerType is used in the Solve function of the TBlockSparseSymmetricLinearSystem class to determine which preconditioner to use in the linear system solver.

Developers should be aware that this variable directly affects the behavior of the physics simulation and should be changed cautiously.

Best practices for using PreconditionerType include:

  1. Using the console variable p.Chaos.LinearSystem.Preconditioner to modify it rather than changing it directly in code.
  2. Understanding the performance implications of each preconditioner type before changing this value.
  3. Documenting any changes made to this variable in your project settings or documentation.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Math/BlockSparseLinearSystem.cpp:35

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

};
static int32 PreconditionerType = EPreconditionerType::Diagonal;
FAutoConsoleVariableRef CVarChaosLinearSystemPreconditioner(TEXT("p.Chaos.LinearSystem.Preconditioner"), PreconditionerType, TEXT("0 = Diagonal, 1 = IncompleteCholesky"));

	template<typename T, int32 BlockSize>
	struct TBlockSparseSymmetricLinearSystem<T, BlockSize>::FPimpl
	{
		// Just doing Eigen sparse matrix for now and building from triplets. Will investigate block symmetric later
		typedef typename Eigen::SparseMatrix<T, Eigen::RowMajor> SparseMatrixType;

#Associated Variable and Callsites

This variable is associated with another variable named PreconditionerType. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Math/BlockSparseLinearSystem.cpp:34

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	IncompleteCholesky = 1
};
static int32 PreconditionerType = EPreconditionerType::Diagonal;
FAutoConsoleVariableRef CVarChaosLinearSystemPreconditioner(TEXT("p.Chaos.LinearSystem.Preconditioner"), PreconditionerType, TEXT("0 = Diagonal, 1 = IncompleteCholesky"));

	template<typename T, int32 BlockSize>
	struct TBlockSparseSymmetricLinearSystem<T, BlockSize>::FPimpl
	{
		// Just doing Eigen sparse matrix for now and building from triplets. Will investigate block symmetric later
		typedef typename Eigen::SparseMatrix<T, Eigen::RowMajor> SparseMatrixType;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Math/BlockSparseLinearSystem.cpp:184

Scope (from outer to inner):

file
namespace    Chaos
function     bool TBlockSparseSymmetricLinearSystem<T, BlockSize>::Solve

Source code excerpt:

		int32* OptionalOutIterations, T* OptionalOutError) const
	{
		switch (PreconditionerType)
		{
		case EPreconditionerType::Diagonal:
			return Pimpl->template Solve<Eigen::DiagonalPreconditioner<T>>(RHS, Result, MaxNumCGIterations, CGResidualTolerance, bCheckResidual, OptionalOutIterations, OptionalOutError);
		case EPreconditionerType::IncompleteCholesky:
			return Pimpl->template Solve<Eigen::IncompleteCholesky<T, Eigen::Upper | Eigen::Lower>>(RHS, Result, MaxNumCGIterations, CGResidualTolerance, bCheckResidual, OptionalOutIterations, OptionalOutError);
		default: