p.Chaos.Cloth.CGTol

p.Chaos.Cloth.CGTol

#Overview

name: p.Chaos.Cloth.CGTol

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

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Cloth.CGTol is to set the tolerance for the Conjugate Gradient (CG) method used in cloth simulation within Unreal Engine 5’s Chaos physics system. This variable is specifically used for controlling the precision of the CG solver in cloth-related calculations.

The Chaos physics system, particularly its cloth simulation module, relies on this setting variable. It’s used within the Experimental/Chaos runtime module of Unreal Engine 5.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified through console commands or configuration files. Its default value is 1e-4f (0.0001).

This variable interacts closely with another variable named MaxItCG, which sets the maximum number of iterations for the CG method. Both variables are used together to control the behavior of the CG solver.

Developers must be aware that this variable directly affects the precision and performance of cloth simulations. A lower tolerance value will result in more accurate simulations but may require more computation time.

Best practices when using this variable include:

  1. Balancing accuracy and performance by adjusting both CGTol and MaxItCG.
  2. Testing different values to find the optimal balance for your specific use case.
  3. Being cautious when modifying this value, as it can significantly impact simulation quality and performance.

Regarding the associated variable MaxItCG:

The purpose of MaxItCG is to set the maximum number of iterations for the Conjugate Gradient method in cloth simulations within the Chaos physics system.

Like CGTol, MaxItCG is used in the Experimental/Chaos runtime module and is crucial for controlling the behavior of the CG solver in cloth simulations.

The value of MaxItCG is also set using an FAutoConsoleVariableRef, with a default value of 50 iterations.

MaxItCG works in conjunction with CGTol to determine when the CG solver should terminate. The solver will stop when either the tolerance is met or the maximum number of iterations is reached.

Developers should be aware that increasing MaxItCG can lead to more accurate simulations but at the cost of increased computation time.

Best practices for using MaxItCG include:

  1. Adjusting it in tandem with CGTol to achieve the desired balance between accuracy and performance.
  2. Monitoring performance impacts when modifying this value.
  3. Consider the complexity of your cloth simulations when setting this value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Deformable/GaussSeidelMainConstraint.cpp:10

Scope (from outer to inner):

file
namespace    Chaos::Softs

Source code excerpt:

	FSolverReal CGTol = 1e-4f;

	FAutoConsoleVariableRef CVarClothCGTol(TEXT("p.Chaos.Cloth.CGTol"), MaxItCG, TEXT("CG Tolerance [def: 1e-4]"));

	template <typename T, typename ParticleType>
	void FGaussSeidelMainConstraint<T, ParticleType>::AddStaticConstraints(const TArray<TArray<int32>>& ExtraConstraints, TArray<TArray<int32>>& ExtraIncidentElements, TArray<TArray<int32>>& ExtraIncidentElementsLocal)
	{	
		if (!IsClean(ExtraConstraints, ExtraIncidentElements, ExtraIncidentElementsLocal))
		{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Deformable/GaussSeidelMainConstraint.cpp:1

Scope (from outer to inner):

file
namespace    Chaos::Softs

Source code excerpt:

#include "Chaos/Deformable/GaussSeidelMainConstraint.h"
#include "Chaos/Math/Krylov.h"

namespace Chaos::Softs
{
	int32 MaxItCG = 50;

	FAutoConsoleVariableRef CVarClothMaxItCG(TEXT("p.Chaos.Cloth.MaxItCG"), MaxItCG, TEXT("Max iter for CG [def: 50]"));

	FSolverReal CGTol = 1e-4f;

	FAutoConsoleVariableRef CVarClothCGTol(TEXT("p.Chaos.Cloth.CGTol"), MaxItCG, TEXT("CG Tolerance [def: 1e-4]"));

	template <typename T, typename ParticleType>
	void FGaussSeidelMainConstraint<T, ParticleType>::AddStaticConstraints(const TArray<TArray<int32>>& ExtraConstraints, TArray<TArray<int32>>& ExtraIncidentElements, TArray<TArray<int32>>& ExtraIncidentElementsLocal)
	{	
		if (!IsClean(ExtraConstraints, ExtraIncidentElements, ExtraIncidentElementsLocal))
		{
			ExtraIncidentElements = Chaos::Utilities::ComputeIncidentElements(ExtraConstraints, &ExtraIncidentElementsLocal);
		}

		int32 Offset = StaticConstraints.Num();
		StaticConstraints += ExtraConstraints;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Deformable/GaussSeidelMainConstraint.cpp:176

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FGaussSeidelMainConstraint<T, ParticleType>::ApplyCG

Source code excerpt:

					y[i] = FSolverVec3(0.f);
				}
			}
		};

		int32 max_it_cg = MaxItCG;
		FSolverReal cg_tol = CGTol;
		int32 MaxNewtonIt = 1;

		for (int32 It = 0; It < MaxNewtonIt; It++)
		{
			const TArray<FSolverVec3> Residual = ComputeNewtonResiduals(Particles, Dt, false, nullptr);

			auto multiply = [this, &ProjectBCs, &Dt, &Particles](TArray<FSolverVec3>& y, const TArray<FSolverVec3>& x) 
			{
				TArray<FSolverVec3> XProj = x;
				ProjectBCs(XProj);

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Deformable/GaussSeidelMainConstraint.cpp:208

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FGaussSeidelMainConstraint<T, ParticleType>::ApplyCG

Source code excerpt:

			};

			TArray<FSolverVec3> Deltax;
			Deltax.Init(FSolverVec3(0.f), Particles.Size());

			Chaos::LanczosCG<FSolverReal>(multiply, Deltax, Residual, MaxItCG, CGTol, use_list.Get()); 

			PhysicsParallelFor(Particles.Size(), [&Particles, &Deltax](const int32 i) 
				{
					Particles.P(i) -= Deltax[i];
				});
		}
	}
}


