Physical¶

Bases: Condition

A driven coil under COIL_MAGNETOSTATICS (body target): bodies sharing this condition become one massive CoilSolver Component normalized to current.

Reverse the drive by swapping the terminal roles, not with a negative current.

Fields:

• kind (Literal['coil_drive'])
• physics (Physics)
• target (ConditionTarget)
• current (Current)

kind: Literal['coil_drive'] = 'coil_drive'

physics: Physics = Physics.COIL_MAGNETOSTATICS

target: ConditionTarget = ConditionTarget.BODY

current: Current

to_elmer() -> dict[str, float | str]

339
340
341
342
343
344
345

def to_elmer(self) -> dict[str, float | str]:
    """The ``Desired Coil Current`` and the massive ``Coil Type``."""
    out: dict[str, float | str] = super().to_elmer()
    # Massive: one solid conductor whose current distribution is the solved conduction field (the PCB winding),
    # as opposed to "stranded" (a wound bundle with imposed uniform fill).
    out["Coil Type"] = '"massive"'
    return out

Bases: Condition

One end of an open coil's terminal pair, Elmer's Coil Start or Coil End marker (COIL_MAGNETOSTATICS, boundary target).

The electrode's end face must lie on the domain boundary (GeometryConfig.terminate_electrodes); positive coil current flows from start to end.

Fields:

• kind (Literal['coil_terminal'])
• physics (Physics)
• target (ConditionTarget)
• role (Literal['start', 'end'])

kind: Literal['coil_terminal'] = 'coil_terminal'

physics: Physics = Physics.COIL_MAGNETOSTATICS

target: ConditionTarget = ConditionTarget.BOUNDARY

role: Literal['start', 'end']

to_elmer() -> dict[str, float | str]

368
369
370

def to_elmer(self) -> dict[str, float | str]:
    """The ``Coil Start`` or ``Coil End`` flag for this ``role``."""
    return {"Coil Start" if self.role == "start" else "Coil End": "Logical True"}

Bases: BaseModel

Base condition: subclasses pin physics/target defaults and implement to_elmer. Never instantiated directly (no kind discriminator).

Config:

• arbitrary_types_allowed: True
• use_attribute_docstrings: True

Fields:

• physics (Physics)
• target (ConditionTarget)

external_only: bool = False

physics: Physics

target: ConditionTarget

to_elmer(*args: Any, **kwargs: Any) -> dict[str, float | str]

 95
 96
 97
 98
 99
100
101
102
103

def to_elmer(self, *args: Any, **kwargs: Any) -> dict[str, float | str]:  # pyright: ignore[reportExplicitAny, reportAny]  # variadic: subclass to_elmer signatures diverge (Magnetization takes a magnitude)
    """This condition's Elmer sif keyword dict, reflected from each field's ``ElmerKeyword`` metadata."""
    out: dict[str, float | str] = {}
    for name, field in type(self).model_fields.items():
        spec: ElmerKeyword | None = _elmer_keyword(field)
        if spec is None:
            continue
        out[spec.key] = _si(getattr(self, name), spec.unit)  # pyright: ignore[reportAny]  # getattr is Any
    return out

check_frame(frame: Frame) -> None

105
106

def check_frame(self, frame: Frame) -> None:
    """Raise when this condition cannot drive a ``frame`` solve."""

Bases: StrEnum

Whether a condition attaches to a 3D body or a 2D boundary.

Attributes:

• BODY –

  Attach to a body.

• BOUNDARY –

  Attach to a boundary surface.

BODY = 'body'

BOUNDARY = 'boundary'

Bases: Condition

Convective (Newton-cooling) boundary condition (thermal, boundary target); external_only — a film BC on an interior interface would bypass the conduction path.

Fields:

• kind (Literal['convection'])
• physics (Physics)
• target (ConditionTarget)
• coefficient (HeatTransferCoefficient)
• ext_temperature (Temperature)

kind: Literal['convection'] = 'convection'

physics: Physics = Physics.THERMAL

target: ConditionTarget = ConditionTarget.BOUNDARY

coefficient: HeatTransferCoefficient

ext_temperature: Temperature

Bases: Condition

Uniform signed azimuthal current density J = N·I/A over a winding window (axisymmetric magnetostatics, body target), the homogenized stranded-coil drive.

Requires frame=Axisymmetric().

Fields:

• kind (Literal['current_density'])
• physics (Physics)
• target (ConditionTarget)
• value (CurrentDensity)

kind: Literal['current_density'] = 'current_density'

physics: Physics = Physics.MAGNETOSTATICS_2D

target: ConditionTarget = ConditionTarget.BODY

value: CurrentDensity

check_frame(frame: Frame) -> None

182
183
184
185

def check_frame(self, frame: Frame) -> None:
    """Raise unless ``frame`` is axisymmetric."""
    if isinstance(frame, Solid):
        raise ValueError("CurrentDensity is the axisymmetric coil drive; it requires frame=Axisymmetric().")

Bases: Condition

Dirichlet electric-potential boundary condition (current conduction, boundary target), one electrode of a phase's terminal pair.

Fields:

• kind (Literal['fixed_potential'])
• physics (Physics)
• target (ConditionTarget)
• value (Voltage)

kind: Literal['fixed_potential'] = 'fixed_potential'

physics: Physics = Physics.CURRENT_CONDUCTION

target: ConditionTarget = ConditionTarget.BOUNDARY

value: Voltage

to_elmer() -> dict[str, float | str]

292
293
294
295
296
297

def to_elmer(self) -> dict[str, float | str]:
    """The electrode potential plus the ``Save Scalars`` flag that makes SaveScalars integrate the electrode current."""
    out: dict[str, float | str] = super().to_elmer()
    # Mark the electrode for SaveScalars boundary integration (the per-phase current measurement).
    out["Save Scalars"] = "Logical True"
    return out

Bases: Condition

Dirichlet temperature boundary condition (thermal, boundary target).

Fields:

• kind (Literal['fixed_temperature'])
• physics (Physics)
• target (ConditionTarget)
• value (Temperature)

kind: Literal['fixed_temperature'] = 'fixed_temperature'

physics: Physics = Physics.THERMAL

target: ConditionTarget = ConditionTarget.BOUNDARY

value: Temperature

Bases: Condition

An Elmer Component lumping CalcFields' magnetic force and torque over the bodies this condition's tag matches (magnetic physics, body target).

Fields:

• kind (Literal['force_component'])
• physics (Physics)
• target (ConditionTarget)
• label (str | None)
• calculate_magnetic_force (bool)
• calculate_magnetic_torque (bool)
• torque_origin (Vec3Field | None)
• torque_axis (DirectionField | None)

kind: Literal['force_component'] = 'force_component'

physics: Physics = Physics.MAGNETOSTATICS

target: ConditionTarget = ConditionTarget.BODY

label: str | None = None

calculate_magnetic_force: bool = True

calculate_magnetic_torque: bool = False

torque_origin: Vec3Field | None = None

torque_axis: DirectionField | None = None

to_elmer() -> dict[str, float | str]

400
401
402
403
404
405
406
407
408
409
410
411

def to_elmer(self) -> dict[str, float | str]:
    """The CalcFields force and torque flags, plus the torque origin and axis when set."""
    out: dict[str, float | str] = {}
    if self.calculate_magnetic_force:
        out["Calculate Magnetic Force"] = "Logical True"
    if self.calculate_magnetic_torque:
        out["Calculate Magnetic Torque"] = "Logical True"
    if self.torque_origin is not None:
        out["Torque Origin(3)"] = f"Real {self.torque_origin.x:.6g} {self.torque_origin.y:.6g} {self.torque_origin.z:.6g}"
    if self.torque_axis is not None:
        out["Torque Axis(3)"] = f"Real {self.torque_axis.x:.6g} {self.torque_axis.y:.6g} {self.torque_axis.z:.6g}"
    return out

check_frame(frame: Frame) -> None

413
414
415
416
417
418

def check_frame(self, frame: Frame) -> None:
    """Raise when torque is requested under an axisymmetric ``frame``."""
    torque: bool = self.calculate_magnetic_torque or self.torque_origin is not None or self.torque_axis is not None

    if torque and isinstance(frame, Axisymmetric):
        raise ValueError("ForceComponent torque has no axisymmetric form; drop calculate_magnetic_torque, torque_origin and torque_axis under frame=Axisymmetric().")

