Configuration reference

class TrackGenConfig

Bases: object

Single configuration object passed to every stage of the pipeline.

Fields configure the fixed-shape Warp pipeline. Scalar style knobs are used by default; opt-in per-env style sampling is available through style_sampling and the *_range fields for the Bezier generator. Only relax_solver="xpbd" is used by the runtime path; the energy_*, tp_*, and smooth_finish* fields serve the torch oracle backends in tests/_oracle/ and are not used by TrackGenerator. The Fourier fields (num_harmonics, decay_p, amplitude, num_centerline_samples) are retained only for compatibility with track_gen._experimental.fourier and older experiment sweeps.

generator

Registered generator name. One of "bezier" (default), "hull", "polar", "voronoi", or "checkpoint". Resolved through track_gen._src.generator_registry at TrackGenerator construction time.

Type:

str

device

Warp device string: "cpu" (GPU-free, for tests/CI) or "cuda" (captures a replay graph on first generate() call).

Type:

str

num_envs

Number of environments in the batch. Must be >= 1. Determines the leading dimension of all output arrays.

Type:

int

min_num_points

Minimum Bezier/hull corner-anchor count per env. Must be >= 2. Shared by the "bezier" and "hull" generators; feeds wp.randi with the range [min_num_points, max_num_points].

Type:

int

max_num_points

Maximum corner-anchor count per env. Must be >= min_num_points. A wider range adds more per-env diversity in corner count.

Type:

int

num_points_per_segment

Dense Bezier (or Catmull-Rom) samples emitted per corner-to-corner segment before arc-resampling to num_points. Must be >= 2; higher values give the arc-resampler a finer cumulative-arc-length grid, reducing interpolation error.

Type:

int

min_point_distance

Minimum grid-cell spacing for corner-position sampling. Must be in (0, 0.5]. Governs the cell grid as num_cells = int(1 / (min_point_distance * 2)).

Type:

float

min_angle

Minimum interior angle (radians) at constrained Bezier corners; default ~0.218 rad (12.5 deg). Used by the gate-angle validity kernel in warp_generate.py; not applied directly to track-centerline generation.

Type:

float

rad

Cubic-Bezier handle length as a fraction of the segment chord — the primary curviness dial. Typical range [0.2, 0.6]. Only live when rad <= handle_clamp_frac; if rad exceeds the clamp, handle_clamp_frac binds every segment and rad has no effect (see handle_clamp_frac).

Type:

float

edgy

Corner-tangent blend weight. Converted internally as p = atan(edgy) / pi + 0.5. At 0.0 (default), p = 0.5 gives a symmetric bisector tangent; larger positive values push p toward 1, making turns asymmetrically sharper (outgoing-edge-dominant).

Type:

float

scale

Isotropic scale multiplier applied to sampled corner positions. Scales all track coordinates; interacts with spacing and half_width through the coordinate range.

Type:

float

handle_clamp_frac

Adaptive Bezier-handle clamp. Each corner’s handle is capped at handle_clamp_frac * (its shorter incident edge) to prevent overshoot past a nearby corner. Set equal to rad (the default) so the clamp only trims genuine overshoot; set below rad to bind every handle regardless of rad (producing near-polygonal tracks); set very large to disable. Tracks that still self-cross after clamping fall back to their corner polygon (~5% at 0.4), which XPBD re-rounds.

Type:

float

hull_displacement

Hull generator only. Maximum per-edge radial midpoint displacement as a fraction of the centroid-to-midpoint distance. At 0.0 the method collapses toward a plain angle-sorted loop; larger values (typical range [0.1, 0.4]) bulge or pinch lobes for more racing-shape variety, at the cost of a higher downstream relaxation burden.

Type:

float

checkpoint_count

Checkpoint generator only. Number of radial checkpoints (C). Must be >= 3. More checkpoints produce wavier tracks (chicane count scales ~C); fewer produce calmer, rounder tracks. CarRacing canonical default: 12.

Type:

int

checkpoint_radius_min_frac

Inner-radius fraction for checkpoint placement. Checkpoint radii are drawn from U(checkpoint_radius_min_frac * R, R) where R = 1. Must be in [0, 1). The CarRacing canonical value 0.33 gives the inlets.

Type:

float

checkpoint_angle_jitter

Angular jitter as a fraction of the per-checkpoint angular slot (slot = 2*pi/C). Kept below 1.0 so the checkpoint sequence stays angle-monotone, ensuring the steered path winds once around. Default 0.55.

Type:

float

checkpoint_turn_rate

Maximum heading change (radians) per steering step. Bounds path curvature; too large allows kinks, too small prevents tracking the inlets. Default 0.42.

Type:

float

checkpoint_steer_gain

Proportional steering gain toward the current target bearing, in (0, 1]. Controls how aggressively the heading chases each checkpoint per step, coupled to one lap by the fixed step length dl. Default 0.65.

Type:

float

checkpoint_lookahead_frac

