p.Chaos.NewtonEvolution.UseNestedParallelFor

p.Chaos.NewtonEvolution.UseNestedParallelFor

#Overview

name: p.Chaos.NewtonEvolution.UseNestedParallelFor

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

• type: Var
• help: ``

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.NewtonEvolution.UseNestedParallelFor is to control the use of nested parallel execution in the Newton Evolution algorithm within Unreal Engine’s Chaos physics system.

This setting variable is primarily used in the Chaos physics subsystem, specifically in the Newton Evolution module. It’s part of the experimental Chaos physics engine in Unreal Engine 5.

The value of this variable is set as a console variable (CVar) in the Unreal Engine. It’s initialized with a default value of true, indicating that nested parallel execution is enabled by default.

The associated variable CVarChaosNewtonEvolutionUseNestedParallelFor directly interacts with p.Chaos.NewtonEvolution.UseNestedParallelFor. They share the same value and purpose.

Developers must be aware that this variable affects the parallelization strategy of the Newton Evolution algorithm. When set to true, it allows for nested parallel execution, which can potentially improve performance on systems with many cores. However, it may not always be beneficial, depending on the specific simulation scenarios and hardware.

Best practices when using this variable include:

1. Testing performance with both true and false values to determine which works best for your specific use case.
2. Considering the target hardware when deciding whether to enable or disable nested parallelization.
3. Using in conjunction with other related variables like CVarChaosNewtonEvolutionMinParallelBatchSize to fine-tune performance.

Regarding the associated variable CVarChaosNewtonEvolutionUseNestedParallelFor:

This is the actual C++ variable that controls the behavior specified by p.Chaos.NewtonEvolution.UseNestedParallelFor. It’s defined as a TAutoConsoleVariable, which means it can be changed at runtime through the console.

The variable is used in the AdvanceOneTimeStep function of the FNewtonEvolution class. It determines whether single-threaded or multi-threaded execution should be used for certain operations.

Developers should be aware that changing this variable at runtime can have immediate effects on the physics simulation’s performance and behavior. It’s important to profile and test thoroughly when adjusting this setting.

Best practices for using CVarChaosNewtonEvolutionUseNestedParallelFor include:

1. Using it in conjunction with performance profiling tools to understand its impact.
2. Considering its interaction with other parallelization settings in the Chaos system.
3. Potentially exposing it as a user-configurable setting in performance-critical applications, allowing end-users to optimize for their specific hardware.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/NewtonEvolution.cpp:33

Scope: file

Source code excerpt:

//DECLARE_CYCLE_STAT(TEXT("Chaos Newton Constraints Init"), STAT_ChaosXNewtonConstraintsInit, STATGROUP_Chaos);

TAutoConsoleVariable<bool> CVarChaosNewtonEvolutionUseNestedParallelFor(TEXT("p.Chaos.NewtonEvolution.UseNestedParallelFor"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosNewtonEvolutionFastPositionBasedFriction(TEXT("p.Chaos.NewtonEvolution.FastPositionBasedFriction"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosNewtonEvolutionUseSmoothTimeStep(TEXT("p.Chaos.NewtonEvolution.UseSmoothTimeStep"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<int32> CVarChaosNewtonEvolutionMinParallelBatchSize(TEXT("p.Chaos.NewtonEvolution.MinParallelBatchSize"), 300, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosNewtonEvolutionWriteCCDContacts(TEXT("p.Chaos.NewtonEvolution.WriteCCDContacts"), false, TEXT("Write CCD collision contacts and normals potentially causing the CCD collision threads to lock, allowing for debugging of these contacts."), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosNewtonEvolutionParallelIntegrate(TEXT("p.Chaos.NewtonEvolution.ParalleIntegrate"), false, TEXT("Run the integration step in parallel for."), ECVF_Cheat);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/NewtonEvolution.cpp:33

Scope: file

Source code excerpt:

//DECLARE_CYCLE_STAT(TEXT("Chaos Newton Constraints Init"), STAT_ChaosXNewtonConstraintsInit, STATGROUP_Chaos);

TAutoConsoleVariable<bool> CVarChaosNewtonEvolutionUseNestedParallelFor(TEXT("p.Chaos.NewtonEvolution.UseNestedParallelFor"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosNewtonEvolutionFastPositionBasedFriction(TEXT("p.Chaos.NewtonEvolution.FastPositionBasedFriction"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosNewtonEvolutionUseSmoothTimeStep(TEXT("p.Chaos.NewtonEvolution.UseSmoothTimeStep"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<int32> CVarChaosNewtonEvolutionMinParallelBatchSize(TEXT("p.Chaos.NewtonEvolution.MinParallelBatchSize"), 300, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosNewtonEvolutionWriteCCDContacts(TEXT("p.Chaos.NewtonEvolution.WriteCCDContacts"), false, TEXT("Write CCD collision contacts and normals potentially causing the CCD collision threads to lock, allowing for debugging of these contacts."), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosNewtonEvolutionParallelIntegrate(TEXT("p.Chaos.NewtonEvolution.ParalleIntegrate"), false, TEXT("Run the integration step in parallel for."), ECVF_Cheat);

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/NewtonEvolution.cpp:701

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FNewtonEvolution::AdvanceOneTimeStep

Source code excerpt:

		// Don't bother with threaded execution if we don't have enough work to make it worth while.
		const bool bUseSingleThreadedRange = !CVarChaosNewtonEvolutionUseNestedParallelFor.GetValueOnAnyThread();
		const int32 MinParallelBatchSize = !CVarChaosNewtonEvolutionParallelIntegrate.GetValueOnAnyThread() ?
			TNumericLimits<int32>::Max() :  // Disable
			CVarChaosNewtonEvolutionMinParallelBatchSize.GetValueOnAnyThread(); // TODO: 1000 is a guess, tune this!
		const bool bWriteCCDContacts = CVarChaosNewtonEvolutionWriteCCDContacts.GetValueOnAnyThread();

		{