p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker

p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker

#Overview

name: p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker

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

• type: Var
• help: The minimum number of constraints we want per worker thread

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker is to set the minimum number of constraints to be processed per worker thread in the Chaos physics solver’s island group system. This setting is part of the Chaos physics engine in Unreal Engine 5, specifically within the island grouping optimization for constraint solving.

The Chaos physics engine, which is part of Unreal Engine’s Experimental module, relies on this setting variable. It is used in the IslandGroupManager, which is responsible for organizing physics objects into groups (islands) for more efficient parallel processing.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 50 and can be adjusted at runtime or through configuration files.

This variable interacts closely with another variable named GIslandGroupsMinConstraintsPerWorker. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the parallelization strategy of the physics solver. Setting it too low might result in too many small tasks, which could impact performance on many-core systems due to increased overhead. Setting it too high might reduce the benefits of parallelization.

Best practices when using this variable include:

1. Adjusting it based on the target hardware’s core count and the typical complexity of physics simulations in the game.
2. Profiling the physics performance with different values to find the optimal setting for specific game scenarios.
3. Considering it in conjunction with other related settings, such as p.Chaos.Solver.IslandGroups.MinBodiesPerWorker.

Regarding the associated variable GIslandGroupsMinConstraintsPerWorker:

The purpose of GIslandGroupsMinConstraintsPerWorker is identical to p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker. It’s the internal representation of the console variable in the C++ code.

This variable is used directly in the FPBDIslandGroupManager::BuildGroups function to determine the target number of constraints per task. It ensures that the number of constraints per task doesn’t fall below this minimum value, which helps in maintaining efficient task distribution across worker threads.

The value of GIslandGroupsMinConstraintsPerWorker is set through the console variable system and can be modified at runtime.

Developers should be aware that changes to p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker will directly affect GIslandGroupsMinConstraintsPerWorker, and vice versa.

Best practices for GIslandGroupsMinConstraintsPerWorker are the same as for p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker, as they represent the same setting.

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// 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
		int32 GIslandGroupsMinConstraintsPerWorker = 50;
		FAutoConsoleVariableRef GCVarIslandGroupsMinConstraintsPerWorker(TEXT("p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker"), GIslandGroupsMinConstraintsPerWorker, TEXT("The minimum number of constraints we want per worker thread"));

		// We want a minimum number of bodies to gather on each thread. This prevents us running too many tiny tasks on a many-core machine
		int32 GIslandGroupsMinBodiesPerWorker = 50;
		FAutoConsoleVariableRef GCVarIslandGroupsMinBodiesPerWorker(TEXT("p.Chaos.Solver.IslandGroups.MinBodiesPerWorker"), GIslandGroupsMinBodiesPerWorker, TEXT("The minimum number of bodies we want per worker thread"));

	}

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// 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
		int32 GIslandGroupsMinConstraintsPerWorker = 50;
		FAutoConsoleVariableRef GCVarIslandGroupsMinConstraintsPerWorker(TEXT("p.Chaos.Solver.IslandGroups.MinConstraintsPerWorker"), GIslandGroupsMinConstraintsPerWorker, TEXT("The minimum number of constraints we want per worker thread"));

		// We want a minimum number of bodies to gather on each thread. This prevents us running too many tiny tasks on a many-core machine
		int32 GIslandGroupsMinBodiesPerWorker = 50;
		FAutoConsoleVariableRef GCVarIslandGroupsMinBodiesPerWorker(TEXT("p.Chaos.Solver.IslandGroups.MinBodiesPerWorker"), GIslandGroupsMinBodiesPerWorker, TEXT("The minimum number of bodies we want per worker thread"));

	}

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    Private
function     int32 FPBDIslandGroupManager::BuildGroups

Source code excerpt:

			// would outweight the benefits of going wide.
			// @todo(chaos): we may want to consider separating the gather task count from the number of island groups by adding a second multiplier.
			TargetNumConstraintsPerTask = FMath::Max(TargetNumConstraintsPerTask, CVars::GIslandGroupsMinConstraintsPerWorker);
			TargetNumBodiesPerTask = FMath::Max(TargetNumConstraintsPerTask, CVars::GIslandGroupsMinBodiesPerWorker);

			// Reset all the groups
			for (TUniquePtr<FPBDIslandConstraintGroupSolver>& IslandGroup : IslandGroups)
			{
				IslandGroup->Reset();