Advance-to-next-checkpoint threshold as a fraction of outer radius R. The path moves to the next checkpoint once within checkpoint_lookahead_frac * R of the current target, keeping flow from stalling at each checkpoint. Default 0.16.

Type:

float

checkpoint_best_of_k

Best-of-K candidate count. Must be >= 1. Generates K decorrelated candidates per env and keeps the one with the fewest self-intersections (deterministic argmin; ties broken by lowest k). Replaces CarRacing’s unbounded reject-retry with a bounded, graph-capturable pool; K=4 leaves ≲0.4% of tracks with a pre-relax self-intersection at the default config.

Type:

int

checkpoint_clip_fallback

Opt-in single-crossing clip fallback (default False). When True, the first self-crossing of the selected centerline is clipped: split at the intersection point, keep the longer sub-loop arc, resample to num_points. A capture-time Python branch; the captured graph stays fixed either way.

Type:

bool

style_sampling

Opt-in per-env Bezier style randomisation (default False). When False, the scalar rad / scale / handle_clamp_frac are used for all envs unchanged. When True, each env draws its own values from the *_range fields via the per-env Warp RNG, so a single batch spans a family of styles. Resolved at CUDA-graph capture time (a Python branch); per-env values are device data so the captured graph remains fixed.

Type:

bool

rad_range

(lo, hi) range for per-env rad when style_sampling=True. None collapses to the scalar rad for all envs.

Type:

tuple of float or None

scale_range

(lo, hi) range for per-env scale when style_sampling=True. None collapses to the scalar scale for all envs.

Type:

tuple of float or None

handle_clamp_frac_range

(lo, hi) range for per-env handle_clamp_frac when style_sampling=True. None collapses to the scalar handle_clamp_frac for all envs.

Type:

tuple of float or None

polar_num_knots

Polar generator only. Number of periodic cubic-spline control knots. More knots add higher-frequency shape variety. Default 12.

Type:

int

polar_radial_jitter

Polar generator only. Radial jitter magnitude for polar control knots, as a fraction of the base radius. Clamped internally to keep radii positive; larger values produce more eccentric track shapes. Default 0.60.

Type:

float

polar_angular_jitter

Polar generator only. Angular jitter per polar knot, as a fraction of a half angular cell, so the sorted order is preserved without a runtime sort. Larger values add more angular irregularity. Default 0.30.

Type:

float

voronoi_num_sites

Voronoi generator only. Total cell sites in the fixed site field. Must be >= voronoi_control_points. More sites enrich anchor-snap targets at the cost of a larger all-sites scan. Default 256.

Type:

int

voronoi_site_layout

Voronoi generator only. Site distribution layout. One of "ring" (uniform box fill — NOT an annular band; name kept for config compatibility), "void_ring" (default — annular band with center void, r ∈ [0.14·box, 0.52·box], biased for usable closed loops), "clustered" (6 radial Gaussian clusters with ~22% annular fallback per site), or "mixed" (65% annular sites blended with 35% uniform box fill).

Type:

str

voronoi_control_points

Voronoi generator only. Number of angular anchor sites selected from the site field (K). Must be >= 6 for Chaikin/Catmull-Rom densification to produce a smooth loop. More control points add local features and can raise the downstream relaxation burden.

Type:

int

voronoi_radial_variation

Voronoi generator only. Radial modulation of anchor target positions. Must be >= 0. At 0, all targets are placed at a uniform annulus radius; larger values allow more eccentric loops. Default 0.62.

Type:

float

voronoi_angular_jitter

Voronoi generator only. Angular jitter for anchor sector targets, as a fraction of a full sector. Must be >= 0. Larger values randomise the angular spacing of targets. Default 0.08.

Type:

float

repulsive_grow_mult_min

Repulsive generator only. Lower bound of the per-env target-perimeter multiplier draw U(min, max): the grown loop’s target perimeter is grow_mult * 2π * r_init. Higher → denser mazes at some yield cost.

Warning

The repulsive generator is a host-driven, non-graph-capturable optimizer — roughly 1000× slower than bezier (~0.18 s @ E=64, ~5.1 s @ E=8192 on an RTX 4090, vs ~2 ms for bezier). It runs eagerly on CUDA every call (no captured replay). Regenerate on a slow cadence or in staggered per-env slices, not every frame.

Type:

float

repulsive_grow_mult_max

Repulsive generator only. Upper bound of the target-perimeter multiplier draw. Must be >= repulsive_grow_mult_min. Overfill ratio ≈ grow_mult / repulsive_domain_init_ratio.

Type:

float

repulsive_domain_frac

Repulsive generator only. Confinement-disc radius as a fraction of the world-scale reference length (r_dom = repulsive_domain_frac * scale_ref * config.scale). Sets the grown curve’s absolute scale vs half_width. Must be > 0. Tighter → richer folds.

Type:

float

repulsive_domain_init_ratio

Repulsive generator only. Ratio r_dom / r_init of the domain radius to the initial seed-circle radius. Must be > 1. Reference value 4.0.

Type:

float

repulsive_obstacle_count_min

Repulsive generator only. Lower bound of the per-env inner-disc obstacle count k ~ randi[min, max]. Must be >= 1.

Type:

int

repulsive_obstacle_count_max

Repulsive generator only. Upper bound of the inner-disc count. Must be >= repulsive_obstacle_count_min.

Type:

int

repulsive_obstacle_radius_min_frac

Repulsive generator only. Lower bound of the inner-disc radius as a fraction of r_dom. Must be > 0.

Type:

float

repulsive_obstacle_radius_max_frac

Repulsive generator only. Upper bound of the inner-disc radius fraction. Must be >= repulsive_obstacle_radius_min_frac.

Type:

float

repulsive_ratchet_rate

Repulsive generator only. Per-iteration length-growth factor of the hard ratchet. Must be > 0. <= 0.013 holds full yield with folds; >= 0.016 collapses the folds (physical limit).

Type:

float

repulsive_alpha

Repulsive generator only. Tangent-point energy exponent alpha. Must be > 0.

Type:

float

repulsive_beta

Repulsive generator only. Tangent-point energy exponent beta; obstacle inverse power is p = beta - alpha. Must be > 0.

Type:

float

repulsive_tau

Repulsive generator only. Normalized flow step size.

Type:

float

repulsive_w_len

Repulsive generator only. Weight of the small inert length regularizer.

Type:

float

repulsive_stages

Repulsive generator only. Coarse-to-fine resolution schedule N = 64 → 128 → 256. Must be non-empty, strictly increasing, and each a positive multiple of 4. The last entry must equal num_points (the tail input resolution) when generator == "repulsive".

Type:

tuple of int

repulsive_settle_iters

Repulsive generator only. Settle-phase iteration budget above the ratchet.

Type:

int

repulsive_resample_every

Repulsive generator only. Periodic arc-length reparameterization interval.

Type:

int

repulsive_stall_window

Repulsive generator only. Iterations between stall checks / early-exit readbacks.

Type:

int

repulsive_stall_area_tol

Repulsive generator only. Freeze an env once it is past target length AND its enclosed-area relative change over a stall window is below this (reparameterization-invariant shape-convergence tolerance).

Type:

float

repulsive_deactivate_obstacles

Repulsive generator only. When True (default), zero the inner-disc obstacle weights once an env reaches its target length (the wall stays live), closing the disc halos.

Type:

bool

num_harmonics

Fourier / experimental — not used by the runtime path. Number of Fourier harmonics (K). Retained for compatibility with track_gen._experimental.fourier and older sweeps.

Type:

int

decay_p

Fourier / experimental — not used by the runtime path. Fourier amplitude decay exponent: amplitude ~ amp / k ** decay_p.

Type:

int

amplitude

Fourier / experimental — not used by the runtime path. Fourier base amplitude.

Type:

float

num_centerline_samples

Fourier / experimental — not used by the runtime path. Dense sample count for the Fourier generator (M_max).

Type:

int

half_width

Track half-width in the same coordinate units as the centerline. Must be > 0. All spacing, relaxation, and inflation distances couple to this value: spacing defaults to 0.6 * half_width; the XPBD separation target is 2 * half_width * (1 + relax_margin); N_max headroom scales with 1 / half_width at a given track scale.

Type:

float

relax_enable

When True (default), the XPBD relaxation solve runs before inflation. When False, the constant-spacing centerline is inflated directly; useful for ablation studies but typically produces lower-quality tracks.

Type:

bool

relax_solver

Backend selector. Only "xpbd" is used by the runtime path (TrackGenerator). "energy" (Adam) and "tp_sobolev" are oracle-only backends in tests/_oracle/relaxation.py; TrackGenerator rejects any solver other than "xpbd" at construction time.

Type:

str

relax_chunk_size

Energy oracle backend only — not used by the runtime path. Env-chunk size for the dense [E, N, N] interaction term in the energy backend. None disables chunking.

Type:

int or None

relax_use_warp

Oracle-only — not used by the runtime path. When False, oracle tests redirect relaxation to the pure-torch path instead of Warp. Ignored by TrackGenerator and warp_relax.py.

Type:

bool or None

relax_tol

Validity thickness tolerance. The minimum valid track half-width is (1 - relax_tol) * half_width. Default 0.02 (2% tolerance).

Type:

float

relax_band

Bead-index exclusion band for the separation constraint. None (default) auto-computes round(2 * half_width / L0) per track, where L0 is the rest edge length. Set explicitly to override the per-track auto-band.

Type:

int or None

relax_iters

Number of XPBD Jacobi sweeps. Default 50. Each sweep applies separation, spacing, and bending corrections; with the default Chebyshev-accelerated solve (relax_accel="chebyshev"), 50 sweeps are calibrated for ~0.999 end-to-end valid yield at the library defaults (matching what 150 plain Jacobi sweeps used to need).

Type:

int

relax_accel

