p.Chaos.SoftBodyCollision.ISPC.ParallelBatchSize

p.Chaos.SoftBodyCollision.ISPC.ParallelBatchSize

#Overview

name: p.Chaos.SoftBodyCollision.ISPC.ParallelBatchSize

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.SoftBodyCollision.ISPC.ParallelBatchSize is to control the parallel batch size for ISPC (Intel SPMD Program Compiler) in the context of soft body collision processing within Unreal Engine’s Chaos physics system.

This setting variable is primarily used by the Chaos physics system, specifically in the soft body collision module. It’s part of the experimental Chaos namespace, indicating that it’s used in the newer, more advanced physics simulation features of Unreal Engine.

The value of this variable is set to a default of 128, as seen in the static variable declaration. It can be modified at runtime through the console variable system, but only in non-shipping builds.

This variable interacts closely with its associated variable Chaos_SoftBodyCollision_ISPC_ParallelBatchSize. They share the same value, with the console variable (p.Chaos.SoftBodyCollision.ISPC.ParallelBatchSize) providing a way to modify the static variable (Chaos_SoftBodyCollision_ISPC_ParallelBatchSize) at runtime.

Developers must be aware that this variable affects the parallelization of soft body collision calculations. It determines the size of batches processed in parallel, which can impact performance and potentially simulation accuracy.

Best practices when using this variable include:

  1. Experimenting with different values to find the optimal balance between performance and simulation quality for your specific use case.
  2. Being cautious about modifying it in shipping builds, as it’s only exposed in non-shipping builds by default.
  3. Considering the hardware capabilities of your target platforms when adjusting this value, as optimal batch sizes may vary depending on available computational resources.

Regarding the associated variable Chaos_SoftBodyCollision_ISPC_ParallelBatchSize:

This is the actual variable used in the code to determine the batch size for parallel processing. It’s a static variable initialized with a value of 128.

The purpose of this variable is to directly control the number of particles processed in each parallel batch during soft body collision calculations.

It’s used in the Chaos physics system, specifically in the PBDSoftBodyCollisionConstraint module. This is evident from its usage in the ApplyInternalISPC function of the FPBDSoftBodyCollisionConstraintBase class.

The value of this variable is set at compile-time but can be modified at runtime through the associated console variable in non-shipping builds.

Developers should be aware that this variable directly impacts the parallelization strategy of the soft body collision system. Changing its value will affect how work is distributed across available processing units.

Best practices for this variable include:

  1. Profiling your application to determine if the default value is optimal for your use case.
  2. If modifying, ensure thorough testing across various scenarios and hardware configurations.
  3. Remember that while a larger batch size might improve parallelization, it could also increase memory usage and potentially reduce cache efficiency.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDSoftBodyCollisionConstraint.cpp:118

Scope: file

Source code excerpt:

static int32 Chaos_SoftBodyCollision_ISPC_ParallelBatchSize = 128;
#if !UE_BUILD_SHIPPING
FAutoConsoleVariableRef CVarChaosSoftBodyCollisionISPCParallelBatchSize(TEXT("p.Chaos.SoftBodyCollision.ISPC.ParallelBatchSize"), Chaos_SoftBodyCollision_ISPC_ParallelBatchSize, TEXT("Parallel batch size for ISPC"));
#endif

namespace Chaos::Softs {

// Helper function to call PhiWithNormal and return data to ISPC
extern "C" void GetPhiWithNormalCollisionParticleRange(const uint8 * CollisionParticlesRange, const FSolverReal * InV, FSolverReal * Normal, FSolverReal * Phi, const int32 i, const int32 ProgramCount, const int32 Mask)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDSoftBodyCollisionConstraint.cpp:116

Scope: file

Source code excerpt:

#endif

static int32 Chaos_SoftBodyCollision_ISPC_ParallelBatchSize = 128;
#if !UE_BUILD_SHIPPING
FAutoConsoleVariableRef CVarChaosSoftBodyCollisionISPCParallelBatchSize(TEXT("p.Chaos.SoftBodyCollision.ISPC.ParallelBatchSize"), Chaos_SoftBodyCollision_ISPC_ParallelBatchSize, TEXT("Parallel batch size for ISPC"));
#endif

namespace Chaos::Softs {

// Helper function to call PhiWithNormal and return data to ISPC
extern "C" void GetPhiWithNormalCollisionParticleRange(const uint8 * CollisionParticlesRange, const FSolverReal * InV, FSolverReal * Normal, FSolverReal * Phi, const int32 i, const int32 ProgramCount, const int32 Mask)

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDSoftBodyCollisionConstraint.cpp:457

Scope (from outer to inner):

file
namespace    Chaos::Softs
function     void FPBDSoftBodyCollisionConstraintBase::ApplyInternalISPC

Source code excerpt:

#if INTEL_ISPC
	check(bRealTypeCompatibleWithISPC);
	const int32 NumBatches = FMath::CeilToInt((FSolverReal)(Particles.GetRangeSize()) / (FSolverReal)Chaos_SoftBodyCollision_ISPC_ParallelBatchSize);
	PhysicsParallelFor(NumBatches, [this, &Particles, Dt, &CollisionParticles](int32 BatchNumber)
	{
		const int32 BatchBegin = (Chaos_SoftBodyCollision_ISPC_ParallelBatchSize * BatchNumber);
		const int32 BatchEnd = FMath::Min(Particles.GetRangeSize(), BatchBegin + Chaos_SoftBodyCollision_ISPC_ParallelBatchSize);

		for (const FSolverCollisionParticlesRange& CollisionParticlesRange : CollisionParticles)
		{
			if constexpr (bWithFriction)
			{
				ispc::ApplyPerParticleCollisionFastFrictionNoGroupCheck(