Bases: Condition

Prescribed heat flux boundary condition (thermal, boundary target).

Fields:

• kind (Literal['heat_flux'])
• physics (Physics)
• target (ConditionTarget)
• value (HeatFlux)

kind: Literal['heat_flux'] = 'heat_flux'

physics: Physics = Physics.THERMAL

target: ConditionTarget = ConditionTarget.BOUNDARY

value: HeatFlux

Bases: Condition

Volumetric heat source in W/m³ (thermal, body target).

With temperature_coefficient set, the source scales linearly with the local temperature, the σ(T) Joule feedback of a prescribed-current winding.

Fields:

• kind (Literal['heat_source'])
• physics (Physics)
• target (ConditionTarget)
• power_density (PowerDensity)
• temperature_coefficient (float | None)
• reference_temperature (Temperature | None)

kind: Literal['heat_source'] = 'heat_source'

physics: Physics = Physics.THERMAL

target: ConditionTarget = ConditionTarget.BODY

power_density: PowerDensity

temperature_coefficient: float | None = None

reference_temperature: Temperature | None = None

to_elmer() -> dict[str, float | str]

265
266
267
268
269
270
271
272
273
274

def to_elmer(self) -> dict[str, float | str]:
    """The ``Volumetric Heat Source`` keyword, a MATC expression in temperature when ``temperature_coefficient`` is set."""
    out: dict[str, float | str] = super().to_elmer()
    if self.temperature_coefficient is not None:
        if self.reference_temperature is None:
            raise ValueError("temperature_coefficient requires reference_temperature (the temperature power_density holds at).")
        source_at_reference: float = _si(self.power_density, U.W / U.m**3)
        reference_kelvin: float = _si(self.reference_temperature, U.K)
        out["Volumetric Heat Source"] = f'Variable Temperature\n    Real MATC "{source_at_reference:.9g}*(1.0+{self.temperature_coefficient:.9g}*(tx(0)-{reference_kelvin:.9g}))"'
    return out

Bases: Condition

Joule heat source body force (coupled current->thermal, body target): HeatSolve integrates StatCurrentSolve's loss density as the heat source.

Carries no value — the magnitude is the solved current field itself.

Fields:

• kind (Literal['joule_heat'])
• physics (Physics)
• target (ConditionTarget)

kind: Literal['joule_heat'] = 'joule_heat'

physics: Physics = Physics.JOULE_HEATING

target: ConditionTarget = ConditionTarget.BODY

to_elmer() -> dict[str, float | str]

316
317
318

def to_elmer(self) -> dict[str, float | str]:
    """The ``Joule Heat`` flag."""
    return {"Joule Heat": "Logical True"}

Bases: Condition

Permanent-magnet body force (magnetostatics, body target).

The direction is per-region and lives here; the magnitude |M| = Bᵣ/μ₀ is a material property passed into to_elmer.

Fields:

• kind (Literal['magnetization'])
• physics (Physics)
• target (ConditionTarget)
• direction (DirectionField | None)

kind: Literal['magnetization'] = 'magnetization'

physics: Physics = Physics.MAGNETOSTATICS

target: ConditionTarget = ConditionTarget.BODY

direction: DirectionField | None

to_elmer(magnitude: float, frame: Frame) -> dict[str, float | str]

128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

def to_elmer(self, magnitude: float, frame: Frame) -> dict[str, float | str]:
    """The ``Magnetization`` components of ``magnitude`` (A/m) along the direction, in ``frame``'s solve coordinates."""
    unit: Vec3 | None = self.direction

    if unit is None:
        raise ValueError("A Magnetization without a direction has no components to emit.")

    match frame:
        case Solid():
            m: Vec3 = unit * magnitude
            return {
                "Magnetization 1": f"{m.x:.6g}",
                "Magnetization 2": f"{m.y:.6g}",
                "Magnetization 3": f"{m.z:.6g}",
            }
        case Axisymmetric():
            along: float | None = frame.axis.along(unit)

            if along is None:
                raise ValueError(f"Magnetization direction {self.direction} is not along the symmetry axis {frame.axis.direction}; a transverse magnetization is not axisymmetric.")

            return {
                "Magnetization 1": "0",
                "Magnetization 2": f"{along * magnitude:.6g}",
            }