Iteration-acceleration scheme for the XPBD Jacobi sweeps. "chebyshev" (default) applies Chebyshev semi-iterative acceleration (Macklin et al. 2014): after relax_cheby_start plain warmup sweeps, each sweep blends the Jacobi update with the current and previous iterates using a host-precomputed omega recurrence, converging ~3x faster per sweep. "none" runs plain damped Jacobi (the legacy behaviour).

Type:

str

relax_cheby_rho

Chebyshev spectral-radius estimate of the underlying Jacobi iteration. Must be in [0, 1). Default 0.98. Larger values accelerate the long-wavelength modes harder but risk overshoot on the nonsmooth separation contacts; values >= 0.99 were observed to reduce yield.

Type:

float

relax_cheby_gamma

Chebyshev under-relaxation factor applied to the Jacobi step inside the blend. Must be in (0, 1]. Default 0.9. Values below 1 damp the contact-switching noise that acceleration would otherwise amplify.

Type:

float

relax_cheby_start

Sweep index at which Chebyshev acceleration engages; earlier sweeps run plain Jacobi so the separation contact set settles first. Must be >= 1. Default 8.

Type:

int

relax_smooth_passes

Number of shrink-free Taubin smoothing passes applied after the main sweep loop. Must be >= 0. Default 5. Each pass is two Laplacian half-steps (\(\lambda > 0\) then \(\mu < -\lambda\)), which removes the sub-R_min curvature noise the bending guard’s deadband cannot see (bending only fires below the minimum radius; gentler wiggles are invisible to all three constraints) without shrinking corners through the validity gate the way a plain Laplacian would. 0 disables the smoothing tail entirely.

Type:

int

relax_smooth_spacing_iters

Number of spacing-only polish sweeps applied after the Taubin passes. Must be >= 0. Default 10. Each is the ordinary edge-spacing correction with separation and bending off, restoring bead uniformity that the Taubin passes perturb. 0 disables the polish.

Type:

int

relax_sep_every

Broadphase refresh interval in sweeps. Must be >= 1. At 1, the dense O(count²) separation scan (or cache rebuild) runs every sweep. At K > 1 with relax_sep_cache_slots == 0, the dense scan is skipped between refreshes (fast but may miss transient contacts). With relax_sep_cache_slots > 0, this is the cache-rebuild interval; the exact narrowphase still runs every sweep on cached candidates. Default 20: the broadphase is built at sweep 0 and refreshed only at multiples of this interval, so runs shorter than relax_sep_every sweeps never refresh it mid-solve — the cadence dropped from 40 alongside the relax_iters 150 -> 50 default so the accelerated solve still refreshes mid-solve.

Type:

int

relax_sep_cache_slots

Broadphase candidate cache capacity per bead. 0 disables the cache (uses the dense cadenced scan). When > 0, each bead stores up to this many non-neighbour candidate indices; the exact separation push runs against cached candidates every sweep. Larger values reduce missed contacts at the cost of memory and narrowphase work. Default 16.

Type:

int

relax_sep_cache_skin

Broadphase skin as a fraction of the exact separation target. Must be >= 0. The cache stores candidates within target * (1 + skin); the exact narrowphase test still requires dist < target. Skin 0 is fastest; positive values retain candidates that may enter contact during a long cache interval. Default 0.5.

Type:

float

relax_sep_relax

Scale applied to the separation-constraint correction. Default 1.0 (full correction). Reduce toward 0 to soften separation enforcement.

Type:

float

relax_spc_relax

Scale applied to the edge-spacing (rest-length) correction. Default 1.0. Reduce to allow more spacing deviation.

Type:

float

relax_bend_relax

Scale applied to the bending/radius-guard correction. Default 1.5 (slightly over-corrects to quickly remove sharp corners introduced by separation pushes). Reduce if the solver oscillates.

Type:

float

relax_margin

Fractional expansion of the separation target beyond the road diameter: target = 2 * half_width * (1 + relax_margin). Default 0.15 (15% margin). Leaves room for the downstream thickness validity gate.

Type:

float

energy_steps

Energy oracle backend — not used by the runtime path. Adam optimiser steps for the "energy" oracle backend in tests/_oracle/relaxation.py.

Type:

int

energy_lr

Energy oracle backend — not used by the runtime path. Adam learning rate.

Type:

float

energy_w_sep

Energy oracle backend — not used by the runtime path. Separation loss weight.

Type:

float

energy_w_len

Energy oracle backend — not used by the runtime path. Edge-length loss weight.

Type:

float

energy_w_bend

Energy oracle backend — not used by the runtime path. Bending loss weight.

Type:

float

energy_w_anchor

Energy oracle backend — not used by the runtime path. Anchor loss weight.

Type:

float

tp_iters

TP-Sobolev oracle backend — not used by the runtime path. Flow steps for the "tp_sobolev" oracle backend in tests/_oracle/relaxation.py.

Type:

int

tp_tau

TP-Sobolev oracle backend — not used by the runtime path. Step size for the TP-Sobolev flow.

Type:

float

tp_alpha

TP-Sobolev oracle backend — not used by the runtime path. Sobolev kernel exponent alpha; shared with the smooth_finish finisher.

Type:

float

tp_beta

TP-Sobolev oracle backend — not used by the runtime path. Sobolev kernel exponent beta; shared with the smooth_finish finisher.

Type:

float

smooth_finish

Oracle-only — not used by the runtime path. When True, a tangent-point/Sobolev smoothing finisher runs after the primary relaxation solve. TrackGenerator rejects smooth_finish=True at construction time.

Type:

bool

smooth_finish_iters

Oracle-only — not used by the runtime path. Flow steps for the smoothing finisher.

Type:

int

smooth_finish_tau

Oracle-only — not used by the runtime path. Step size for the smoothing finisher.

Type:

float

num_points

Intermediate dense-resample resolution (N) used before the constant-spacing step. Default 256. The constant-spacing resampler then derives count[e] = floor(perimeter / spacing) + 1 real points per env.

Type:

int

output_mode

Output resampling mode. The only supported value is "constant_spacing" (enforced by __post_init__). Constant arc spacing produces smoother XPBD convergence and higher valid-track yield than a fixed point count.

Type:

str

spacing

Constant arc-length step (m) between adjacent output points. None (default) auto-couples to 0.6 * half_width — the relaxation-friendly value; a fixed default would be wrong as half_width varies. Must resolve to > 0 after auto-coupling.

Type:

float or None

N_max

Output buffer width: maximum constant-spacing points per track. Tracks whose true count[e] exceeds N_max are truncated and fail validity. Default 384: ample headroom at half_width = 0.1 (spacing ≈ 0.06, ~141 max points), full coverage to half_width ≈ 0.05 (~281 max), and ~98% of the half_width = 0.03 regime (~468 max). Raise N_max or coarsen spacing for finer/larger-scale regimes.

Type:

int

max_regen_iters

Vestigial on the Warp runtime path. Maximum regeneration iterations for the torch oracle’s accept-first-valid loop in tests/_oracle/generators.py. Ignored by _run_pipeline, which is single-pass with no host-side retry loop.

Type:

int

turning_tol

Absolute angular tolerance in radians for the turning-number validity gate. Tracks whose signed curvature integral deviates from the expected full turn by more than this tolerance are marked invalid. Default 0.1.

Type:

float

w_floor

Width floor for validity. Every real track point must have computed half-width > w_floor. Default 1e-3. Guards against near-degenerate geometry that passes the global thickness check.

Type:

float

validity_border_check

When True, an explicit border self-intersection check is added to the validity gate. Default False. Redundant with the thickness/separation gate (a self-crossing fat band drives separation_min → 0 → thickness < half_width → invalid), so the default saves two O(N²) passes with no change to the valid mask.

Type:

bool

z_profile

Per-point altitude (Z) profile family, applied along the resampled constant-spacing centerline arc length. One of "flat" (default, every real point at z_base), "uniform" (i.i.d. uniform in [z_min, z_max]), "random_walk" (Brownian-bridge walk clamped to [z_min, z_max] with a per-step grade cap of z_max_step), or "noise" (periodic harmonic noise around z_base). Applied by warp_zprofile.apply_z_profile on the resampler’s (cum, perim) plan-view arc tables.

Type:

str

z_base

Baseline altitude for the "flat", "random_walk", and "noise" profiles. Default 0.0.

Type:

float

z_min

Lower altitude clamp for "uniform", "random_walk", and "noise". Must be <= z_max. Default 0.0.

Type:

float

z_max

Upper altitude clamp for "uniform", "random_walk", and "noise". Must be >= z_min. Default 0.0.

Type:

float

z_max_step

Random-walk profile only. Maximum |dz| per unit plan-view arc length (a grade cap), applied per random-walk step before the closure bridge. Must be >= 0. Default 0.0.

Type:

float

z_noise_amplitude

Noise profile only. Amplitude of the harmonic altitude oscillation around z_base. Must be >= 0. Default 0.0.

Type:

float

z_noise_harmonics

Noise profile only. Number of summed harmonics in the periodic noise field. Must be >= 1. Default 3.

Type:

int

z_control_points

Number of arc-length-spaced altitude control knots. Altitude is decided at these knots and interpolated between them with a periodic monotone cubic, so smoothness is independent of the resampled point count. Must be >= 3. Applies to z_profile="uniform" and "random_walk"; inert for "flat" (constant) and "noise" (analytically smooth — use z_noise_harmonics for its frequency). Default 10.

Type:

int

z_valid_grade

Maximum allowed |dz|/ds grade for post-hoc course validity checking, where ds is measured along the PLAN-VIEW (XY) arc length, not the 3D lifted arc length. 0 disables the check. Must be >= 0. Default 0.0.

Type:

float

__init__(generator='bezier', device='cpu', num_envs=1, min_num_points=9, max_num_points=13, num_points_per_segment=30, min_point_distance=0.05, min_angle=0.2181661564992912, rad=0.4, edgy=0.0, scale=1.0, handle_clamp_frac=0.4, hull_displacement=0.15, checkpoint_count=12, checkpoint_radius_min_frac=0.33, checkpoint_angle_jitter=0.55, checkpoint_turn_rate=0.42, checkpoint_steer_gain=0.65, checkpoint_lookahead_frac=0.16, checkpoint_best_of_k=4, checkpoint_clip_fallback=False, style_sampling=False, rad_range=None, scale_range=None, handle_clamp_frac_range=None, polar_num_knots=12, polar_radial_jitter=0.6, polar_angular_jitter=0.3, voronoi_num_sites=256, voronoi_site_layout='void_ring', voronoi_control_points=18, voronoi_radial_variation=0.62, voronoi_angular_jitter=0.08, repulsive_grow_mult_min=4.5, repulsive_grow_mult_max=5.5, repulsive_domain_frac=0.35, repulsive_domain_init_ratio=4.0, repulsive_obstacle_count_min=8, repulsive_obstacle_count_max=12, repulsive_obstacle_radius_min_frac=0.02, repulsive_obstacle_radius_max_frac=0.045, repulsive_ratchet_rate=0.012, repulsive_alpha=3.0, repulsive_beta=6.0, repulsive_tau=0.4, repulsive_w_len=30.0, repulsive_stages=(64, 128, 256), repulsive_settle_iters=40, repulsive_resample_every=25, repulsive_stall_window=16, repulsive_stall_area_tol=0.05, repulsive_deactivate_obstacles=True, num_harmonics=5, decay_p=2, amplitude=1.0, num_centerline_samples=256, half_width=0.1, relax_enable=True, relax_solver='xpbd', relax_chunk_size=None, relax_use_warp=None, relax_tol=0.02, relax_band=None, relax_iters=50, relax_accel='chebyshev', relax_cheby_rho=0.98, relax_cheby_gamma=0.9, relax_cheby_start=8, relax_smooth_passes=5, relax_smooth_spacing_iters=10, relax_sep_every=20, relax_sep_cache_slots=16, relax_sep_cache_skin=0.5, relax_sep_relax=1.0, relax_spc_relax=1.0, relax_bend_relax=1.5, relax_margin=0.15, energy_steps=800, energy_lr=0.003, energy_w_sep=80.0, energy_w_len=8.0, energy_w_bend=1.0, energy_w_anchor=0.01, tp_iters=100, tp_tau=0.7, tp_alpha=2.0, tp_beta=4.5, smooth_finish=False, smooth_finish_iters=8, smooth_finish_tau=0.2, num_points=256, output_mode='constant_spacing', spacing=None, N_max=384, max_regen_iters=10, turning_tol=0.1, w_floor=0.001, validity_border_check=False, z_profile='flat', z_base=0.0, z_min=0.0, z_max=0.0, z_max_step=0.0, z_noise_amplitude=0.0, z_noise_harmonics=3, z_control_points=10, z_valid_grade=0.0)

Parameters:

• generator (str)

• device (str)

• num_envs (int)

• min_num_points (int)

• max_num_points (int)

• num_points_per_segment (int)

• min_point_distance (float)

• min_angle (float)

• rad (float)

• edgy (float)

• scale (float)

• handle_clamp_frac (float)

• hull_displacement (float)

• checkpoint_count (int)

• checkpoint_radius_min_frac (float)

• checkpoint_angle_jitter (float)

• checkpoint_turn_rate (float)

• checkpoint_steer_gain (float)

• checkpoint_lookahead_frac (float)

• checkpoint_best_of_k (int)

• checkpoint_clip_fallback (bool)

• style_sampling (bool)

• rad_range (tuple[float, float] | None)

• scale_range (tuple[float, float] | None)

• handle_clamp_frac_range (tuple[float, float] | None)

• polar_num_knots (int)

• polar_radial_jitter (float)

• polar_angular_jitter (float)

• voronoi_num_sites (int)

• voronoi_site_layout (str)

• voronoi_control_points (int)

• voronoi_radial_variation (float)

• voronoi_angular_jitter (float)

• repulsive_grow_mult_min (float)

• repulsive_grow_mult_max (float)

• repulsive_domain_frac (float)

• repulsive_domain_init_ratio (float)

• repulsive_obstacle_count_min (int)

• repulsive_obstacle_count_max (int)

• repulsive_obstacle_radius_min_frac (float)

• repulsive_obstacle_radius_max_frac (float)

• repulsive_ratchet_rate (float)

• repulsive_alpha (float)

• repulsive_beta (float)

• repulsive_tau (float)

• repulsive_w_len (float)

• repulsive_stages (tuple[int, ...])

• repulsive_settle_iters (int)

• repulsive_resample_every (int)

• repulsive_stall_window (int)

• repulsive_stall_area_tol (float)

• repulsive_deactivate_obstacles (bool)

• num_harmonics (int)

• decay_p (int)

• amplitude (float)

• num_centerline_samples (int)

• half_width (float)

• relax_enable (bool)

• relax_solver (str)

• relax_chunk_size (int | None)

• relax_use_warp (bool | None)

