Problem¶
Last changes: Documentation changelog
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)¶
Introduction¶
Problem.magnetization_constraints stores FrozenSpins instances as part of the problem’s
contractual intent. The contract stays typed through to the planner layer and is never collapsed into
backend masks prematurely.
Direct source-level evidence¶
class FrozenSpins(packages/fullmag-py/src/fullmag/model/constraints.py) validates inputs in__init__and normalizesreference/activation.ObjectRegion.freeze_spins(...)(packages/fullmag-py/src/fullmag/model/structure.py) constructsFrozenSpinsfor a region (in_region_selection).Ferromagnet.freeze_spins(...)(packages/fullmag-py/src/fullmag/model/structure.py) constructsFrozenSpinsfor an object (in_object_selection), requiringobject_id.Problem(packages/fullmag-py/src/fullmag/model/problem.py) serializes constraints into IR.
Functions and arguments (from signatures)¶
Function |
Arguments |
|---|---|
|
Full source contract with policy validation and defaults. |
|
Region helper: default |
|
Object helper: selector is |
|
Carries constraints into the problem-level field and into IR ( |
Code references¶
packages/fullmag-py/src/fullmag/model/constraints.py:137packages/fullmag-py/src/fullmag/model/constraints.py:148packages/fullmag-py/src/fullmag/model/structure.py:516packages/fullmag-py/src/fullmag/model/structure.py:769packages/fullmag-py/src/fullmag/model/problem.py
Bibliography¶
Abert, C. “Micromagnetics and spintronics: models and numerical methods,” European Physical Journal B 92, 120 (2019), doi:10.1140/epjb/e2019-90599-6.
Python API¶
Python |
Type |
Default |
SI unit |
Meaning / validation |
ProblemIR |
|---|---|---|---|---|---|
|
|
required |
\(1\) |
non-empty problem identity |
|
|
|
required |
mixed |
non-empty magnetic objects with unique identities |
|
|
|
required |
mixed |
interaction list; duplicate legality checked |
|
|
study or |
|
mixed |
canonical study; conflicts with incompatible legacy route |
|
|
|
|
mixed |
legacy dynamics input |
|
|
sequence or |
|
mixed |
legacy outputs requiring legacy dynamics |
|
|
|
|
mixed |
FDM/FEM/hybrid authoring hints |
|
|
|
|
\(1\) |
optional human description |
|
|
|
factory default |
\(1\) |
requested backend/device/precision/mode |
|
|
mapping |
|
\(1\) |
user/runtime provenance |
|
|
sequence |
|
mixed |
nonmagnetic/helper geometries |
|
|
mapping |
|
\(1\) |
role mapping; unknown geometry rejected |
|
|
sequence |
|
mixed |
current and Oersted source modules |
|
|
sequence |
|
mixed |
regional/time-dependent field drives |
|
|
sequence |
|
mixed |
explicit coupling graph |
|
|
sequence |
|
mixed |
planar monitor definitions |
|
|
analysis or |
|
mixed |
optional excitation analysis |
|
|
mapping |
|
\(1\) |
internal deterministic asset cache |
generated |
|
legacy torque or |
|
mixed |
legacy single-torque input; exclusive with canonical list |
normalized torque modules |
|
sequence |
|
mixed |
canonical torque modules |
|
|
mapping |
|
\(1\) |
stage-local activation; unknown IDs rejected |
stage torque activation |
|
sequence |
|
mixed |
canonical spin drift-diffusion modules |
|
|
|
|
K |
non-negative compatibility temperature; thermal-term consistency checked |
|
|
sequence |
|
mixed |
elastic constitutive records |
|
|
sequence |
|
mixed |
elastic body assignments |
|
|
sequence |
|
mixed |
magnetostriction laws |
|
|
sequence |
|
mixed |
mechanical boundary conditions |
|
|
sequence |
|
mixed |
mechanical loads |
|
|
|
|
\(1\) |
unique definitions; reference existence, cycles, and complexity validated |
canonical selection definitions |
|
|
|
\(1\) |
typed constraints; selection/object/region/stage references validated |
canonical magnetization constraints |
|
|
|
mixed |
optional versioned SI-normalized authoring parameter library; resolved at construction (unknown references, cycles, dimension conflicts rejected), lowered as authoring metadata only |
|
|
|
|
\(1\) |
requested periodic axes and demag policy |
|
Antenna collections and auxiliary-object identity¶
Containers and identifiers are dimensionless; physical parameters of nested objects retain their own SI units (\(\mathrm{m}\), \(\mathrm{A}\), \(\mathrm{T}\), \(\mathrm{Hz}\), \(\mathrm{s}\)). The table below does not alter their normalization and does not imply solver execution on all lanes.
Python |
Type |
Default |
SI |
Construction validation |
Meaning |
Support |
ProblemIR |
|---|---|---|---|---|---|---|---|
|
|
|
\(1\) |
non-empty names and IDs; keys belong to auxiliary_geometry_roles; unique object_ids across magnets |
immutable auxiliary-entity identity, independent of display name |
shared FDM/FEM CPU/GPU authoring; execution follows explicit capabilities |
|
|
|
|
\(1\) |
AntennaPortMode entries; unique id within collection |
port current-basis declarations without automatic solve |
shared FDM/FEM CPU/GPU authoring; execution follows explicit capabilities |
|
|
|
|
\(1\) |
AntennaFieldSolveStage entries; unique id within collection |
field-solve declarations separated from explicit stage action |
shared FDM/FEM CPU/GPU authoring; execution follows explicit capabilities |
|
|
|
|
\(1\) |
AntennaTargetProjection entries; unique id within collection |
requested basis projections onto a selected target |
shared FDM/FEM CPU/GPU authoring; execution follows explicit capabilities |
|
|
|
|
\(1\) |
SolvedAntennaDrive entries; unique id within collection |
time-domain consumption of a previously solved basis |
shared FDM/FEM CPU/GPU authoring; execution follows explicit capabilities |
|
|
|
|
\(1\) |
AntennaSpectrumRequest entries; unique id within collection |
source-spectrum requests rather than magnetization response |
shared FDM/FEM CPU/GPU authoring; execution follows explicit capabilities |
|
Problem.__post_init__ rejects wrong element types and duplicate id values. This is not a full
preflight of cross-references between port, solve, projection, and drive declarations: the
IR/planner/runtime boundary must verify that before execution. A valid collection type alone must
never be treated as a solved or available basis.
auxiliary_geometry_object_ids maps a display name to an immutable object_id; keys must appear
in auxiliary_geometry_roles. When omitted, the serializer preserves the object_id = name
compatibility fallback. In each physics_objects[] entry, name stays a separate field,
geometry_id references the geometry, and type comes from the explicit role. Antenna type or
name never triggers current transport, field solve, projection, or LLG dynamics. An ID dictionary
alone does not create a physics_objects record: a record is emitted only for a declared role.
The five collections serialize via value.to_ir() to identically named IR fields. Registering a
field-solve declaration is not a stage action: a dedicated stage-first workflow must invoke it
explicitly. A source spectrum is not evidence of an excited magnetization wavevector response; that
requires a separate magnetization analysis.
ProblemIR¶
The excerpt below comes from lowering the example study through the repository loader without
running a solver. Because no antenna collection is declared, each collection stays empty and no
automatic field solve or RF drive appears. The physics_objects field is omitted when no auxiliary
roles are declared. This is an excerpt rather than a complete problem snapshot.
{
"antenna_port_modes": [],
"antenna_field_solve_stages": [],
"antenna_target_projections": [],
"solved_antenna_drives": [],
"antenna_spectrum_requests": []
}
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: Control Room authors a study, objects, couplings, and FrozenSpins constraints and lowers them to ProblemIR; direct standalone Problem/ProblemIR editing is not exposed.
Python/API surface |
Control Room path |
Status |
Transaction |
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Standalone |
|
|
Python-only until implemented |
not implemented: frontend support for standalone Problem/ProblemIR authoring or aggregate parameters without matching inspector panels.
See Control Room capability register and Physics, Couplings & Frozen Spins Inspectors.
Frontend source owners: apps/control-room/src/modules/inspector/panels/StudyInspectorPanel.tsx (StudyInspectorPanel), FrozenSpinsInspectorPanel, and CouplingInspectorPanel.
Source-code index¶
Claim |
Path |
Stable symbol |
Responsibility |
Evidence |
|---|---|---|---|---|
aggregate API and IR |
graph validation and lowering |
signature/source-map/round-trip tests |
||
selections |
|
|
canonical selection graph |
selection validation tests |
constraints |
|
|
magnetization constraint semantics |
constraint tests |