check_frame(frame: Frame) -> None

154
155
156
157
158
159
160
161

def check_frame(self, frame: Frame) -> None:
    """Raise when an axisymmetric ``frame`` meets a direction off its symmetry axis."""
    # A missing direction is left to Sim.validate, which reports it as a missing direction rather than a frame mismatch.
    if not isinstance(frame, Axisymmetric) or self.direction is None:
        return

    if frame.axis.along(self.direction) is None:
        raise ValueError(f"Magnetization direction {self.direction} is not along the symmetry axis {frame.axis.direction}; a transverse magnetization is not axisymmetric.")

Bases: ConfigArea

The materials the mesher matches to STEP parts, plus the per-region EntityTag overrides (conditions / mesh refinement).

Fields:

• materials (list[MaterialProperties])
• tags (list[EntityTag])

materials: list[MaterialProperties]

tags: list[EntityTag]

check_frame(frame: Frame) -> None

73
74
75
76
77

def check_frame(self, frame: Frame) -> None:
    """Raise when a condition here cannot drive a ``frame`` solve."""
    for tag in self.tags:
        for condition in tag.conditions:
            condition.check_frame(frame)

Bases: ConfigArea

A per-region override matched to a mesh entity by its authored tags; carries the region's self-describing conditions.

Fields:

• selector (TagDict)
• conditions (list[ConditionUnion])
• mesh_size (float | None)

selector: TagDict

conditions: list[ConditionUnion]

mesh_size: float | None = None

name: str

matches(tags: Mapping[str, str]) -> bool

46
47
48

def matches(self, tags: Mapping[str, str]) -> bool:
    """Whether an entity's tag dict satisfies every selector pair."""
    return all(tags.get(key) == value for key, value in self.selector.items())

print_tree(tree: Tree) -> None

57
58
59
60
61

def print_tree(self, tree: Tree) -> None:
    """Add this tag and its conditions to ``tree``."""
    report: Tree = tree.add(COLORS.H2(f"Tag: {self.name}"))
    for condition in self.conditions:
        report.add(COLORS.Prop(type(condition).__name__, f"{condition}"))

Bases: _Binary

The sum of two subexpressions.

Fields:

• left ('Expr')
• right ('Expr')
• op (Literal['add'])
• _symbol (str)

op: Literal['add'] = 'add'

evaluate(env: Mapping[str, float]) -> float

159
160
161

def evaluate(self, env: Mapping[str, float]) -> float:
    """The sum of both operands."""
    return self.left.evaluate(env) + self.right.evaluate(env)

Bases: ExprNode

A literal SI magnitude.

Fields:

• op (Literal['const'])
• value (float)

op: Literal['const'] = 'const'

value: float

evaluate(env: Mapping[str, float]) -> float

92
93
94

def evaluate(self, env: Mapping[str, float]) -> float:
    """The literal value."""
    return self.value

render(refs: Mapping[str, str]) -> str

96
97
98
99

def render(self, refs: Mapping[str, str]) -> str:
    """The literal at full float precision."""
    # repr keeps full float precision; MATC and Lua both read e-notation.
    return repr(self.value)

parameters() -> frozenset[str]

101
102
103

def parameters(self) -> frozenset[str]:
    """The empty set: a literal references no parameter."""
    return frozenset()

Bases: _Binary

The quotient of two subexpressions.

Fields:

• left ('Expr')
• right ('Expr')
• op (Literal['div'])
• _symbol (str)

op: Literal['div'] = 'div'

evaluate(env: Mapping[str, float]) -> float

198
199
200

def evaluate(self, env: Mapping[str, float]) -> float:
    """The left operand divided by the right one."""
    return self.left.evaluate(env) / self.right.evaluate(env)

Bases: BaseModel

Base node: shared config + Python operator composition, so laws are authored as plain arithmetic.

Config:

• frozen: True
• use_attribute_docstrings: True

evaluate(env: Mapping[str, float]) -> float

38
39
40