• relax_tol (float)

• relax_band (int | None)

• relax_iters (int)

• relax_accel (str)

• relax_cheby_rho (float)

• relax_cheby_gamma (float)

• relax_cheby_start (int)

• relax_smooth_passes (int)

• relax_smooth_spacing_iters (int)

• relax_sep_every (int)

• relax_sep_cache_slots (int)

• relax_sep_cache_skin (float)

• relax_sep_relax (float)

• relax_spc_relax (float)

• relax_bend_relax (float)

• relax_margin (float)

• energy_steps (int)

• energy_lr (float)

• energy_w_sep (float)

• energy_w_len (float)

• energy_w_bend (float)

• energy_w_anchor (float)

• tp_iters (int)

• tp_tau (float)

• tp_alpha (float)

• tp_beta (float)

• smooth_finish (bool)

• smooth_finish_iters (int)

• smooth_finish_tau (float)

• num_points (int)

• output_mode (str)

• spacing (float | None)

• N_max (int)

• max_regen_iters (int)

• turning_tol (float)

• w_floor (float)

• validity_border_check (bool)

• z_profile (str)

• z_base (float)

• z_min (float)

• z_max (float)

• z_max_step (float)

• z_noise_amplitude (float)

• z_noise_harmonics (int)

• z_control_points (int)

• z_valid_grade (float)

Return type:

None

classmethod __new__(*args, **kwargs)

class GateGenConfig

Bases: object

Configuration for fixed-batch native gate sequence generation.

Used by GateGenerator to produce batched GateSequence results. The gate path only samples corner anchors and emits them directly as gates; it never runs Bezier or hull curve assembly. As a result, num_points_per_segment, rad, edgy, handle_clamp_frac, and hull_displacement are inert for gate output (kept for config parity with TrackGenConfig). The effective knobs for anchor placement are min_num_points, max_num_points, min_point_distance, and scale.

generator

Registered generator name. One of "bezier" (default), "hull", "polar", "voronoi", or "checkpoint". Selects the anchor sampling family; only the anchor positions are used as gates.

Type:

str

device

Warp device string: "cpu" or "cuda".

Type:

str

num_envs

Number of environments in the batch. Must be >= 1.

Type:

int

min_gates

Minimum real gate count per env. Must be >= 2.

Type:

int

max_gates

Maximum real gate count per env. Must be >= min_gates.

Type:

int

gate_radius

Gate detection radius used for gate-constraint solve proximity checks. Must be >= 0.

Type:

float

gate_solve_iters

Number of gate-constraint solve iterations. Must be >= 0.

Type:

int

gate_width

Physical gate half-width (visual/collision extent). Must be >= 0. Does not affect anchor sampling geometry.

Type:

float

gate_ordering

Gate output ordering. One of "ccw" (counter-clockwise sort by angle around the batch centroid; default), "raw" (generator order as sampled), or "random_pairs" (random gate pairs for training objectives).

Type:

str

min_num_points

Minimum corner-anchor count per env for the bezier/hull point sampler. Must be >= 2. Affects the number of sampled anchor positions.

Type:

int

max_num_points

Maximum corner-anchor count per env. Must be >= min_num_points.

Type:

int

num_points_per_segment

Inert for gate output. Dense samples per segment for Bezier/hull curve assembly; the gate path does not assemble curves. Kept for config parity with TrackGenConfig.

Type:

int

min_point_distance

Minimum grid-cell spacing for anchor-position sampling. Must be > 0. Governs the cell grid as num_cells = int(1 / (min_point_distance * 2)).

Type:

float

rad

Inert for gate output. Bezier handle-length fraction. Kept for config parity with TrackGenConfig.

Type:

float

edgy

Inert for gate output. Corner-tangent blend weight. Kept for config parity with TrackGenConfig.

Type:

float

scale

Isotropic scale multiplier for anchor positions. Does affect the sampled anchor coordinates and hence gate positions.

Type:

float

handle_clamp_frac

Inert for gate output. Bezier handle clamp. Kept for config parity with TrackGenConfig.

Type:

float

hull_displacement

Inert for gate output. Hull midpoint displacement fraction. Kept for config parity with TrackGenConfig.

Type:

float

polar_num_knots

Polar generator only. Number of periodic cubic-spline control knots. Default 12.

Type:

int

polar_radial_jitter

Polar generator only. Radial jitter magnitude for polar control knots, as a fraction of the base radius. Default 0.60.

Type:

float

polar_angular_jitter

Polar generator only. Angular jitter per polar knot, as a fraction of a half angular cell. Default 0.30.

Type:

float

voronoi_num_sites

Voronoi generator only. Total cell sites in the fixed site field. Must be >= voronoi_control_points. Default 256.

Type:

int

voronoi_site_layout

Voronoi generator only. Site distribution layout. One of "ring", "void_ring" (default), "clustered", or "mixed".

Type:

str

voronoi_control_points