template class Chaos::Softs::FGaussSeidelMainConstraint<Chaos::Softs::FSolverReal, Chaos::Softs::FSolverParticles>;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/Math/Poisson.h:255

Scope (from outer to inner):

file
namespace    Chaos
function     void PoissonSolve

Source code excerpt:

template <class T, class TV, class TV_INT = FIntVector4, int d = 3>
void PoissonSolve(const TArray<int32>& InConstrainedNodes, 
	const TArray<T>& ConstrainedWeights, 
	const TArray<TV_INT>& Mesh,
	const TArray<TV>& X,
	const int32 MaxItCG,
	const T CGTol,
	TArray<T>& Weights)
{
	TArray<T> De_inverse;
	TArray<T> measure;
	ComputeDeInverseAndElementMeasures(Mesh, X, De_inverse, measure);

	TArray<TArray<int32>> IncidentElementsLocalIndex;
	TArray<TArray<int32>> IncidentElements = Chaos::Utilities::ComputeIncidentElements<4>(Mesh, &IncidentElementsLocalIndex);
	
	auto ProjectBCs = [&InConstrainedNodes] (TArray<T>& U)

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/Math/Poisson.h:301

Scope (from outer to inner):

file
namespace    Chaos
function     void PoissonSolve

Source code excerpt:

	MinusResidual.Init((T)0., Weights.Num());
	MultiplyLaplacian(MinusResidual, InitialGuess);

	TArray<T> MinusDw;
	MinusDw.Init((T)0., Weights.Num());
	Chaos::LanczosCG(MultiplyLaplacian, MinusDw, MinusResidual, MaxItCG, CGTol, false);

	for (int32 i = 0; i < InitialGuess.Num(); i++)
	{
		Weights[i] = InitialGuess[i] - MinusDw[i];
	}

}

template <class T, class TV_INT=FIntVector4, int d=3>
void 
Laplacian(

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/Math/Poisson.h:603

Scope (from outer to inner):

file
namespace    Chaos
function     void PoissonSolve

Source code excerpt:

// InConstrainedNodes is a list of flattened index nodes that are boundary conditions. ConstrainedWeights is a parallel array of the constrained values.
template<class TV, class T, bool NodalValues = false>
void PoissonSolve(const TArray<int32>& InConstrainedNodes,
	const TArray<TV>& ConstrainedWeights,
	const TUniformGrid<T, 3>& UniformGrid,
	const int32 MaxItCG,
	const TV CGTol,
	TArray<TV>& Weights,
	bool bCheckResidual = false,
	int32 MinParallelBatchSize = 1000)
{
	auto ProjectBCs = [&InConstrainedNodes](TArray<TV>& U)
	{
		for (int32 i = 0; i < InConstrainedNodes.Num(); i++)
		{
			U[InConstrainedNodes[i]] = (T)0.;
		}

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/Math/Poisson.h:640

Scope (from outer to inner):

file
namespace    Chaos
function     void PoissonSolve

Source code excerpt:

	MinusResidual.Init((TV)0., Weights.Num());
	MultiplyLaplacian(MinusResidual, InitialGuess);

	TArray<TV> MinusDw;
	MinusDw.Init((TV)0., Weights.Num());
	Chaos::LanczosCG(MultiplyLaplacian, MinusDw, MinusResidual, MaxItCG, CGTol, bCheckResidual, MinParallelBatchSize);
	
	for (int32 i = 0; i < InitialGuess.Num(); i++)
	{
		Weights[i] = InitialGuess[i] - MinusDw[i];
	}
}


} // namespace Chaos