ComputingSettings

Qualified name: algan.settings.computing\_settings.ComputingSettings

class ComputingSettings(render_device=<factory>, mps_friendly='auto', torch_compile='auto', animation_memory_fraction=0.15, rendering_memory_fraction=0.4, max_animation_batch_size=10000, cpu_render_memory_budget=<factory>, available_memory_override=None, use_torch_scatter=True, prefetch_gpu_prep=False, overlap_pool_headroom_fraction=0.6)

Bases: Settings

Runtime-adjustable memory, device and authoring controls.

render_device is settable here; the animation device is not – set ALGAN_ANIMATION_DEVICE before importing Algan.

available_memory_override pins what get_num_available_bytes() reports for a measured device (CUDA, MPS), in bytes; None (the default) measures the device for real. It exists for reproducibility, not for capacity.

Free device memory is not reproducible – it shrinks once the Torch and Taichi allocators are warm and moves with anything else on the GPU – and the render loop sizes its frame windows from it (the arena, and the merge headroom the batch preflight weighs). A different window split carries a different set of not-yet-spawned actors and pads the merged arrays to a different width, which reorders them and the STBVH; shared-edge depth ties then land differently and silhouette pixels move by far more than the rounding a pixel-comparison suite budgets for. Pinning the measurement makes a render byte-reproducible across processes.

The value must be affordable on the device: it replaces the measurement rather than capping it, so a value larger than the device can supply over-commits and falls back to the render loop’s out-of-memory retry – which re-splits the window and gives up the reproducibility this buys.

Methods

set	Apply settings, refusing a render-device change that is too late.
set_animation_memory_fraction	Set 'animation_memory_fraction', or return a modified preset copy.
set_available_memory_override	Set 'available_memory_override', or return a modified preset copy.
set_cpu_render_memory_budget	Set 'cpu_render_memory_budget', or return a modified preset copy.
set_max_animation_batch_size	Set 'max_animation_batch_size', or return a modified preset copy.
set_mps_friendly	Set 'mps_friendly', or return a modified preset copy.
set_overlap_pool_headroom_fraction	Set 'overlap_pool_headroom_fraction', or return a modified preset copy.
set_prefetch_gpu_prep	Set 'prefetch_gpu_prep', or return a modified preset copy.
set_render_device	Set 'render_device', or return a modified preset copy.
set_rendering_memory_fraction	Set 'rendering_memory_fraction', or return a modified preset copy.
set_torch_compile	Set 'torch_compile', or return a modified preset copy.
set_use_torch_scatter	Set 'use_torch_scatter', or return a modified preset copy.

Attributes

animation_memory_fraction
available_memory_override
is_preset
max_animation_batch_size
mps_friendly	Restrict the renderer to operations Apple's Metal backend can run: float32 in place of every float64 accumulator, int32 in place of the int64 min/max reductions, and a scan of maximum/minimum in place of cummax/cummin.
overlap_pool_headroom_fraction	Share of RenderLoopMixin._gpu_merge_headroom_bytes() an overlapped (worker-side) projection or merge must fit its predicted peak in -- the rest of that headroom belongs to the render running beside it.
prefetch_gpu_prep	Let the batch-prep worker run the render-device projection and scene merge of batch b+1 while batch b renders, instead of deferring both to the render thread's arena preflight.
rendering_memory_fraction
torch_compile	Run the pipeline's per-frame torch arithmetic -- timeline materialization, projection and shading, the sheet compaction, the post-processing chain -- through torch.compile, which fuses each chain of small tensor operations into one kernel.
use_torch_scatter
render_device	Where render primitives are built and the ray tracer runs.
cpu_render_memory_budget	Budget a CPU render may size its renderer-owned working memory against, in bytes.

Parameters:

• render_device (device)

• mps_friendly (bool | str)

• torch_compile (bool | str)

• animation_memory_fraction (float)

• rendering_memory_fraction (float)

• max_animation_batch_size (int)

• cpu_render_memory_budget (int)

• available_memory_override (int | None)

• use_torch_scatter (bool)

• prefetch_gpu_prep (bool)

• overlap_pool_headroom_fraction (float)

cpu_render_memory_budget: int

Budget a CPU render may size its renderer-owned working memory against, in bytes.

This is deliberately a renderer budget, not a process RSS limit: Python, PyTorch/LLVM allocator retention, the Quadrants runtime/JIT, encoders and child processes all live outside it. Host-pressure cleanup in release_torch_memory is what deals with those allocations when the enclosing machine/cgroup gets tight.

This is the CPU analogue of the device queries the CUDA and MPS branches of get_num_available_bytes make, and it used to be a flat 2 GB. The render arena is rendering_memory_fraction (0.4) of it, so that gave every CPU machine a 0.75 GB arena – which does not hold one 4K frame, so a UHD CPU render died with “Insufficient memory to ray trace a single frame” on a 7 GB laptop and on a 512 GB workstation alike. It is the same shape of defect as the 1 GiB clamp the MPS branch carried, and it was found the same way: by rendering the scene and reading the error.

So it defaults to a share of the machine’s RAM, the figure the MPS branch is capped against, and stays an explicit setting for anyone who wants to pin it. psutil is already a dependency; the fallback keeps the old constant for a platform that cannot report its memory.

mps_friendly: bool | str = 'auto'

Restrict the renderer to operations Apple’s Metal backend can run: float32 in place of every float64 accumulator, int32 in place of the int64 min/max reductions, and a scan of maximum/minimum in place of cummax/cummin. 'auto' (the default) turns it on exactly when the render device is MPS and leaves every other device on the float64 path; True/False decide for themselves, which is what makes the mode testable on a machine with no Apple GPU. Env override ALGAN_MPS_FRIENDLY. Read it through algan.rendering.mps_compat.mps_friendly(), which is where the resolution and the substitutions it selects are documented.

The mode is not deterministic: the accumulators it narrows are the ones §6.6.4 widened precisely because a float32 sum is not order-reproducible, so two renders of one scene may differ in their low bits. That is the trade MPS forces – Metal has no float64 at all – and it is why the mode is off wherever float64 is available.

overlap_pool_headroom_fraction: float = 0.6

Share of RenderLoopMixin._gpu_merge_headroom_bytes() an overlapped (worker-side) projection or merge must fit its predicted peak in – the rest of that headroom belongs to the render running beside it. Only consulted when prefetch_gpu_prep is active; the render thread’s own preflight keeps the full headroom. Env override ALGAN_OVERLAP_HEADROOM_FRACTION.

prefetch_gpu_prep: bool = False

Let the batch-prep worker run the render-device projection and scene merge of batch b+1 while batch b renders, instead of deferring both to the render thread’s arena preflight. The transient-peak predictors must already be calibrated (the first batch always prepares on the render thread), overlapped builds skip their peak observations, and the pool headroom the worker checks against is derated by overlap_pool_headroom_fraction to leave room for the concurrent render. Env override ALGAN_PREFETCH_GPU_PREP. Default off.

render_device: device

Where render primitives are built and the ray tracer runs. Accepts a torch.device, a device string, or 'auto' (what ALGAN_RENDER_DEVICE defaults to), and is normalized to a torch.device. Read it through algan.settings._startup.render_device(), never by binding it at import. Changing it re-selects Taichi’s arch at the next render, which costs one kernel-preparation pass (the compiled kernels of the old arch are discarded), so switch once at the top of a script rather than between renders.

set(source=None, **kwargs)

Apply settings, refusing a render-device change that is too late.

The check runs before the base class writes anything: a rejected change must leave the section exactly as it was, not half-applied.

set_animation_memory_fraction(value)

Set ‘animation_memory_fraction’, or return a modified preset copy.

set_available_memory_override(value)

Set ‘available_memory_override’, or return a modified preset copy.

set_cpu_render_memory_budget(value)

Set ‘cpu_render_memory_budget’, or return a modified preset copy.

set_max_animation_batch_size(value)

Set ‘max_animation_batch_size’, or return a modified preset copy.

set_mps_friendly(value)

Set ‘mps_friendly’, or return a modified preset copy.

set_overlap_pool_headroom_fraction(value)

Set ‘overlap_pool_headroom_fraction’, or return a modified preset copy.

set_prefetch_gpu_prep(value)

Set ‘prefetch_gpu_prep’, or return a modified preset copy.

set_render_device(value)

Set ‘render_device’, or return a modified preset copy.

set_rendering_memory_fraction(value)

Set ‘rendering_memory_fraction’, or return a modified preset copy.

set_torch_compile(value)

Set ‘torch_compile’, or return a modified preset copy.

set_use_torch_scatter(value)

Set ‘use_torch_scatter’, or return a modified preset copy.

torch_compile: bool | str = 'auto'

Run the pipeline’s per-frame torch arithmetic – timeline materialization, projection and shading, the sheet compaction, the post-processing chain – through torch.compile, which fuses each chain of small tensor operations into one kernel. 'auto' (the default) is on wherever torch.compile runs and off where it does not (Windows, a Python that Dynamo does not support) or where its backend is not trustworthy yet (Metal – PyTorch calls that backend an early prototype, and on this codebase it fails on _triangle_projection_fused in every run and crashed a UHD render outright on a SymInt shape; see benchmarks/performance/reports/mac_2026_09/FINDINGS.md §7.5). True tries regardless and False is off everywhere, so the Metal backend stays re-testable once PyTorch fixes it.

A function whose compile fails warns once and runs eagerly, so that much cannot fail a render. A backend that compiles and then generates wrong code still can, which is what the Metal default is for. The first render of a process pays the compile (seconds per function on the CPU, cached across processes by Inductor); every later one is faster. Env override ALGAN_TORCH_COMPILE. Read it through algan.utils.torch_compile.torch_compile_enabled().