p.Chaos.Solver.IslandGroups.ParallelMode

p.Chaos.Solver.IslandGroups.ParallelMode

#Overview

name: p.Chaos.Solver.IslandGroups.ParallelMode

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

• type: Var
• help: 0: Single-Threaded; 1: Parallel-For; 2: Tasks

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Solver.IslandGroups.ParallelMode is to control the parallelization mode for solving island groups in the Chaos physics solver within Unreal Engine 5. This setting variable is specifically for the physics simulation system, particularly the Chaos solver.

The Unreal Engine subsystem that relies on this setting variable is the Chaos physics system, which is part of the Experimental module. This can be seen from the file path and namespace in the callsites.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 2 and can be changed at runtime using the console command “p.Chaos.Solver.IslandGroups.ParallelMode”.

This variable interacts directly with the associated variable GIslandGroupsParallelMode. They share the same value, with GIslandGroupsParallelMode being the actual int32 variable used in the code, while p.Chaos.Solver.IslandGroups.ParallelMode is the console-accessible name.

Developers must be aware that this variable controls the parallelization strategy for the island group solver, which can significantly impact performance and behavior of the physics simulation. The variable accepts three values: 0: Single-Threaded 1: Parallel-For 2: Tasks (default)

Best practices when using this variable include:

1. Use the default value (2) for most scenarios, as it likely provides the best balance of performance and stability.
2. If experiencing issues with physics simulation, try changing this value to see if it resolves the problem.
3. For debugging purposes, using the single-threaded mode (0) can be helpful to isolate issues.
4. Consider the target hardware when choosing a mode, as different parallelization strategies may perform differently on various systems.

Regarding the associated variable GIslandGroupsParallelMode:

• Its purpose is to store the actual integer value used by the Chaos solver to determine the parallelization mode.
• It’s used directly in the Chaos solver code to switch between different solving methods (SolveSerial, SolveParallelFor, or SolveParallelTasks).
• The value is set through the CVar system and can be changed at runtime.
• Developers should be aware that changing this value directly in code instead of through the CVar system may lead to inconsistent behavior.
• Best practice is to always use the CVar p.Chaos.Solver.IslandGroups.ParallelMode to modify this value, ensuring that both the console variable and the actual variable used in code stay synchronized.

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		//   2: Tasks
		int32 GIslandGroupsParallelMode = 2;
		FAutoConsoleVariableRef GCVarIslandGroupsParallelMode(TEXT("p.Chaos.Solver.IslandGroups.ParallelMode"), GIslandGroupsParallelMode, TEXT("0: Single-Threaded; 1: Parallel-For; 2: Tasks"));

		// Cvar to control the number of island groups used in the solver. The total number will be NumThreads * GIslandGroupsWorkerMultiplier
		FRealSingle GIslandGroupsWorkerMultiplier = 1;
		FAutoConsoleVariableRef GCVarIslandGroupsWorkerThreadMultiplier(TEXT("p.Chaos.Solver.IslandGroups.WorkerMultiplier"), GIslandGroupsWorkerMultiplier, TEXT("Total number of island groups in the solver will be NumWorkerThreads * WorkerThreadMultiplier. [def:1]"));

		// Do not use more worker threads than this for the main solve (0 for unlimited)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Island/IslandGroupManager.cpp:31

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		//   1: Parallel-For
		//   2: Tasks
		int32 GIslandGroupsParallelMode = 2;
		FAutoConsoleVariableRef GCVarIslandGroupsParallelMode(TEXT("p.Chaos.Solver.IslandGroups.ParallelMode"), GIslandGroupsParallelMode, TEXT("0: Single-Threaded; 1: Parallel-For; 2: Tasks"));

		// Cvar to control the number of island groups used in the solver. The total number will be NumThreads * GIslandGroupsWorkerMultiplier
		FRealSingle GIslandGroupsWorkerMultiplier = 1;
		FAutoConsoleVariableRef GCVarIslandGroupsWorkerThreadMultiplier(TEXT("p.Chaos.Solver.IslandGroups.WorkerMultiplier"), GIslandGroupsWorkerMultiplier, TEXT("Total number of island groups in the solver will be NumWorkerThreads * WorkerThreadMultiplier. [def:1]"));

		// Do not use more worker threads than this for the main solve (0 for unlimited)

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Island/IslandGroupManager.cpp:554

Scope (from outer to inner):

file
namespace    Chaos
namespace    Private
function     void FPBDIslandGroupManager::Solve

Source code excerpt:

			// @todo(chaos): Remove SolveParallelFor when SolveParallelTasks has been thoroughly tested
			const bool bSingleThreaded = GSingleThreadedPhysics || (IslandGroups.Num() == 1);
			const int32 ParallelMode = bSingleThreaded ? 0 : CVars::GIslandGroupsParallelMode;
			switch (ParallelMode)
			{
			case 0:
				SolveSerial(Dt);
				break;
			case 1: