Problem¶

Contract¶

Problem is the canonical aggregate of magnets, interactions, studies, transport, mechanics, selections, magnetization constraints, discretization, and requested runtime intent. Stage-first scripts normally produce this object through the loader; direct construction remains the exact class API and serialization contract.

Governing equations¶

Problem introduces no independent equation. It preserves a typed multiphysics graph whose individual modules own their equations, signs, units, boundary conditions, and qualification.

Symbols and SI units¶

Each nested module retains its declared SI units. Names, IDs, policies, selections, activation rules, and runtime choices are dimensionless semantic/provenance data.

Assumptions and validity¶

At least one magnet and one active interaction/material anisotropy are required. Exactly one canonical study or a compatible legacy dynamics/output route must be supplied. All named graph, selection, constraint, torque, transport, geometry, material, stage, and interface references are validated before execution.

Frozen-spin constraints¶

Problem.magnetization_constraints carries FrozenSpins intent as stage-first, typed contract data:

• selector: geometry/object/region selection used for the frozen region.

• membership: static freeze or snapshot-at-activation behavior.

• reference: source orientation mode (capture_current_at_activation, initial_state, explicit_field_asset).

• stage_ids / activation: stage-scoped applicability controls.

Constraint definitions are validated before planning. Unsupported runtime/lane combinations must fail closed rather than silently rewrite intent.

Standard entry: Frozen-spins (source-first, argument-complete)¶

from fullmag.model.constraints import FrozenSpins
from fullmag.model.selection import in_object_selection

constraint = FrozenSpins(
    id="film_frozen_capture",
    selector=in_object_selection("film"),
    reference="capture_current_at_activation",
    membership="snapshot_at_activation",
    stage_ids=("run",),
    empty_selection="error",
    inactive_selection="warn_and_intersect",
)

Python API¶

# %% Build a Problem through the public study API
import fullmag as fm

study = fm.study("problem_api_example")
study.engine("fdm")
study.device("cpu", precision="double")
study.objects.mesh.defaults(cell_size=(2e-9, 2e-9, 2e-9))
film = study.geometry(fm.Box(40e-9, 20e-9, 4e-9), name="film")
film.Ms = 8.0e5
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.exchange()
study.stages.add_run(stage_id="run", until=1e-12)

ProblemIR¶

Requested intent remains distinct from planner resolution and execution evidence. The serializer preserves selections and frozen-spin constraints as typed graph data; it must not flatten them to backend masks before planning.

Round-trip and failure semantics¶

Requested intent preserves module identities, signs, units, formula/operator versions, selection graphs, constraint policies, stage activation, and requested runtime. Resolved execution records the chosen planner realization, concrete meshes/masks, solver, device, precision, and capability decisions without replacing requested intent. Validation errors reject unknown references, cycles, duplicates, malformed data, and stale source identities. Unsupported combinations fail closed and are not silently omitted, converted, or executed on a fallback lane.

Discrete realization¶

Planners resolve the same ProblemIR into FDM/FEM and CPU/GPU execution plans. Representation in Problem is not evidence that every nested module executes on every lane.

Implementation mapping¶

packages/fullmag-py/src/fullmag/model/problem.py, class Problem, owns aggregate validation, legacy migration, canonical lowering, geometry assets, selections, constraints, and multiphysics reference integrity.

Validation¶

The documentation ownership test compares this inventory and source map with the live constructor signature. Runtime qualification remains module- and lane-specific.

Limitations¶

Some fields are compatibility or internal build inputs. The stage-first API should remain the primary user surface while direct construction stays fully documented for reproducibility.

Scientific bibliography¶

No independent physical equation is introduced.

Control Room crosswalk¶

Status: The Control Room authors a study and lowers it to ProblemIR; direct Problem/IR editing is not exposed.

frontend support is not implemented for standalone Problem/ProblemIR authoring. See Control Room capability register for the support matrix and not implemented policy. Frontend source owner: apps/control-room/src/modules/inspector/panels/StudyInspectorPanel.tsx (StudyInspectorPanel).

Source-code index¶