Geometry¶

Bases: GeometryArea

A GeometryArea whose STEP is the export of model, the tagged assembly in the authored frame.

Config:

• arbitrary_types_allowed: True
• use_attribute_docstrings: True
• extra: allow

model() -> TaggedCompound

19
20
21

@abstractmethod
def model(self) -> TaggedCompound:
    """The tagged assembly in the authored frame."""

build_step(path: Path) -> Path

23
24
25
26

def build_step(self, path: Path) -> Path:
    """Export [`model`][] as a STEP at ``path`` and return it."""
    self.model().export_step(str(path))
    return path

Bases: ConfigArea

A parametric geometry the driver builds into a STEP in the authored frame; config.frame converts it for the solve.

build_step(path: Path) -> Path

18
19
20

def build_step(self, path: Path) -> Path:
    """Write the geometry as a STEP at ``path``, in the authored frame, and return it."""
    raise NotImplementedError

Bases: Compound, HasTags

A build123d compound whose tags pass down to its tagged leaves on export.

Methods:

• rebuild_labels –

  Relabel every tagged part below this compound with its tags.

• placed_leaves –

  Fresh copies of the tagged solids and faces, world-placed, moved by location, and carrying their ancestors' tags (deeper wins).

• flatten_and_tag –

  A new compound of the world-placed tagged leaves (see placed_leaves), labelled with their tags; self is left untouched.

• export_step –

  Export the compound, flattened into its tagged leaves unless flatten is False, to the STEP file filename.

Attributes:

• children_at_global_location (list[Any3D]) –

  Return a list of children located at their global location.

20
21
22
23
24

def __init__(self, *, children: Sequence[AnyShape] = (), tags: TagDict | None = None) -> None:
    """Build the assembly over ``children`` and tag it with ``tags``, the ``key=value`` pairs every tagged leaf below inherits on export."""
    b3d.Compound.__init__(self, children=children)  # pyright: ignore[reportUnknownMemberType]  # OCP ships no stubs
    HasTags.__init__(self, tags)
    self.label = self.tags_str()

children_at_global_location: list[Any3D]

rebuild_labels() -> None

26
27
28
29
30

def rebuild_labels(self) -> None:
    """Relabel every tagged part below this compound with its tags."""
    for child in cast("tuple[object, ...]", self.descendants):
        if isinstance(child, TaggedPart):
            child.label = child.tags_str()

placed_leaves(location: Location | None = None) -> list[TaggedPart | TaggedFace]

32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

def placed_leaves(self, location: b3d.Location | None = None) -> list["TaggedPart | TaggedFace"]:
    """Fresh copies of the tagged solids and faces, world-placed, moved by ``location``, and carrying their ancestors' tags (deeper wins)."""
    moved_by: b3d.Location = location if location is not None else b3d.Location()

    leaves: list[TaggedPart | TaggedFace] = []
    for leaf in cast("tuple[object, ...]", self.descendants):
        if not isinstance(leaf, (TaggedPart, TaggedFace)):
            continue

        # A compound's own location never reaches its children's shapes, and leaf.moved() deep-copies the whole
        # parent tree, so the shapes are rebuilt with every ancestor's location applied.
        parent = cast("b3d.Compound | None", leaf.parent)
        ancestors: b3d.Location = parent.global_location if parent is not None else b3d.Location()
        placement: b3d.Location = moved_by * ancestors
        tags: TagDict = {key: value for node in leaf.path if isinstance(node, HasTags) for key, value in node.tags.items()}

        if isinstance(leaf, TaggedPart):
            placed: list[TaggedPart | TaggedFace] = [TaggedPart([solid.moved(placement) for solid in leaf.solids()], tags=tags)]
        else:
            placed = [TaggedFace(face.moved(placement), tags=tags) for face in leaf.faces()]

        for copy in placed:
            copy.color = leaf.color

        leaves.extend(placed)

    return leaves

flatten_and_tag() -> Compound

60
61
62

def flatten_and_tag(self) -> b3d.Compound:
    """A new compound of the world-placed tagged leaves (see [`placed_leaves`][]), labelled with their tags; ``self`` is left untouched."""
    return b3d.Compound(children=self.placed_leaves(), label=f"Flattened_{self.label}")

export_step(filename: str, flatten: bool = True) -> None

64
65
66
67

def export_step(self, filename: str, flatten: bool = True) -> None:
    """Export the compound, flattened into its tagged leaves unless ``flatten`` is False, to the STEP file ``filename``."""
    compound_to_export: b3d.Compound = self.flatten_and_tag() if flatten else self
    _ = b3d.export_step(compound_to_export, filename)  # pyright: ignore[reportUnknownMemberType]  # OCP ships no stubs

Bases: Face, HasTags

A build123d face whose tags ride its STEP name into a 2D mesh.

Parameters:

• face (Face) –

  The face to wrap, placed where it is.

• tags (TagDict | None, default: None ) –

  The key=value pairs domain materials and EntityTag selectors match, e.g. {TagKey.MATERIAL: N52().tag}.

• name (str | None, default: None ) –

  The body name, kept as written in the Name tag and uppercased in the mesh, Elmer, entities.json and the viewer; None composes it from the tags.

78
79
80
81
82
83
84
85
86
87
88

def __init__(self, face: b3d.Face, *, tags: TagDict | None = None, name: str | None = None) -> None:
    """Wrap ``face`` and tag it.

    Args:
        face: The face to wrap, placed where it is.
        tags: The ``key=value`` pairs domain materials and ``EntityTag`` selectors match, e.g. ``{TagKey.MATERIAL: N52().tag}``.
        name: The body name, kept as written in the ``Name`` tag and uppercased in the mesh, Elmer, ``entities.json`` and the viewer; None composes it from the tags.
    """
    b3d.Face.__init__(self, cast("object", face.wrapped))  # pyright: ignore[reportUnknownMemberType]  # OCP ships no stubs
    HasTags.__init__(self, named(tags, name))
    self.label = self.tags_str()

Bases: Sketch, HasTags

A build123d sketch that carries tags.

94
95
96
97
98

def __init__(self, shapes: Iterable[AnyShape] | None = None, *, tags: TagDict | None = None) -> None:
    """Build the sketch from ``shapes``, such as faces, and tag it with ``tags``."""
    b3d.Sketch.__init__(self, shapes)  # pyright: ignore[reportUnknownMemberType]  # OCP ships no stubs
    HasTags.__init__(self, tags)
    self.label = self.tags_str()

Bases: Part, HasTags

A build123d part whose tags ride its STEP name into the mesh.

Parameters:

• shapes (Iterable[AnyShape]) –

  The solids the part holds, such as [box] or a build123d part.

• tags (TagDict | None, default: None ) –

  The key=value pairs domain materials and EntityTag selectors match, e.g. {TagKey.MATERIAL: N52().tag}.

• name (str | None, default: None ) –

  The body name, kept as written in the Name tag and uppercased in the mesh, Elmer, entities.json and the viewer; None composes it from the tags.

104
105
106
107
108
109
110
111
112
113
114

def __init__(self, shapes: Iterable[AnyShape], *, tags: TagDict | None = None, name: str | None = None) -> None:
    """Build the part from ``shapes`` and tag it.

    Args:
        shapes: The solids the part holds, such as ``[box]`` or a build123d part.
        tags: The ``key=value`` pairs domain materials and ``EntityTag`` selectors match, e.g. ``{TagKey.MATERIAL: N52().tag}``.
        name: The body name, kept as written in the ``Name`` tag and uppercased in the mesh, Elmer, ``entities.json`` and the viewer; None composes it from the tags.
    """
    b3d.Part.__init__(self, shapes)  # pyright: ignore[reportUnknownMemberType]  # OCP ships no stubs
    HasTags.__init__(self, named(tags, name))
    self.label = self.tags_str()

Bases: Edge, HasTags

A build123d edge that carries tags.

120
121
122
123
124

def __init__(self, edge: b3d.Edge, *, tags: TagDict | None = None) -> None:
    """Wrap ``edge``, placed where it is, and tag it with ``tags``."""
    b3d.Edge.__init__(self, cast("object", edge.wrapped))  # pyright: ignore[reportUnknownMemberType]  # OCP ships no stubs
    HasTags.__init__(self, tags)
    self.label = self.tags_str()

Bases: StrEnum

How the specified window OD bounds the layer stack.

Attributes:

• UNDER –

  Keep only layers that stay inside the specified OD: actual coil OD <= specified.

• OVER –

  Stop after the first layer that reaches the specified OD: actual coil OD >= specified.

UNDER = 'under'

OVER = 'over'

Bases: StrEnum

How the wires occupy the specified window length.

Attributes:

• TANGENT –

  The largest integer count of mutually tangent wires, centered in the window; an end gap likely remains.

• SPLAYED –

  The base layer spans the window wall to wall: the same wire count, splayed to an axial pitch above the wire OD.

TANGENT = 'tangent'

SPLAYED = 'splayed'

Round magnet wire.

Attributes:

• copper_diameter (float) –

  d_cu [m]: Bare copper diameter.

• insulation_diameter (float) –

  d_ins [m]: Overall diameter including the enamel.

• copper_area (float) –

  a_cu [m²]: Bare copper cross-section.

• insulation_area (float) –

  a_ins [m²]: Insulated-wire cross-section.

copper_diameter: float

insulation_diameter: float

copper_area: float

insulation_area: float

One coil's revolved winding window: the annular slot between the mandrel and the coil OD.

Attributes:

• inner_radius (float) –

  r_in [m]: Radius of the window's inner wall, where the first layer seats.

• outer_radius (float) –

  r_out [m]: Radius of the window's outer wall (the CAD coil OD); the last layer may stand proud of it under OVER fit.

• length (float) –

  w [m]: Axial length of the window: the coil width, which the geometry sets equal to the magnet length.

• area (float) –

  A_w [m²]: The r-z cross-section of the window: radial depth × axial length.

• mean_radius (float) –

  r_mean [m]: Mid-radius of the window.

• volume (float) –

  V_w [m³]: The revolved window volume, 2π·r_mean·A_w.

inner_radius: float

outer_radius: float

length: float

area: float

mean_radius: float

volume: float

One turn's centerline circle.

Attributes:

• layer (int) –

  Zero-based layer index; layer 0 seats on the window's inner radius.

• index (int) –

  Zero-based position along the layer.

• radius (float) –

  r [m]: Radius of the turn's centerline.

• axial_position (float) –

  z [m]: Axial position of the turn's center, measured from the window mid-plane.

layer: int

index: int

radius: float

axial_position: float

One packed coil, computed by wind; every quantity derives from the wire and window alone.

Methods:

• wind –

  Pack the wire into the window: nested layers alternate n and n-1 turns, upper wires tangent in the grooves of the layer below.

• wire_coordinates –

  Every turn's centerline circle, layer-major; odd layers sit in the grooves, offset by half the axial pitch.

• coil_resistance –

  R_coil [Ω]: Per-coil DC resistance at temperature (K), by the same α law the FEA's σ(T) emits.

• window_current_density –

  J [A/m²]: Homogenized azimuthal current density (signed): the ampere-turns spread over the specified window area — the FEA coil body's drive.

• heat_density –

  q [W/m³]: Per-coil Joule density, I²·R_coil(T) over the revolved window volume.

• wire_current_density –

  J_wire [A/m²]: Current density in the copper itself.

Attributes:

• wire (Wire) –

  The wound wire.

• window (CoilWindow) –

  The window the wire fills.

• outer_diameter_fit (OuterDiameterFit) –

  Whether the stack stops under or just over the specified window OD.

• length_fit (LengthFit) –

  Whether the base layer is tangent-packed or splayed wall to wall.

• axial_pitch (float) –

  p_z [m]: Center-to-center spacing of neighbouring turns in a layer: the wire OD when tangent, wider when splayed.

• radial_pitch (float) –

  p_r [m]: Center-to-center radial rise from one layer to the next, the groove-nested √(d² − (p_z/2)²).

• turns_per_layer (tuple[int, ...]) –

  Turn count of each layer from the inside out; nested layers alternate n and n − 1.

• turns (int) –

  N [-]: Wire turns in the coil.

• num_layers (int) –

  The number of layers in the stack.

• layer_radii (tuple[float, ...]) –

  [m]: Each layer's wire-center radius, layer 0 seated on the window's inner radius.

• actual_outer_diameter (float) –

  [m]: The built coil's outer diameter: the outermost layer plus one wire radius.

• actual_length (float) –

  [m]: The base layer's axial extent; upper layers are inset by half a pitch and never wider.

• end_margin (float) –

  [m]: The gap between the base layer and each window wall (zero when splayed).

• splay_gap (float) –

  [m]: The clearance between neighbouring wires in a layer (zero when tangent).

• wire_length (float) –

  ℓ_wire [m]: Total wire length: each turn's circumference with the helical advance of one axial pitch.

• copper_mass (float) –

  m_wire [kg]: Copper mass of the wire: length × bare-copper section × the Copper material's density.

• copper_fill_factor (float) –

  f_cu [-]: Copper cross-section over the specified window cross-section.

• mechanical_fill_factor (float) –

  f_mech [-]: Insulated-wire cross-section over the specified window cross-section; hex packing bounds it at π/(2√3) ≈ 0.907.

wire: Wire

window: CoilWindow

outer_diameter_fit: OuterDiameterFit

length_fit: LengthFit

axial_pitch: float

radial_pitch: float

turns_per_layer: tuple[int, ...]

turns: int

num_layers: int

layer_radii: tuple[float, ...]

actual_outer_diameter: float

actual_length: float

end_margin: float

splay_gap: float

wire_length: float

copper_mass: float

copper_fill_factor: float

mechanical_fill_factor: float

wind(wire: Wire, window: CoilWindow, outer_diameter_fit: OuterDiameterFit = UNDER, length_fit: LengthFit = TANGENT) -> WoundCoil

141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197

@classmethod
def wind(
    cls,
    wire: Wire,
    window: CoilWindow,
    outer_diameter_fit: OuterDiameterFit = OuterDiameterFit.UNDER,
    length_fit: LengthFit = LengthFit.TANGENT,
) -> WoundCoil:
    """Pack the wire into the window: nested layers alternate n and n-1 turns, upper wires tangent in the grooves of the layer below.

    Args:
        wire: The wire to wind.
        window: The window to fill.
        outer_diameter_fit: Whether the stack stops under or just over the window OD.
        length_fit: Whether the base layer is tangent-packed or splayed wall to wall.
    """
    diameter = wire.insulation_diameter
    base_turns = math.floor(window.length / diameter + _COUNT_TOL)
    if base_turns < 2:
        raise ValueError(f"window length {window.length} m fits {base_turns} wires of OD {diameter} m; the nested-layer model needs at least 2 in the base layer.")

    if length_fit is LengthFit.TANGENT:
        axial_pitch = diameter
    else:
        axial_pitch = (window.length - diameter) / (base_turns - 1)

    # A groove wire touches both neighbours (center distance d) at a radial rise of sqrt(d^2 - (p/2)^2);
    # p < 2d always holds because base_turns is the floor count, so the sqrt stays real and positive.
    radial_pitch = math.sqrt(diameter**2 - (axial_pitch / 2) ** 2)

    seat_radius = window.inner_radius + diameter / 2
    turns_per_layer: list[int] = []
    layer = 0
    while True:
        build_radius = seat_radius + layer * radial_pitch + diameter / 2

        if outer_diameter_fit is OuterDiameterFit.UNDER and build_radius > window.outer_radius + _DIAMETER_TOL:
            break

        turns_per_layer.append(base_turns if layer % 2 == 0 else base_turns - 1)
        layer += 1

        if outer_diameter_fit is OuterDiameterFit.OVER and build_radius >= window.outer_radius - _DIAMETER_TOL:
            break

    if not turns_per_layer:
        raise ValueError(f"window radial depth {window.outer_radius - window.inner_radius} m cannot hold one layer of OD {diameter} m wire under {outer_diameter_fit}.")

    return cls(
        wire=wire,
        window=window,
        outer_diameter_fit=outer_diameter_fit,
        length_fit=length_fit,
        axial_pitch=axial_pitch,
        radial_pitch=radial_pitch,
        turns_per_layer=tuple(turns_per_layer),
    )

wire_coordinates() -> tuple[WireTurn, ...]

217
218
219
220
221
222
223
224
225
226
227

def wire_coordinates(self) -> tuple[WireTurn, ...]:
    """Every turn's centerline circle, layer-major; odd layers sit in the grooves, offset by half the axial pitch."""
    base_turns = self.turns_per_layer[0]
    first_position = -(base_turns - 1) * self.axial_pitch / 2

    turns: list[WireTurn] = []
    for layer, (radius, count) in enumerate(zip(self.layer_radii, self.turns_per_layer)):
        start = first_position + (self.axial_pitch / 2 if layer % 2 else 0.0)
        for index in range(count):
            turns.append(WireTurn(layer=layer, index=index, radius=radius, axial_position=start + index * self.axial_pitch))
    return tuple(turns)

coil_resistance(temperature: float = REFERENCE_TEMPERATURE) -> float

261
262
263
264

def coil_resistance(self, temperature: float = REFERENCE_TEMPERATURE) -> float:
    """`R_coil` `[Ω]`: Per-coil DC resistance at ``temperature`` (K), by the same α law the FEA's σ(T) emits."""
    at_reference = self.wire_length / (CONDUCTIVITY_AT_REFERENCE * self.wire.copper_area)
    return at_reference * (1.0 + RESISTIVITY_TEMPERATURE_COEFFICIENT * (temperature - REFERENCE_TEMPERATURE))

window_current_density(current: float) -> float

278
279
280

def window_current_density(self, current: float) -> float:
    """`J` `[A/m²]`: Homogenized azimuthal current density (signed): the ampere-turns spread over the specified window area — the FEA coil body's drive."""
    return self.turns * current / self.window.area

heat_density(current: float, temperature: float = REFERENCE_TEMPERATURE) -> float

282
283
284

def heat_density(self, current: float, temperature: float = REFERENCE_TEMPERATURE) -> float:
    """`q` `[W/m³]`: Per-coil Joule density, I²·R_coil(T) over the revolved window volume."""
    return current**2 * self.coil_resistance(temperature) / self.window.volume

wire_current_density(current: float) -> float

286
287
288

def wire_current_density(self, current: float) -> float:
    """`J_wire` `[A/m²]`: Current density in the copper itself."""
    return abs(current) / self.wire.copper_area

An axis-aligned 2D rectangle of build123d vectors, with edge and corner accessors.

Parameters:

• min (V | None, default: None ) –

  The lower-left corner; None is the origin.

• max (V | None, default: None ) –

  The upper-right corner; None is the origin.

• label (str, default: '' ) –

  A name shown in the repr.

Attributes:

• left (float) –

  The x of the left edge; setting it moves only that edge.

• right (float) –

  The x of the right edge; setting it moves only that edge.

• bottom (float) –

  The y of the bottom edge; setting it moves only that edge.

• top (float) –

  The y of the top edge; setting it moves only that edge.

• width (float) –

  The extent along x.

• height (float) –

  The extent along y.

• size (V) –

  The width and height as a vector.

• center (V) –

  The midpoint.

• corners (list[V]) –

  The four corners, counter-clockwise from min.

• points (list[V]) –

  The four corners, the same as corners.

 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100

def __init__(self, min: V | None = None, max: V | None = None, label: str = ""):
    """Span ``min`` to ``max``.

    Args:
        min: The lower-left corner; None is the origin.
        max: The upper-right corner; None is the origin.
        label: A name shown in the repr.
    """
    self.min = min or V()
    self.max = max or V()
    self.label = label

left: float

right: float

bottom: float

top: float

width: float

height: float

size: V

center: V

corners: list[V]

points: list[V]

The frame-shaped region between an inner and an outer rectangle.

Parameters:

• inside (Rect | None, default: None ) –

  The inner rectangle; None starts an empty one.

• outside (Rect | None, default: None ) –

  The outer rectangle; None starts an empty one.

• label (str, default: '' ) –

  A name for the region and its faces; empty derives one from the object id.

Methods:

• face –

  Return a face representing the area between the inside and outside rectangles.

• extrude –

  Return a part representing the area between the inside and outside rectangles extruded to the given thickness.

210
211
212
213
214
215
216
217
218
219
220
221

def __init__(self, inside: Rect | None = None, outside: Rect | None = None, label: str = ""):
    """Hold the two rectangles.

    Args:
        inside: The inner rectangle; None starts an empty one.
        outside: The outer rectangle; None starts an empty one.
        label: A name for the region and its faces; empty derives one from the object id.
    """

    self.label = label or f"NestedRect_{id(self)}"
    self.inside = inside or Rect(label=f"{self.label}.inside")
    self.outside = outside or Rect(label=f"{self.label}.outside")

face() -> Face

254
255
256
257
258
259

def face(self) -> b3d.Face:
    """Return a face representing the area between the inside and outside rectangles."""
    outer_wire = b3d.Rectangle(self.outside.width, self.outside.height).wire().translate(self.outside.center)
    inner_wire = b3d.Rectangle(self.inside.width, self.inside.height).wire().translate(self.inside.center)
    face = b3d.Face(outer_wire, [inner_wire], label=f"{self.label}_Face")
    return face