def evaluate(self, env: Mapping[str, float]) -> float:
    """This subtree's value with each parameter bound to a bare SI float."""
    raise NotImplementedError

render(refs: Mapping[str, str]) -> str

42
43
44

def render(self, refs: Mapping[str, str]) -> str:
    """This subtree as backend source, with each parameter name replaced by its reference (e.g. ``tx(0)``)."""
    raise NotImplementedError

parameters() -> frozenset[str]

46
47
48

def parameters(self) -> frozenset[str]:
    """Every parameter name referenced in this subtree."""
    raise NotImplementedError

Bases: _Binary

The product of two subexpressions.

Fields:

• left ('Expr')
• right ('Expr')
• op (Literal['mul'])
• _symbol (str)

op: Literal['mul'] = 'mul'

evaluate(env: Mapping[str, float]) -> float

185
186
187

def evaluate(self, env: Mapping[str, float]) -> float:
    """The product of both operands."""
    return self.left.evaluate(env) * self.right.evaluate(env)

Bases: ExprNode

The negation of a subexpression.

Fields:

• op (Literal['neg'])
• operand ('Expr')

op: Literal['neg'] = 'neg'

operand: 'Expr'

evaluate(env: Mapping[str, float]) -> float

239
240
241

def evaluate(self, env: Mapping[str, float]) -> float:
    """The negated operand."""
    return -self.operand.evaluate(env)

render(refs: Mapping[str, str]) -> str

243
244
245

def render(self, refs: Mapping[str, str]) -> str:
    """The negation as ``(-operand)``."""
    return f"(-{self.operand.render(refs)})"

parameters() -> frozenset[str]

247
248
249

def parameters(self) -> frozenset[str]:
    """The operand's parameters."""
    return self.operand.parameters()

Bases: ExprNode

A named parameter (e.g. temperature), bound at evaluation/render time.

Fields:

• op (Literal['param'])
• name (str)

op: Literal['param'] = 'param'

name: str

evaluate(env: Mapping[str, float]) -> float

115
116
117
118
119

def evaluate(self, env: Mapping[str, float]) -> float:
    """The value ``env`` binds to this parameter."""
    if self.name not in env:
        raise KeyError(f"expression parameter {self.name!r} not bound; supplied: {sorted(env)}")
    return env[self.name]

render(refs: Mapping[str, str]) -> str

121
122
123
124
125

def render(self, refs: Mapping[str, str]) -> str:
    """The backend reference ``refs`` binds to this parameter."""
    if self.name not in refs:
        raise KeyError(f"expression parameter {self.name!r} has no backend reference; supplied: {sorted(refs)}")
    return refs[self.name]

parameters() -> frozenset[str]

127
128
129

def parameters(self) -> frozenset[str]:
    """This parameter's name."""
    return frozenset({self.name})

Bases: ExprNode

One subexpression raised to the power of another.

Fields:

• op (Literal['pow'])
• base ('Expr')
• exponent ('Expr')

op: Literal['pow'] = 'pow'

base: 'Expr'

exponent: 'Expr'

evaluate(env: Mapping[str, float]) -> float

215
216
217
218

def evaluate(self, env: Mapping[str, float]) -> float:
    """The base raised to the exponent."""
    # math.pow keeps the operation float-typed (the ** operator's stub admits complex).
    return math.pow(self.base.evaluate(env), self.exponent.evaluate(env))

render(refs: Mapping[str, str]) -> str

220
221
222
223

def render(self, refs: Mapping[str, str]) -> str:
    """The power as ``(base ^ exponent)``."""
    # ^ is exponentiation in both MATC and Lua.
    return f"({self.base.render(refs)} ^ {self.exponent.render(refs)})"

parameters() -> frozenset[str]

225
226
227

def parameters(self) -> frozenset[str]:
    """The parameters of the base and the exponent."""
    return self.base.parameters() | self.exponent.parameters()

Bases: _Binary

The difference of two subexpressions.

Fields:

• left ('Expr')
• right ('Expr')
• op (Literal['sub'])
• _symbol (str)

op: Literal['sub'] = 'sub'

evaluate(env: Mapping[str, float]) -> float

172
173
174