Voronoi generator only. Anchor sites selected from the site field. Must be >= 3 (the gate-native Voronoi path emits anchors directly as gates, so it needs only 3 for a non-degenerate ring — unlike TrackGenConfig’s >= 6 floor for Chaikin/Catmull-Rom densification).

Type:

int

voronoi_radial_variation

Voronoi generator only. Radial modulation of anchor target positions. Must be >= 0. Default 0.62.

Type:

float

voronoi_angular_jitter

Voronoi generator only. Angular jitter for anchor sector targets. Must be >= 0. Default 0.08.

Type:

float

checkpoint_count

Checkpoint generator only. Number of radial checkpoints. Must be >= 3. Default 12.

Type:

int

checkpoint_radius_min_frac

Checkpoint generator only. Inner-radius fraction for checkpoint placement. Must be in [0, 1). Default 0.33.

Type:

float

checkpoint_angle_jitter

Checkpoint generator only. Angular jitter as a fraction of the per-checkpoint angular slot. Default 0.55.

Type:

float

z_profile

Per-gate altitude (Z) profile family. One of "flat" (default, every real gate at z_base), "uniform" (i.i.d. uniform in [z_min, z_max]), "random_walk" (Brownian-bridge walk clamped to [z_min, z_max] with a per-step grade cap of z_max_step), or "noise" (periodic harmonic noise around z_base). Applied by warp_zprofile.apply_z_profile after XY ordering/relaxation and before the 3D lift, wired into the generation pipeline by warp_gate._run_gate_pipeline.

Type:

str

z_base

Baseline altitude for the "flat", "random_walk", and "noise" profiles. Default 0.0.

Type:

float

z_min

Lower altitude clamp for "uniform", "random_walk", and "noise". Must be <= z_max. Default 0.0.

Type:

float

z_max

Upper altitude clamp for "uniform", "random_walk", and "noise". Must be >= z_min. Default 0.0.

Type:

float

z_max_step

Random-walk profile only. Maximum |dz| per unit plan-view arc length (a grade cap), applied per random-walk step before the closure bridge. Must be >= 0. Default 0.0.

Type:

float

z_noise_amplitude

Noise profile only. Amplitude of the harmonic altitude oscillation around z_base. Must be >= 0. Default 0.0.

Type:

float

z_noise_harmonics

Noise profile only. Number of summed harmonics in the periodic noise field. Must be >= 1. Default 3.

Type:

int

z_valid_grade

Maximum allowed |dz|/ds grade for post-hoc course validity checking. 0 disables the check. Must be >= 0. Default 0.0. (Consumed starting in Task 4; unused by warp_zprofile itself.)

Type:

float

gate_align

Gate-frame alignment mode. "yaw_only" (default) keeps gate posts horizontal (the frame forward axis is the plan-view tangent projected onto the XY plane, so left/right posts share the center’s altitude); "full_tangent" aligns the frame forward axis with the full 3D tangent, tilting posts to follow the course slope.

Type:

str

__init__(generator='bezier', device='cpu', num_envs=1, min_gates=4, max_gates=32, gate_radius=0.025, gate_solve_iters=8, gate_width=0.0, gate_ordering='ccw', min_num_points=9, max_num_points=13, num_points_per_segment=30, min_point_distance=0.05, rad=0.4, edgy=0.0, scale=1.0, handle_clamp_frac=0.4, hull_displacement=0.15, polar_num_knots=12, polar_radial_jitter=0.6, polar_angular_jitter=0.3, voronoi_num_sites=256, voronoi_site_layout='void_ring', voronoi_control_points=18, voronoi_radial_variation=0.62, voronoi_angular_jitter=0.08, checkpoint_count=12, checkpoint_radius_min_frac=0.33, checkpoint_angle_jitter=0.55, z_profile='flat', z_base=0.0, z_min=0.0, z_max=0.0, z_max_step=0.0, z_noise_amplitude=0.0, z_noise_harmonics=3, z_valid_grade=0.0, gate_align='yaw_only')

Parameters:

• generator (str)

• device (str)

• num_envs (int)

• min_gates (int)

• max_gates (int)

• gate_radius (float)

• gate_solve_iters (int)

• gate_width (float)

• gate_ordering (str)

• min_num_points (int)

• max_num_points (int)

• num_points_per_segment (int)

• min_point_distance (float)

• rad (float)

• edgy (float)

• scale (float)

• handle_clamp_frac (float)

• hull_displacement (float)

• polar_num_knots (int)

• polar_radial_jitter (float)

• polar_angular_jitter (float)

• voronoi_num_sites (int)

• voronoi_site_layout (str)

• voronoi_control_points (int)

• voronoi_radial_variation (float)

• voronoi_angular_jitter (float)

• checkpoint_count (int)

• checkpoint_radius_min_frac (float)

• checkpoint_angle_jitter (float)

• z_profile (str)

• z_base (float)

• z_min (float)

• z_max (float)

• z_max_step (float)

• z_noise_amplitude (float)

• z_noise_harmonics (int)

• z_valid_grade (float)

• gate_align (str)

Return type:

None

classmethod __new__(*args, **kwargs)