p.Chaos.PBDEvolution.UseNestedParallelFor

p.Chaos.PBDEvolution.UseNestedParallelFor

#Overview

name: p.Chaos.PBDEvolution.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.PBDEvolution.UseNestedParallelFor is to control the use of nested parallel execution in the Position-Based Dynamics (PBD) evolution system within Unreal Engine’s Chaos physics engine.

This setting variable is primarily used by the Chaos physics engine, specifically in the PBD evolution subsystem. Based on the callsites, it’s part of the Experimental Chaos module in Unreal Engine 5.

The value of this variable is set through a console variable (CVarChaosPBDEvolutionUseNestedParallelFor) with a default value of true. It can be changed at runtime using console commands or through code.

This variable interacts with other PBD evolution-related variables, such as CVarChaosPBDEvolutionParallelIntegrate and CVarChaosPBDEvolutionMinParallelBatchSize. These variables work together to control the parallelization of the PBD evolution process.

Developers must be aware that this variable affects the performance and behavior of the physics simulation. Enabling nested parallel execution can potentially improve performance on systems with many cores, but it may also introduce overhead or race conditions if not properly managed.

Best practices when using this variable include:

1. Testing performance with both true and false values to determine the optimal setting for your specific use case.
2. Considering the target hardware when deciding whether to enable nested parallelism.
3. Ensuring that the code is thread-safe when enabling nested parallelism.

Regarding the associated variable CVarChaosPBDEvolutionUseNestedParallelFor:

This is the actual console variable that controls the p.Chaos.PBDEvolution.UseNestedParallelFor setting. It’s defined as a boolean TAutoConsoleVariable, which allows it to be changed at runtime.

The purpose of this variable is the same as p.Chaos.PBDEvolution.UseNestedParallelFor - to control nested parallel execution in the PBD evolution system.

It’s used in the Chaos::Softs::FPBDEvolution::AdvanceOneTimeStep function to determine whether to use single-threaded or multi-threaded execution. The value is retrieved using GetValueOnAnyThread(), indicating that it can be safely accessed from any thread.

Developers should be aware that changing this variable at runtime will immediately affect the physics simulation’s behavior. It’s important to thoroughly test any changes to ensure stability and performance across various scenarios.

Best practices for using this console variable include:

1. Using it for debugging and performance tuning.
2. Documenting any non-default values used in production.
3. Considering its interaction with other PBD evolution settings for optimal performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDEvolution.cpp:32

Scope: file

Source code excerpt:

DECLARE_CYCLE_STAT(TEXT("Chaos XPBD Constraints Init"), STAT_ChaosXPBDConstraintsInit, STATGROUP_Chaos);

TAutoConsoleVariable<bool> CVarChaosPBDEvolutionUseNestedParallelFor(TEXT("p.Chaos.PBDEvolution.UseNestedParallelFor"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosPBDEvolutionFastPositionBasedFriction(TEXT("p.Chaos.PBDEvolution.FastPositionBasedFriction"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosPBDEvolutionUseSmoothTimeStep(TEXT("p.Chaos.PBDEvolution.UseSmoothTimeStep"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<int32> CVarChaosPBDEvolutionMinParallelBatchSize(TEXT("p.Chaos.PBDEvolution.MinParallelBatchSize"), 300, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosPBDEvolutionWriteCCDContacts(TEXT("p.Chaos.PBDEvolution.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> CVarChaosPBDEvolutionParallelIntegrate(TEXT("p.Chaos.PBDEvolution.ParalleIntegrate"), false, TEXT("Run the integration step in parallel for."), ECVF_Cheat);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDEvolution.cpp:32

Scope: file

Source code excerpt:

DECLARE_CYCLE_STAT(TEXT("Chaos XPBD Constraints Init"), STAT_ChaosXPBDConstraintsInit, STATGROUP_Chaos);

TAutoConsoleVariable<bool> CVarChaosPBDEvolutionUseNestedParallelFor(TEXT("p.Chaos.PBDEvolution.UseNestedParallelFor"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosPBDEvolutionFastPositionBasedFriction(TEXT("p.Chaos.PBDEvolution.FastPositionBasedFriction"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosPBDEvolutionUseSmoothTimeStep(TEXT("p.Chaos.PBDEvolution.UseSmoothTimeStep"), true, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<int32> CVarChaosPBDEvolutionMinParallelBatchSize(TEXT("p.Chaos.PBDEvolution.MinParallelBatchSize"), 300, TEXT(""), ECVF_Cheat);
TAutoConsoleVariable<bool> CVarChaosPBDEvolutionWriteCCDContacts(TEXT("p.Chaos.PBDEvolution.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> CVarChaosPBDEvolutionParallelIntegrate(TEXT("p.Chaos.PBDEvolution.ParalleIntegrate"), false, TEXT("Run the integration step in parallel for."), ECVF_Cheat);

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDEvolution.cpp:474

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FPBDEvolution::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 = !CVarChaosPBDEvolutionUseNestedParallelFor.GetValueOnAnyThread();
	const int32 MinParallelBatchSize = !CVarChaosPBDEvolutionParallelIntegrate.GetValueOnAnyThread() ?
		TNumericLimits<int32>::Max() :  // Disable
		CVarChaosPBDEvolutionMinParallelBatchSize.GetValueOnAnyThread(); // TODO: 1000 is a guess, tune this!
	const bool bWriteCCDContacts = CVarChaosPBDEvolutionWriteCCDContacts.GetValueOnAnyThread();

	{