p.Chaos.Solver.IslandGroups.WorkerMultiplier

p.Chaos.Solver.IslandGroups.WorkerMultiplier

#Overview

name: p.Chaos.Solver.IslandGroups.WorkerMultiplier

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.IslandGroups.WorkerMultiplier is to control the number of island groups used in the Chaos physics solver. It is a multiplier that, when combined with the number of worker threads, determines the total number of island groups in the solver.

This setting variable is primarily used in the Chaos physics system, which is part of Unreal Engine’s experimental physics simulation module. It specifically affects the island group management within the solver, which is crucial for parallel processing of physics simulations.

The value of this variable is set through a console variable (CVar) system. It’s defined and initialized in the Chaos namespace, within the CVars namespace, in the IslandGroupManager.cpp file.

The associated variable GIslandGroupsWorkerMultiplier directly interacts with p.Chaos.Solver.IslandGroups.WorkerMultiplier. They share the same value, with GIslandGroupsWorkerMultiplier being the actual variable used in the code, while p.Chaos.Solver.IslandGroups.WorkerMultiplier is the console variable name used for external access and modification.

Developers must be aware that this variable directly impacts the parallelization of physics simulations. Increasing this value will create more island groups, potentially improving performance on systems with many cores, but it may also increase overhead.

Best practices when using this variable include:

  1. Adjusting it based on the target hardware’s core count.
  2. Balancing it with other physics-related settings for optimal performance.
  3. Testing thoroughly after modifications, as it can significantly impact physics simulation performance and behavior.

Regarding the associated variable GIslandGroupsWorkerMultiplier:

The purpose of GIslandGroupsWorkerMultiplier is to store the actual value used in the code for calculating the number of island groups. It’s directly linked to the p.Chaos.Solver.IslandGroups.WorkerMultiplier console variable.

This variable is used within the Chaos physics system, specifically in the island group management part of the solver.

The value is set initially to 1 in the code, but can be modified at runtime through the associated console variable.

It interacts directly with the number of worker threads to determine the total number of island groups. The calculation is done in the FPBDIslandGroupManager constructor.

Developers should be aware that this variable directly affects the parallelization strategy of the physics solver. Modifying it can have significant performance implications.

Best practices include careful tuning based on profiling results and target hardware specifications, and ensuring that changes to this variable are tested thoroughly across various scenarios in the game or application.

#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:36

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// 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)
		int32 GIslandGroupsMaxWorkers = 0;
		FAutoConsoleVariableRef GCVarIslandGroupsMaxWorkers(TEXT("p.Chaos.Solver.IslandGroups.MaxWorkers"), GIslandGroupsMaxWorkers, TEXT("The maximum number of worker threads to use (0 means unlimited)"));

		// We want a minimum number of constraints to gather/solve/scatter on each thread. This prevents us running too many tiny tasks on a many-core machine

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		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)
		int32 GIslandGroupsMaxWorkers = 0;
		FAutoConsoleVariableRef GCVarIslandGroupsMaxWorkers(TEXT("p.Chaos.Solver.IslandGroups.MaxWorkers"), GIslandGroupsMaxWorkers, TEXT("The maximum number of worker threads to use (0 means unlimited)"));

		// We want a minimum number of constraints to gather/solve/scatter on each thread. This prevents us running too many tiny tasks on a many-core machine

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    Private
function     FPBDIslandGroupManager::FPBDIslandGroupManager

Source code excerpt:

			NumWorkerThreads = (FApp::ShouldUseThreadingForPerformance() && !GSingleThreadedPhysics) ? FMath::Min(FTaskGraphInterface::Get().GetNumWorkerThreads(), Chaos::MaxNumWorkers) : 0;
			const int32 MaxIslandGroups = (CVars::GIslandGroupsMaxWorkers > 0) ? CVars::GIslandGroupsMaxWorkers : TNumericLimits<int32>::Max();
			const int32 NumIslandGroups = FMath::Clamp(FMath::CeilToInt32(FReal(NumWorkerThreads) * CVars::GIslandGroupsWorkerMultiplier), 1, MaxIslandGroups);

			IslandGroups.Reserve(NumIslandGroups);
			for (int32 GroupIndex = 0; GroupIndex < NumIslandGroups; ++GroupIndex)
			{
				IslandGroups.Emplace(MakeUnique<FPBDIslandConstraintGroupSolver>(IslandManager));
			}