polecraft 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
polecraft/__init__.py ADDED
@@ -0,0 +1,17 @@
1
+ """Pole-Craft: design and simulation tool for quasi-direct-drive (QDD) motors."""
2
+
3
+ __version__ = "0.0.1"
4
+
5
+ from polecraft.design import Design, design_from_dict, design_to_dict, load_design
6
+ from polecraft.machines import machine_for
7
+ from polecraft.validation import DesignError
8
+
9
+ __all__ = [
10
+ "Design",
11
+ "DesignError",
12
+ "__version__",
13
+ "design_from_dict",
14
+ "design_to_dict",
15
+ "load_design",
16
+ "machine_for",
17
+ ]
polecraft/__main__.py ADDED
@@ -0,0 +1,7 @@
1
+ """Lets ``python -m polecraft`` run the command line."""
2
+
3
+ import sys
4
+
5
+ from polecraft.cli import main
6
+
7
+ sys.exit(main())
polecraft/cli.py ADDED
@@ -0,0 +1,94 @@
1
+ """The ``polecraft`` command."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sys
7
+ from pathlib import Path
8
+ from typing import Sequence
9
+
10
+ from polecraft import __version__
11
+ from polecraft.design import load_design
12
+ from polecraft.machines import machine_for
13
+ from polecraft.timing import Timings
14
+ from polecraft.validation import DesignError
15
+
16
+
17
+ def _parser() -> argparse.ArgumentParser:
18
+ parser = argparse.ArgumentParser(
19
+ prog="polecraft", description="Design and simulation tool for QDD motors."
20
+ )
21
+ parser.add_argument("--version", action="version", version=f"polecraft {__version__}")
22
+ commands = parser.add_subparsers(dest="command", required=True)
23
+
24
+ mesh = commands.add_parser(
25
+ "mesh", help="mesh a design and save a picture of it",
26
+ description="Build the geometry of a design, mesh it and save a coloured picture.",
27
+ )
28
+ mesh.add_argument("design", type=Path, help="design file (YAML)")
29
+ mesh.add_argument(
30
+ "-o", "--output", type=Path,
31
+ help="picture to write; .png, .svg or .pdf (default: <design name>_mesh.png)",
32
+ )
33
+ mesh.add_argument(
34
+ "--full", action="store_true",
35
+ help="mesh the whole machine, not only the slice that repeats",
36
+ )
37
+ mesh.add_argument(
38
+ "--size", type=float, default=1.0,
39
+ help="scale of the triangles; 0.5 halves their edges (default: 1)",
40
+ )
41
+ return parser
42
+
43
+
44
+ def _mesh(arguments: argparse.Namespace) -> int:
45
+ timings = Timings()
46
+ # Imported here so that other commands start without loading Matplotlib.
47
+ with timings.stage("load libraries"):
48
+ from polecraft.core.mesh import build_mesh
49
+ from polecraft.plot import picture_path, plot_mesh
50
+
51
+ # Checked first, so that a mistyped file name does not cost a mesh.
52
+ output = picture_path(arguments.output or Path(f"{arguments.design.stem}_mesh.png"))
53
+
54
+ with timings.stage("load design"):
55
+ design = load_design(arguments.design)
56
+ with timings.stage("geometry"):
57
+ geometry = machine_for(design).build_geometry(full=arguments.full)
58
+ with timings.stage("mesh"):
59
+ mesh = build_mesh(geometry, size=arguments.size)
60
+
61
+ shown = "whole machine" if arguments.full else "repeating slice"
62
+ title = f"{arguments.design.name}: {design.slots} slots, {design.poles} poles, {shown}"
63
+ with timings.stage("picture"):
64
+ written = plot_mesh(mesh, geometry, output, title=title)
65
+
66
+ print(f"{arguments.design.name}: {design.slots} slots, {design.poles} poles")
67
+ print(f" {shown}: {len(geometry.regions)} regions")
68
+ print(f" mesh: {len(mesh.nodes)} nodes, {len(mesh.triangles)} triangles")
69
+ print(f" smallest triangle angle: {mesh.smallest_angles().min():.1f} degrees")
70
+ print(f" picture: {written}")
71
+ print(timings.report())
72
+ return 0
73
+
74
+
75
+ def main(argv: Sequence[str] | None = None) -> int:
76
+ """Run the command line. Returns the exit code: 0 for success, 1 for failure.
77
+
78
+ Stopping it with Ctrl-C returns 130.
79
+ """
80
+ arguments = _parser().parse_args(argv)
81
+ try:
82
+ return _mesh(arguments)
83
+ except DesignError as error:
84
+ print(error, file=sys.stderr)
85
+ except (ImportError, ValueError, OSError) as error:
86
+ print(f"polecraft: {error}", file=sys.stderr)
87
+ except KeyboardInterrupt:
88
+ print("polecraft: interrupted", file=sys.stderr)
89
+ return 130
90
+ return 1
91
+
92
+
93
+ if __name__ == "__main__":
94
+ sys.exit(main())
@@ -0,0 +1,5 @@
1
+ """Motor-agnostic core: meshing, field solve, motion, materials, winding, post-processing.
2
+
3
+ Nothing in this package may know the motor type. It works only with regions,
4
+ materials, coils and magnets.
5
+ """
@@ -0,0 +1,281 @@
1
+ """Two-dimensional regions: what a machine hands to the mesher and the solver.
2
+
3
+ A machine is described as a set of regions, each a closed outline of straight
4
+ lines and circular arcs with a material and, where it applies, a
5
+ magnetisation or a coil side. Nothing here knows which machine the regions
6
+ came from.
7
+
8
+ Lengths are in metres and angles in radians. Angles are measured
9
+ counter-clockwise from the x axis.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import math
15
+ from dataclasses import dataclass, replace
16
+ from typing import Sequence
17
+
18
+ import numpy as np
19
+
20
+ Point = tuple[float, float]
21
+
22
+ # Vertices closer than this are treated as the same point (metres).
23
+ SAME_POINT = 1e-12
24
+
25
+ # Arcs sweeping more than this are cut in two (radians, about 115 degrees).
26
+ LONGEST_ARC = 2.0
27
+
28
+
29
+ def polar(radius: float, angle: float) -> Point:
30
+ """The point at a radius and angle from the origin."""
31
+ return (radius * math.cos(angle), radius * math.sin(angle))
32
+
33
+
34
+ def _rotate(point: Point, angle: float) -> Point:
35
+ c, s = math.cos(angle), math.sin(angle)
36
+ return (c * point[0] - s * point[1], s * point[0] + c * point[1])
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class Edge:
41
+ """A straight line, or a circular arc if ``centre`` is given.
42
+
43
+ An arc runs from start to end counter-clockwise about its centre if
44
+ ``ccw`` is true, clockwise otherwise, and always sweeps less than half a
45
+ turn, so start, end and centre define it without ambiguity.
46
+ """
47
+
48
+ start: Point
49
+ end: Point
50
+ centre: Point | None = None
51
+ ccw: bool = True
52
+
53
+ @property
54
+ def radius(self) -> float:
55
+ """Arc radius; 0 for a straight line."""
56
+ if self.centre is None:
57
+ return 0.0
58
+ return math.dist(self.start, self.centre)
59
+
60
+ @property
61
+ def sweep(self) -> float:
62
+ """Angle the arc turns through, always positive; 0 for a straight line."""
63
+ if self.centre is None:
64
+ return 0.0
65
+ a0 = math.atan2(self.start[1] - self.centre[1], self.start[0] - self.centre[0])
66
+ a1 = math.atan2(self.end[1] - self.centre[1], self.end[0] - self.centre[0])
67
+ turn = a1 - a0 if self.ccw else a0 - a1
68
+ return turn % (2 * math.pi)
69
+
70
+ def points(self, tolerance: float) -> list[Point]:
71
+ """Points along the edge, start included and end excluded.
72
+
73
+ An arc is cut into chords that stay within ``tolerance`` of it.
74
+ """
75
+ if self.centre is None:
76
+ return [self.start]
77
+ radius, sweep = self.radius, self.sweep
78
+ # A chord spanning angle t lies r (1 - cos(t/2)) ~ r t^2 / 8 inside the arc.
79
+ pieces = max(1, math.ceil(sweep / math.sqrt(8 * tolerance / radius)))
80
+ a0 = math.atan2(self.start[1] - self.centre[1], self.start[0] - self.centre[0])
81
+ step = (sweep if self.ccw else -sweep) / pieces
82
+ return [self.start] + [
83
+ (
84
+ self.centre[0] + radius * math.cos(a0 + i * step),
85
+ self.centre[1] + radius * math.sin(a0 + i * step),
86
+ )
87
+ for i in range(1, pieces)
88
+ ]
89
+
90
+ def rotated(self, angle: float) -> Edge:
91
+ """The same edge turned about the origin."""
92
+ centre = None if self.centre is None else _rotate(self.centre, angle)
93
+ return Edge(_rotate(self.start, angle), _rotate(self.end, angle), centre, self.ccw)
94
+
95
+
96
+ @dataclass(frozen=True)
97
+ class Magnetisation:
98
+ """How a magnet region is magnetised.
99
+
100
+ The axis angle and the points given to ``direction`` are in the frame the
101
+ region is described in. For a rotor that has turned, turn the region with
102
+ ``Region.rotated`` first.
103
+ """
104
+
105
+ pattern: str # "parallel": one direction throughout; "radial": along the radius
106
+ axis_angle: float # angle of the magnet's centre line
107
+ polarity: int # +1 points away from the machine axis, -1 towards it
108
+
109
+ def direction(self, x: float, y: float) -> Point:
110
+ """Unit vector of the magnetisation at a point of the magnet."""
111
+ angle = self.axis_angle if self.pattern == "parallel" else math.atan2(y, x)
112
+ return (self.polarity * math.cos(angle), self.polarity * math.sin(angle))
113
+
114
+
115
+ @dataclass(frozen=True)
116
+ class CoilSide:
117
+ """One side of a coil, filling a region of a slot."""
118
+
119
+ phase: str # "A", "B" or "C"
120
+ tooth: int # the tooth this coil is wound on
121
+ sign: int # +1: positive phase current flows out of the plane here
122
+ turns: int # conductors of the coil passing through the region
123
+
124
+
125
+ @dataclass(frozen=True)
126
+ class Region:
127
+ """A closed area of one material."""
128
+
129
+ name: str # unique within a geometry, e.g. "tooth_3"
130
+ kind: str # "steel", "air", "coil" or "magnet"
131
+ role: str # what it is in the machine, e.g. "tooth" or "rotor_yoke"
132
+ material: str # grade name, or "air"
133
+ boundary: tuple[Edge, ...] # one closed loop, counter-clockwise, no holes
134
+ magnetisation: Magnetisation | None = None
135
+ coil_side: CoilSide | None = None
136
+
137
+ def area(self) -> float:
138
+ """Exact enclosed area in square metres.
139
+
140
+ Shoelace formula on the vertices, plus for each arc the sliver between
141
+ the arc and its chord, r^2 (t - sin t) / 2 for a sweep t. An arc that
142
+ turns the same way as the loop bulges outwards and adds area.
143
+ """
144
+ total = 0.0
145
+ for edge in self.boundary:
146
+ (x0, y0), (x1, y1) = edge.start, edge.end
147
+ total += 0.5 * (x0 * y1 - x1 * y0)
148
+ if edge.centre is not None:
149
+ sweep = edge.sweep
150
+ sliver = 0.5 * edge.radius**2 * (sweep - math.sin(sweep))
151
+ total += sliver if edge.ccw else -sliver
152
+ return total
153
+
154
+ def polygon(self, tolerance: float = 1e-8) -> np.ndarray:
155
+ """The outline as an (n, 2) array of points, arcs cut into short chords."""
156
+ points = [p for edge in self.boundary for p in edge.points(tolerance)]
157
+ return np.array(points)
158
+
159
+ def rotated(self, angle: float) -> Region:
160
+ """The same region turned about the origin."""
161
+ magnetisation = self.magnetisation
162
+ if magnetisation is not None:
163
+ magnetisation = replace(
164
+ magnetisation, axis_angle=magnetisation.axis_angle + angle
165
+ )
166
+ return replace(
167
+ self,
168
+ boundary=tuple(edge.rotated(angle) for edge in self.boundary),
169
+ magnetisation=magnetisation,
170
+ )
171
+
172
+
173
+ def closed_loop(corners: Sequence[tuple[float, float, str]]) -> tuple[Edge, ...]:
174
+ """Build a boundary from corners given as (radius, angle, edge to the next).
175
+
176
+ The edge to the next corner is "line", or "ccw" or "cw" for an arc about
177
+ the origin in that direction. The last corner joins back to the first.
178
+ Corners that coincide are merged, so a caller may list a corner that only
179
+ exists for some dimensions. A long arc is cut in two at its middle, which
180
+ keeps every arc well under half a turn.
181
+ """
182
+ edges = []
183
+ count = len(corners)
184
+ for i in range(count):
185
+ radius, angle, kind = corners[i]
186
+ next_radius, next_angle, _ = corners[(i + 1) % count]
187
+ if kind not in ("line", "ccw", "cw"):
188
+ raise ValueError(f"edge must be 'line', 'ccw' or 'cw', got {kind!r}")
189
+ start, end = polar(radius, angle), polar(next_radius, next_angle)
190
+ if math.dist(start, end) < SAME_POINT:
191
+ continue
192
+ if kind == "line":
193
+ edges.append(Edge(start, end))
194
+ continue
195
+ if abs(next_radius - radius) > SAME_POINT:
196
+ raise ValueError(
197
+ f"an arc about the origin cannot join radius {radius} to {next_radius}"
198
+ )
199
+ ccw = kind == "ccw"
200
+ turn = (next_angle - angle if ccw else angle - next_angle) % (2 * math.pi)
201
+ if turn > LONGEST_ARC:
202
+ middle = polar(radius, angle + (turn if ccw else -turn) / 2)
203
+ edges.append(Edge(start, middle, centre=(0.0, 0.0), ccw=ccw))
204
+ edges.append(Edge(middle, end, centre=(0.0, 0.0), ccw=ccw))
205
+ else:
206
+ edges.append(Edge(start, end, centre=(0.0, 0.0), ccw=ccw))
207
+ return tuple(edges)
208
+
209
+
210
+ def ring_sector(
211
+ inner_radius: float,
212
+ outer_radius: float,
213
+ start_angle: float,
214
+ end_angle: float,
215
+ inner_breaks: Sequence[float] = (),
216
+ outer_breaks: Sequence[float] = (),
217
+ ) -> tuple[Edge, ...]:
218
+ """Boundary of the part of a ring between two angles.
219
+
220
+ ``inner_breaks`` and ``outer_breaks`` are angles at which the inner and
221
+ outer arcs get an extra vertex. A neighbouring region that has a corner on
222
+ one of these arcs needs the arc split there, so that the two regions share
223
+ whole edges.
224
+ """
225
+ corners = [(inner_radius, start_angle, "line"), (outer_radius, start_angle, "ccw")]
226
+ corners += [(outer_radius, angle, "ccw") for angle in sorted(outer_breaks)]
227
+ corners += [(outer_radius, end_angle, "line"), (inner_radius, end_angle, "cw")]
228
+ corners += [(inner_radius, angle, "cw") for angle in sorted(inner_breaks, reverse=True)]
229
+ return closed_loop(corners)
230
+
231
+
232
+ @dataclass(frozen=True)
233
+ class Geometry:
234
+ """A machine cross-section, or the slice of it that repeats.
235
+
236
+ The stator and the rotor are each described in their own frame, so the
237
+ rotor regions never change as it turns. They are joined by a band of air
238
+ between two circles, which is not a region: it is the layer that is
239
+ reconnected when the rotor moves.
240
+
241
+ The stator regions lie between the stator's own surface and the band, the
242
+ rotor regions between the band and the rotor's own surface. Stator and
243
+ rotor cover the same angle, each starting from its own start angle. In an
244
+ antiperiodic slice the field and currents of the next slice are these
245
+ with the opposite sign.
246
+
247
+ The model ends at the inner and outer radius: no air is modelled beyond
248
+ the iron there, which assumes the yokes are not saturated enough to leak.
249
+ """
250
+
251
+ stator: tuple[Region, ...]
252
+ rotor: tuple[Region, ...] # at rotor angle 0
253
+ inner_radius: float
254
+ outer_radius: float
255
+ band_inner_radius: float
256
+ band_outer_radius: float
257
+ stator_start_angle: float
258
+ rotor_start_angle: float
259
+ span_angle: float # angle the slice covers; 2 pi for a full machine
260
+ antiperiodic: bool
261
+ stack_length: float # along the shaft
262
+
263
+ @property
264
+ def regions(self) -> tuple[Region, ...]:
265
+ """Stator regions followed by rotor regions."""
266
+ return self.stator + self.rotor
267
+
268
+ def region(self, name: str) -> Region:
269
+ """Look a region up by name. Raises KeyError if there is none."""
270
+ for candidate in self.regions:
271
+ if candidate.name == name:
272
+ return candidate
273
+ raise KeyError(name)
274
+
275
+ def band_area(self) -> float:
276
+ """Area of the band between its two circles, in square metres."""
277
+ return 0.5 * self.span_angle * (self.band_outer_radius**2 - self.band_inner_radius**2)
278
+
279
+ def area(self) -> float:
280
+ """Area of the whole slice, from the inner radius to the outer radius."""
281
+ return 0.5 * self.span_angle * (self.outer_radius**2 - self.inner_radius**2)