def evaluate(self, env: Mapping[str, float]) -> float:
    """The left operand minus the right one."""
    return self.left.evaluate(env) - self.right.evaluate(env)

Bases: BaseModel

Pydantic base implementing parameter checking once; subclasses declare parameters / result_dimensionality and implement _evaluate.

Extra keyword arguments are ignored, so an operating point may carry more quantities than a property needs.

Config:

• arbitrary_types_allowed: True
• use_attribute_docstrings: True

parameters: Mapping[str, str]

result_dimensionality: str

Bases: BasePropertyFunction

A property defined by sample points and interpolated between them (1-D only for now).

Point inputs are validated against param_dims at construction; out-of-range raises unless extrapolate=True.

Fields:

• kind (Literal['calibration'])
• param_dims (dict[str, str])
• points (list[CalibrationPoint])
• method (Literal['linear', 'nearest', 'cubic'])
• extrapolate (bool)

Validators:

• _validate_points

kind: Literal['calibration'] = 'calibration'

param_dims: dict[str, str]

points: list[CalibrationPoint]

method: Literal['linear', 'nearest', 'cubic'] = 'linear'

extrapolate: bool = False

parameters: Mapping[str, str]

result_dimensionality: str

Bases: BaseModel

One measured sample: input quantities by name and the resulting output.

Config:

• arbitrary_types_allowed: True
• use_attribute_docstrings: True

Fields:

• inputs (dict[str, Quantity])
• output (Quantity)

Validators:

• _coerce_inputs → inputs
• _coerce_output → output

inputs: dict[str, Quantity]

output: Quantity

Bases: BasePropertyFunction

A property defined by an explicit Python callable, pint-in / pint-out; the callable is code, not JSON-serializable.

Fields:

• param_dims (dict[str, str])
• result_dim (str)
• expression (Callable[..., Quantity])

param_dims: dict[str, str]

result_dim: str

expression: Callable[..., Quantity]

parameters: Mapping[str, str]

result_dimensionality: str

Bases: BasePropertyFunction

A property defined by a serializable typed expression AST (physical.expressions) — ClosedForm as data instead of code.

body computes the result's SI magnitude in result_units from parameters bound as SI-base magnitudes, matching Elmer's tx.

Fields:

• kind (Literal['expression'])
• param_dims (dict[str, str])
• result_units (str)
• body (Expr)

Validators:

• _validate_body_parameters

kind: Literal['expression'] = 'expression'

param_dims: dict[str, str]

result_units: str

body: Expr

parameters: Mapping[str, str]

result_dimensionality: str

Bases: PropertyError

A supplied parameter had the wrong dimensionality.

Parameters:

• fn ('PropertyFunction') –

  The property that rejected the call.

• name (str) –

  The offending parameter, or <result> for a closed form's return value.

• expected (str) –

  The dimensionality the parameter needs.

• got (object) –

  The dimensionality, or the type, that was supplied.

61
62
63
64
65
66
67
68
69
70
71
72
73
74

def __init__(self, fn: "PropertyFunction", name: str, expected: str, got: object) -> None:
    """Record which parameter of ``fn`` had the wrong dimensionality.

    Args:
        fn: The property that rejected the call.
        name: The offending parameter, or ``<result>`` for a closed form's return value.
        expected: The dimensionality the parameter needs.
        got: The dimensionality, or the type, that was supplied.
    """
    self.fn: PropertyFunction = fn
    self.name: str = name
    self.expected: str = expected
    self.got: object = got
    super().__init__(f"{type(fn).__name__} parameter {name!r} expected {expected or 'dimensionless'}, got {got}.")

Bases: Exception

Base class for every property-function error.

Bases: Protocol

A material property as a function of zero or more named pint quantities, returning a pint Quantity.

Methods:

• __call__ –

  Evaluate. Raises a typed error if a required parameter is missing or has the wrong dimensionality.

Attributes:

• parameters (Mapping[str, str]) –

  Required parameter name -> expected dimensionality (pint string); this IS the call schema.

• result_dimensionality (str) –

  Dimensionality of the returned quantity, e.g. '[power]/[length]/[temperature]'.

parameters: Mapping[str, str]

result_dimensionality: str

__call__(**kwargs: Quantity) -> Quantity