p.Chaos.Solver.InertiaConditioning.Distance

p.Chaos.Solver.InertiaConditioning.Distance

#Overview

name: p.Chaos.Solver.InertiaConditioning.Distance

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.Solver.InertiaConditioning.Distance is to serve as an input to the inertia conditioning system within the Chaos physics solver in Unreal Engine 5. Specifically, it represents the largest joint distance error that the system expects to resolve in a moderately stable manner.

This setting variable is primarily used by the Chaos physics system, which is part of Unreal Engine’s experimental physics framework. Based on the callsites, it’s utilized in the PBDRigidsEvolutionGBF (Position Based Dynamics Rigid Bodies Evolution) module.

The value of this variable is set through a console variable system, allowing it to be adjusted at runtime. It’s initialized with a default value of 20 and can be modified using the console command “p.Chaos.Solver.InertiaConditioning.Distance”.

The associated variable ChaosSolverInertiaConditioningDistance directly interacts with p.Chaos.Solver.InertiaConditioning.Distance. They share the same value, with ChaosSolverInertiaConditioningDistance being the actual variable used in the code logic.

Developers must be aware that this variable affects the stability of joint error resolution in the physics simulation. A higher value allows for larger joint errors to be considered “stable”, while a lower value enforces stricter stability requirements.

Best practices when using this variable include:

  1. Carefully adjusting its value based on the specific needs of the simulation.
  2. Monitoring the simulation’s stability when changing this value.
  3. Considering the relationship between this value and other physics parameters, such as constraint teleport thresholds.

Regarding the associated variable ChaosSolverInertiaConditioningDistance:

The purpose of ChaosSolverInertiaConditioningDistance is to store and provide access to the value set by p.Chaos.Solver.InertiaConditioning.Distance within the code.

This variable is used directly in the UpdateInertiaConditioning function of the FPBDRigidsEvolutionGBF class, which is part of the Chaos physics solver.

Its value is set by the console variable system when p.Chaos.Solver.InertiaConditioning.Distance is modified.

It interacts closely with other variables in the inertia conditioning system, such as ChaosSolverInertiaConditioningRotationRatio and ChaosSolverMaxInvInertiaComponentRatio.

Developers should be aware that this variable directly influences the physics calculations for rigid body evolution in the Chaos system.

Best practices include ensuring that any code modifications involving this variable are consistent with the intended behavior of the inertia conditioning system and thoroughly testing any changes to avoid unintended consequences in the physics simulation.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolutionGBF.cpp:106

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// The largest joint error we expect to resolve in a moderately stable way
		FRealSingle ChaosSolverInertiaConditioningDistance = 20;
		FAutoConsoleVariableRef  CVarChaosSolverInertiaConditioningDistance(TEXT("p.Chaos.Solver.InertiaConditioning.Distance"), ChaosSolverInertiaConditioningDistance, TEXT("An input to inertia conditioning system. The joint distance error which needs to be stable (generate a low rotation)."));

		// The ratio of joint error correction that comes from particle rotation versus translation
		FRealSingle ChaosSolverInertiaConditioningRotationRatio = 2;
		FAutoConsoleVariableRef  CVarChaosSolverInertiaConditioningRotationRatio(TEXT("p.Chaos.Solver.InertiaConditioning.RotationRatio"), ChaosSolverInertiaConditioningRotationRatio, TEXT("An input to inertia conditioning system. The maximum ratio of joint correction from rotation versus translation"));

		// If > 1, limits the inverse inertia components to be mo more than this multiple of the smallest component. Makes the objects more round. Set to 0 to disable.

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolutionGBF.cpp:105

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:


		// The largest joint error we expect to resolve in a moderately stable way
		FRealSingle ChaosSolverInertiaConditioningDistance = 20;
		FAutoConsoleVariableRef  CVarChaosSolverInertiaConditioningDistance(TEXT("p.Chaos.Solver.InertiaConditioning.Distance"), ChaosSolverInertiaConditioningDistance, TEXT("An input to inertia conditioning system. The joint distance error which needs to be stable (generate a low rotation)."));

		// The ratio of joint error correction that comes from particle rotation versus translation
		FRealSingle ChaosSolverInertiaConditioningRotationRatio = 2;
		FAutoConsoleVariableRef  CVarChaosSolverInertiaConditioningRotationRatio(TEXT("p.Chaos.Solver.InertiaConditioning.RotationRatio"), ChaosSolverInertiaConditioningRotationRatio, TEXT("An input to inertia conditioning system. The maximum ratio of joint correction from rotation versus translation"));

		// If > 1, limits the inverse inertia components to be mo more than this multiple of the smallest component. Makes the objects more round. Set to 0 to disable.

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolutionGBF.cpp:1645

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDRigidsEvolutionGBF::UpdateInertiaConditioning

Source code excerpt:

	// The error distance that the constraint correction must be stable for
	// @todo(chaos): should probably be tied to constraint teleport threshold?
	const FRealSingle MaxDistance = ChaosSolverInertiaConditioningDistance;

	// A limit on the relative sizes of the inertia components (inverse)
	const FRealSingle MaxInvInertiaComponentRatio = ChaosSolverMaxInvInertiaComponentRatio;

	// @todo(chaos): we should only visit particles that are dirty
	for (auto& Rigid : Particles.GetNonDisabledDynamicView())