Skip to content

Add MACE-POLAR input/output support across torch_sim APIs #463

@janosh

Description

@janosh

torch_sim already supports many aspects of MACE-POLAR (charge/spin plumbing exists), but we do not yet support all POLAR inputs and predicted properties in existing torch_sim APIs. This issue proposes a focused integration plan.

References:

Scope

1) Add external field to state + IO

  • Extend SimState with per-system external_field (shape [n_systems, 3])
  • Include it in system-level attributes so split/slice/concat preserve it
  • Validate shape in SimState.__post_init__
  • Round-trip through ASE conversion:
    • atoms_to_state: read atoms.info["external_field"] (default zero vector)
    • state_to_atoms: write atoms.info["external_field"]

2) Pass POLAR inputs through MaceModel

  • In torch_sim.models.mace.MaceModel.forward, pass:
    • total_charge
    • total_spin
    • external_field (included by default)

3) Standardize + preserve model outputs

  • Keep canonical outputs stable:
    • energy, forces, stress
  • Also propagate additional tensor outputs from MACE/POLAR in MaceModel results
    • e.g. dipole, density_coefficients, spin_charge_density, charges
  • Goal: avoid hardcoding only a fixed small set of properties and support future POLAR heads without wrapper churn

4) Expose extra outputs in high-level APIs

  • Ensure ts.static(...) returns extra model outputs in the per-system property dicts (in addition to existing core properties)
  • Preserve correct per-system/per-atom splitting under batching/autobatching
  • Keep trajectory reporting compatibility for these extra arrays

5) POLAR model discovery / convenience

  • Add POLAR foundation aliases/checkpoint entries to MaceUrls (or equivalent in mace.py)
  • Keep POLAR support in MaceModel rather than creating a separate wrapper class

6) Optional dependency docs/packaging

  • Document and wire optional dependency required by POLAR runtime (graph_electrostatics / graph_longrange) in project extras/docs

7) Tests

  • Add/extend tests for:
    • external_field IO round-trip
    • MACE-POLAR forward pass with charge/spin/field
    • presence + shape checks for electrostatic outputs
    • ts.static exposure of extra outputs
    • ordering correctness with autobatching

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions