Skip to content

Refactor builder.py into cohesive private modules #4192

Description

@eric-heiden

Part of #4191. No public API or functionality changes; the shared compatibility requirements in the tracker apply.

newton/_src/sim/builder.py combines construction, custom attributes, composition, graph transformations, validation, and finalization in one large class. This issue owns the refactoring of that file as a whole. The sections below are implementation steps, not separate issues.

Scope

  • Keep ModelBuilder, its public methods/signatures/docstrings, nested public configuration types, supported subclass dispatch, and observable state compatible.
  • Extract substantial rigid/joint, shape/mesh, deformable, custom-attribute/actuator, collision-filter, and validation implementations into cohesive private modules. Keep short convenience methods and authoritative state easy to find.
  • Extract replication, world/builder composition, merge validation/caches, and custom-attribute/actuator merging. Preserve compact collision filters, shared geometry, source/destination aliasing, group ranges, reference metadata, and cache lifetime.
  • Split fixed-joint collapse into graph discovery, reconstruction, domain fixups, reference remapping, and results. Preserve entity order, loops/disconnected components, world/articulation membership, sparse custom values, cable ranges, and mimic/equality/tendon references.
  • Extract finalization into named phases for validation/world starts, model creation, particles/geometry, deformable topology, bodies/joints, counts, actuators, and custom attributes. Isolate mesh/SDF/heightfield/AABB/edge-resource preparation.
  • Keep temporary phase data local to a call. Preserve allocation/execution order, device scope, geometry deduplication, existing builder mutations, and resource lifetime.
  • Retain lazy importer entry points; avoid new import cycles, dynamic method installation, and stateful mixin hierarchies.

Validation

  • Compare builder/model counts, labels, start/sentinel arrays, dtypes/layouts/values, custom namespaces, requested attributes, and returned remapping dictionaries before/after extraction.
  • Exercise empty and mixed models, repeated finalize, non-empty composition destinations, zero/one/many replicas, custom schemas, and supported subclasses.
  • Cover fixed-joint collapse, procedural rigid/deformable construction, collision filtering, and validation switches; preserve warnings/errors and their caller attribution.
  • Run relevant builder/model, replication, custom-attribute, geometry/deformable, and importer tests on supported CPU/CUDA/requires_grad paths.
  • Check representative setup time and allocation behavior, particularly replication, shared geometry, and deferred SDF generation.

Land coherent extractions in a sequence of reviewable PRs under this issue; no algorithm changes or hard LOC quota. Consolidates the scopes previously tracked in #4193 and #4194.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions