mphkit 0.1.0__tar.gz → 0.2.0__tar.gz

{mphkit-0.1.0 → mphkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mphkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Helpers on top of MPh for building COMSOL geometries and geometry-based selections in Python.
 Keywords: comsol,mph,multiphysics,geometry,selection,simulation,fem
 Author: elgar328
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Physics
 Classifier: Typing :: Typed
@@ -30,14 +31,19 @@ Description-Content-Type: text/markdown
 
 # mphkit
 
+[![PyPI](https://img.shields.io/pypi/v/mphkit)](https://pypi.org/project/mphkit/)
+[![Python](https://img.shields.io/python/required-version-toml?tomlFilePath=https://raw.githubusercontent.com/elgar328/mphkit/main/pyproject.toml)](https://pypi.org/project/mphkit/)
+[![License](https://img.shields.io/pypi/l/mphkit)](https://github.com/elgar328/mphkit/blob/main/LICENSE)
+[![COMSOL](https://img.shields.io/badge/COMSOL-6.4-blue)](https://www.comsol.com/)
+
 Helpers on top of [MPh](https://github.com/MPh-py/MPh) for building COMSOL
 geometries and geometry-based selections in Python. Select boundaries by
 location instead of by entity number, so selections keep working when the
 geometry changes.
 
 > [!WARNING]
-> **Early stage.** mphkit is at an early stage of development. The API may
-> change at any time, without deprecation warnings.
+> **Early stage.** The API may change at any time, without deprecation
+> warnings.
 
 Not affiliated with COMSOL AB.
 
@@ -60,13 +66,18 @@ bottom = mk.sel.box(geom, 'boundary', z=0)     # faces on the plane z = 0
 
 # plain MPh from here on
 physics = (model/'physics').create('HeatTransfer', geom)
-physics.create('TemperatureBoundary', 2).select(bottom)
+physics.create('TemperatureBoundary', 2).select(bottom)  # 2: boundaries in 3D
 model.save('demo.mph')
 ```
 
-Every helper takes MPh `Node`s, and those that create something return
-one, so mphkit and MPh mix freely. Physics, mesh, study and results stay
-plain MPh (or the COMSOL Java API through `node.java`).
+Helpers take MPh `Node`s (`mk.geometry` the model, `mk.set` also Java
+objects), and those that create something return one, so mphkit and MPh
+mix freely. Physics, mesh, study and results stay plain MPh (or the
+COMSOL Java API through `node.java`).
+
+`help(mphkit)` sums up the workflow, the rules and the common pitfalls,
+and each helper has its own `help()`. Point an AI assistant to
+`help(mphkit)` first.
 
 ## Requirements
 
@@ -77,10 +88,10 @@ plain MPh (or the COMSOL Java API through `node.java`).
   for CAD import (CAD Import Module, Design Module or a LiveLink).
   Everything else needs COMSOL only.
 
-Tested with COMSOL 6.4 and MPh 1.4.0, on macOS (Apple silicon) with
-Python 3.10 and 3.13 and on Windows with Python 3.13. Linux is not tested
-yet; since mphkit only goes through MPh, it is expected to work the same
-way.
+mphkit is developed and tested with COMSOL 6.4 and MPh 1.4. Feature types,
+property names and selection behavior can differ between COMSOL versions,
+so other versions may need adjustments; reports are welcome. Checked on
+macOS and Windows; it should run wherever MPh runs.
 
 ## Installation
 
@@ -102,7 +113,7 @@ mk.block(geom, (10, 10, 5)); mk.cylinder(geom, r, h, pos); mk.sphere(geom, r)
 mk.union(geom, [a, b]); mk.difference(geom, a, [b]); mk.intersection(geom, [a, b])
 mk.move(geom, part, (10, 0, 0)); mk.rotate(geom, part, 90, axis='z')
 mk.mirror(geom, part, (1, 0, 0)); mk.array(geom, part, size=(5, 5, 1), displ=(10, 10, 0))
-mk.fillet(geom, block, 0.5); mk.chamfer(geom, block, 0.5)   # all edges, or a selection
+mk.fillet(geom, part, 0.5); mk.chamfer(geom, part, 0.5)     # all edges, or a selection
 mk.partition(geom, part, tool); mk.delete(geom, part)
 plane = mk.workplane(geom, quickz=0)
 mk.circle(plane, 2); mk.extrude(geom, plane, 5); mk.revolve(geom, plane)
@@ -125,16 +136,27 @@ mk.cylinder(geom, 1, 5, pos, contributeto=holes)  # collect from several feature
 `where='geometry'` makes a selection inside the geometry sequence instead,
 for use as input of a later operation, e.g. `mk.sel.box(geom, 'object',
 x=(20, 40), where='geometry')` to pick whole objects for `mk.delete`. In a
-work plane, selections pick single corners or edges:
-`mk.fillet(plane, mk.sel.box(plane, 'point', x=1, y=1), 0.3)`.
+work plane, selections can pick single corners or edges, e.g. to fillet
+one corner: `mk.fillet(plane, mk.sel.box(plane, 'point', x=1, y=1), 0.3)`.
 
-Queries return plain Python values and leave nothing in the model:
+Queries on the plate from the Example section return plain Python values
+and leave nothing in the model:
 
 ```python
 mk.sel.entities(geom, bottom)            # [3]
-mk.sel.find(geom, 'domain', x=(0, 10))   # entity numbers inside a box
-mk.measure(geom, 'domain')               # volume (area, length for other levels)
-mk.bounding_box(geom, 'boundary', 3)     # {'x': (0, 10), 'y': ..., 'z': ...}
+mk.sel.find(geom, 'boundary', x=0)       # [1]: the face at x = 0
+mk.measure(geom, 'domain')               # 99216.5: volume, approximate where curved
+mk.bounding_box(geom, 'boundary', 3)     # {'x': (0.0, 100.0), 'y': ..., 'z': (0.0, 0.0)}
+mk.summary(geom)                         # counts, voids, bounding box, unit
+mk.sel.neighbors(geom, 'domain', boundary=3)  # [1]: the domain beside it
+mk.coordinates(geom, 'boundary', 3)      # {1: (0.0, 0.0, 0.0), 3: (0.0, 100.0, 0.0), ...}
+```
+
+Pictures, written to a file:
+
+```python
+mk.image(geom, 'geom.png')                              # the geometry
+mk.image(geom, 'selection.png', selection, labels=True) # with numbers
 ```
 
 And a few helpers outside geometry:
@@ -144,21 +166,18 @@ mk.coordinate_system(geom, 'PML', selection=layer)   # e.g. perfectly matched la
 mk.set(mesh_size, hmax=0.5, hgrad=2)   # any node or Java object; converts ints and lists
 ```
 
-Arguments are COMSOL property names, so the COMSOL documentation of each
-feature applies. The docstrings describe each helper in detail.
-
 [`examples/plate_with_holes.py`](https://github.com/elgar328/mphkit/blob/main/examples/plate_with_holes.py)
 is a complete script, from geometry to solved results: heat conduction in
-a plate with a row of cooling holes, for any number of holes.
+a plate with a row of cooling holes, for one or more holes.
 
 ## Limitations
 
-- mphkit covers geometry and selections only. Physics, mesh, studies and
+- mphkit covers geometry and selections. Physics, mesh, studies and
   results are left to MPh.
 - No named helpers yet for geometry parts (`PartInstance`), sweeps, cones
   and the other remaining primitives, virtual operations or repair. They
-  work through `mk.feature(geom, 'Sweep', ...)` with the same conversions
-  and input handling.
+  work through `mk.feature(geom, 'Sweep', ...)`, which handles arguments
+  like the named helpers (expressions, lists, nodes as inputs).
 
 ## Development
 

{mphkit-0.1.0 → mphkit-0.2.0}/README.md

@@ -1,13 +1,18 @@
 # mphkit
 
+[![PyPI](https://img.shields.io/pypi/v/mphkit)](https://pypi.org/project/mphkit/)
+[![Python](https://img.shields.io/python/required-version-toml?tomlFilePath=https://raw.githubusercontent.com/elgar328/mphkit/main/pyproject.toml)](https://pypi.org/project/mphkit/)
+[![License](https://img.shields.io/pypi/l/mphkit)](https://github.com/elgar328/mphkit/blob/main/LICENSE)
+[![COMSOL](https://img.shields.io/badge/COMSOL-6.4-blue)](https://www.comsol.com/)
+
 Helpers on top of [MPh](https://github.com/MPh-py/MPh) for building COMSOL
 geometries and geometry-based selections in Python. Select boundaries by
 location instead of by entity number, so selections keep working when the
 geometry changes.
 
 > [!WARNING]
-> **Early stage.** mphkit is at an early stage of development. The API may
-> change at any time, without deprecation warnings.
+> **Early stage.** The API may change at any time, without deprecation
+> warnings.
 
 Not affiliated with COMSOL AB.
 
@@ -30,13 +35,18 @@ bottom = mk.sel.box(geom, 'boundary', z=0)     # faces on the plane z = 0
 
 # plain MPh from here on
 physics = (model/'physics').create('HeatTransfer', geom)
-physics.create('TemperatureBoundary', 2).select(bottom)
+physics.create('TemperatureBoundary', 2).select(bottom)  # 2: boundaries in 3D
 model.save('demo.mph')
 ```
 
-Every helper takes MPh `Node`s, and those that create something return
-one, so mphkit and MPh mix freely. Physics, mesh, study and results stay
-plain MPh (or the COMSOL Java API through `node.java`).
+Helpers take MPh `Node`s (`mk.geometry` the model, `mk.set` also Java
+objects), and those that create something return one, so mphkit and MPh
+mix freely. Physics, mesh, study and results stay plain MPh (or the
+COMSOL Java API through `node.java`).
+
+`help(mphkit)` sums up the workflow, the rules and the common pitfalls,
+and each helper has its own `help()`. Point an AI assistant to
+`help(mphkit)` first.
 
 ## Requirements
 
@@ -47,10 +57,10 @@ plain MPh (or the COMSOL Java API through `node.java`).
   for CAD import (CAD Import Module, Design Module or a LiveLink).
   Everything else needs COMSOL only.
 
-Tested with COMSOL 6.4 and MPh 1.4.0, on macOS (Apple silicon) with
-Python 3.10 and 3.13 and on Windows with Python 3.13. Linux is not tested
-yet; since mphkit only goes through MPh, it is expected to work the same
-way.
+mphkit is developed and tested with COMSOL 6.4 and MPh 1.4. Feature types,
+property names and selection behavior can differ between COMSOL versions,
+so other versions may need adjustments; reports are welcome. Checked on
+macOS and Windows; it should run wherever MPh runs.
 
 ## Installation
 
@@ -72,7 +82,7 @@ mk.block(geom, (10, 10, 5)); mk.cylinder(geom, r, h, pos); mk.sphere(geom, r)
 mk.union(geom, [a, b]); mk.difference(geom, a, [b]); mk.intersection(geom, [a, b])
 mk.move(geom, part, (10, 0, 0)); mk.rotate(geom, part, 90, axis='z')
 mk.mirror(geom, part, (1, 0, 0)); mk.array(geom, part, size=(5, 5, 1), displ=(10, 10, 0))
-mk.fillet(geom, block, 0.5); mk.chamfer(geom, block, 0.5)   # all edges, or a selection
+mk.fillet(geom, part, 0.5); mk.chamfer(geom, part, 0.5)     # all edges, or a selection
 mk.partition(geom, part, tool); mk.delete(geom, part)
 plane = mk.workplane(geom, quickz=0)
 mk.circle(plane, 2); mk.extrude(geom, plane, 5); mk.revolve(geom, plane)
@@ -95,16 +105,27 @@ mk.cylinder(geom, 1, 5, pos, contributeto=holes)  # collect from several feature
 `where='geometry'` makes a selection inside the geometry sequence instead,
 for use as input of a later operation, e.g. `mk.sel.box(geom, 'object',
 x=(20, 40), where='geometry')` to pick whole objects for `mk.delete`. In a
-work plane, selections pick single corners or edges:
-`mk.fillet(plane, mk.sel.box(plane, 'point', x=1, y=1), 0.3)`.
+work plane, selections can pick single corners or edges, e.g. to fillet
+one corner: `mk.fillet(plane, mk.sel.box(plane, 'point', x=1, y=1), 0.3)`.
 
-Queries return plain Python values and leave nothing in the model:
+Queries on the plate from the Example section return plain Python values
+and leave nothing in the model:
 
 ```python
 mk.sel.entities(geom, bottom)            # [3]
-mk.sel.find(geom, 'domain', x=(0, 10))   # entity numbers inside a box
-mk.measure(geom, 'domain')               # volume (area, length for other levels)
-mk.bounding_box(geom, 'boundary', 3)     # {'x': (0, 10), 'y': ..., 'z': ...}
+mk.sel.find(geom, 'boundary', x=0)       # [1]: the face at x = 0
+mk.measure(geom, 'domain')               # 99216.5: volume, approximate where curved
+mk.bounding_box(geom, 'boundary', 3)     # {'x': (0.0, 100.0), 'y': ..., 'z': (0.0, 0.0)}
+mk.summary(geom)                         # counts, voids, bounding box, unit
+mk.sel.neighbors(geom, 'domain', boundary=3)  # [1]: the domain beside it
+mk.coordinates(geom, 'boundary', 3)      # {1: (0.0, 0.0, 0.0), 3: (0.0, 100.0, 0.0), ...}
+```
+
+Pictures, written to a file:
+
+```python
+mk.image(geom, 'geom.png')                              # the geometry
+mk.image(geom, 'selection.png', selection, labels=True) # with numbers
 ```
 
 And a few helpers outside geometry:
@@ -114,21 +135,18 @@ mk.coordinate_system(geom, 'PML', selection=layer)   # e.g. perfectly matched la
 mk.set(mesh_size, hmax=0.5, hgrad=2)   # any node or Java object; converts ints and lists
 ```
 
-Arguments are COMSOL property names, so the COMSOL documentation of each
-feature applies. The docstrings describe each helper in detail.
-
 [`examples/plate_with_holes.py`](https://github.com/elgar328/mphkit/blob/main/examples/plate_with_holes.py)
 is a complete script, from geometry to solved results: heat conduction in
-a plate with a row of cooling holes, for any number of holes.
+a plate with a row of cooling holes, for one or more holes.
 
 ## Limitations
 
-- mphkit covers geometry and selections only. Physics, mesh, studies and
+- mphkit covers geometry and selections. Physics, mesh, studies and
   results are left to MPh.
 - No named helpers yet for geometry parts (`PartInstance`), sweeps, cones
   and the other remaining primitives, virtual operations or repair. They
-  work through `mk.feature(geom, 'Sweep', ...)` with the same conversions
-  and input handling.
+  work through `mk.feature(geom, 'Sweep', ...)`, which handles arguments
+  like the named helpers (expressions, lists, nodes as inputs).
 
 ## Development
 

{mphkit-0.1.0 → mphkit-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mphkit"
-version = "0.1.0"
+version = "0.2.0"
 description = "Helpers on top of MPh for building COMSOL geometries and geometry-based selections in Python."
 readme = "README.md"
 license = "MIT"
@@ -30,6 +30,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering",
     "Topic :: Scientific/Engineering :: Physics",
     "Typing :: Typed",
@@ -45,7 +46,10 @@ Changelog = "https://github.com/elgar328/mphkit/blob/main/CHANGELOG.md"
 Issues = "https://github.com/elgar328/mphkit/issues"
 
 [dependency-groups]
-dev = ["pytest>=8"]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=8",
+]
 
 [build-system]
 requires = ["uv_build>=0.9.9,<0.13"]

{mphkit-0.1.0 → mphkit-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "mphkit"
-version = "0.1.0"
+version = "0.2.0"
 description = "Helpers on top of MPh for building COMSOL geometries and geometry-based selections in Python."
 readme = "README.md"
 authors = [{ name = "elgar328" }]
@@ -21,6 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering",
     "Topic :: Scientific/Engineering :: Physics",
     "Typing :: Typed",
@@ -33,7 +34,10 @@ Changelog = "https://github.com/elgar328/mphkit/blob/main/CHANGELOG.md"
 Issues = "https://github.com/elgar328/mphkit/issues"
 
 [dependency-groups]
-dev = ["pytest>=8"]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=8",
+]
 
 [build-system]
 requires = ["uv_build>=0.9.9,<0.13"]

mphkit-0.2.0/src/mphkit/__init__.py

@@ -0,0 +1,117 @@
+"""
+Helpers on top of MPh for building COMSOL geometries and selections.
+
+mphkit builds geometry and named selections; physics, mesh, studies and
+results stay plain MPh (or the COMSOL Java API through `node.java`).
+Helpers take MPh nodes (`mk.geometry` the model, `mk.set` also Java
+objects), and those that create something return one.
+
+    import mph
+    import mphkit as mk
+
+    client = mph.start()
+    model = client.create('demo')
+    geom = mk.geometry(model, 3, length_unit='mm')
+    plate = mk.block(geom, (100, 100, 10))
+    hole = mk.cylinder(geom, 5, 10, (50, 50, 0))
+    mk.difference(geom, plate, [hole])
+    model.build(geom)
+    bottom = mk.sel.box(geom, 'boundary', z=0)    # select by location
+    physics = (model/'physics').create('HeatTransfer', geom)
+    # 2: boundaries in 3D
+    physics.create('TemperatureBoundary', 2).select(bottom)
+
+Rules:
+
+- Select entities by location with `mk.sel` (box, ball, cylinder, disk,
+  adjacent, set operations), never by entity number: numbers change with
+  the geometry, selections are re-evaluated by COMSOL.
+- Besides locations, `mk.sel.result` selects what a feature left in the
+  geometry and `mk.sel.cumulative` collects groups across operations
+  (features join with `contributeto=`).
+- Entity kinds are COMSOL's: 'domain' (volumes in 3D, areas in 2D),
+  'boundary' (faces in 3D, edges in 2D, where 'edge' means the same),
+  'edge', 'point' (vertices). Physics features take the level as a
+  number: 3 for domains and 2 for boundaries in 3D, 2 and 1 in 2D.
+- Objects that touch or overlap stay separate domains, even after
+  `mk.union`; merge them with `mk.union(geom, [a, b], intbnd=False)`,
+  which also removes layers and partition cuts of its inputs. A full
+  `mk.revolve` (no `angle`) keeps its cross-section as an interior face
+  unless `origfaces=False`.
+- Extra keyword arguments are COMSOL property names (`intbnd`, `keep`,
+  `layername`, `base`, ...); an unknown name raises an error that often
+  suggests the right one.
+- Sizes, positions, angles and counts may be numbers or COMSOL expressions
+  with parameters and units, e.g. `'L-2*t'` or `'5[mm]'`; define
+  parameters with `model.parameter('t', '0.3[mm]')`.
+- Sizes and coordinates are in the geometry's length unit.
+- Build the geometry (`model.build(geom)`) before querying it, and again
+  after adding a `where='geometry'` selection.
+
+Check the result from code:
+
+- `mk.sel.entities(geom, selection)`: entity numbers of a selection
+- `mk.sel.find(geom, 'domain', x=...)`: entity numbers inside a box
+- `mk.measure(geom, 'domain')`: volume, area or length
+- `mk.bounding_box(geom, 'boundary', 3)`: extents
+- `mk.summary(geom)`: counts, voids, size
+- `mk.sel.neighbors(geom, 'domain', boundary=3)`: adjacent entities
+- `mk.coordinates(geom, 'boundary', 3)`: vertex coordinates
+- `mk.image(geom, 'geom.png')`: a picture of the geometry
+- `mk.image(geom, 'selection.png', selection, labels=True)`: a selection
+  highlighted, with entity numbers
+
+Curved entities are measured approximately (see `help(mk.measure)`).
+`mk.measure` and `mk.bounding_box` use single precision, about seven
+digits of the coordinates (`mk.bounding_box` of points excepted);
+`mk.coordinates` and `mk.summary` use double precision. Compare with a
+tolerance either way.
+
+Selection tips: `mk.sel.result(geom, feature, 'boundary')` gives the faces
+that an object and its copies leave in the geometry, curved ones
+included, and the faces it cuts into other objects, e.g. the spherical
+faces a subtracted sphere leaves in a block. Curved surfaces are split
+into several faces: the side of a cylinder or cone, the wall of a hole or
+of an extruded circle into four, a sphere into eight. For the side of a
+cylinder that no other object cut, use a thin shell:
+`mk.sel.cylinder(geom, 'boundary', pos, r, rin=0.99*r, bottom=0, top=h,
+name='side')` (`rin` needs about 1 % room, see
+`help(mk.sel.cylinder)`; a name avoids a clash with the cylinder's own
+label).
+
+More: `help(mk.sel)` for selections (also in work planes), `help(mk.block)`
+etc. for each helper, `mk.feature(geom, 'Type', ...)` for any other
+geometry feature, `mk.set(node_or_java, **properties)` to set properties
+of anything else (mesh, study, material, probe), and `node.java` for the
+rest of the COMSOL API.
+"""
+import sys as _sys
+
+from . import sel
+from ._hints import HintModule as _HintModule
+from ._image import image
+from ._measure import bounding_box, coordinates, measure, summary
+from ._props import set_ as set  # not in __all__: keeps builtin set
+from .errors import LicenseError
+from .geometry import (array, block, chamfer, circle, component_of,
+                       coordinate_system, cylinder, delete, difference,
+                       extrude, feature, fillet, geometry, import_,
+                       intersection, interval, line_segment, mirror, move,
+                       partition, point, polygon, rectangle, revolve,
+                       rigid_transform, rotate, sphere, square, union,
+                       workplane)
+
+__version__ = '0.2.0'
+
+__all__ = ['LicenseError', 'array', 'block', 'bounding_box', 'chamfer',
+           'circle', 'component_of', 'coordinate_system', 'coordinates',
+           'cylinder', 'delete', 'difference', 'extrude', 'feature',
+           'fillet', 'geometry', 'image', 'import_', 'intersection',
+           'interval', 'line_segment', 'measure', 'mirror', 'move',
+           'partition', 'point', 'polygon', 'rectangle', 'revolve',
+           'rigid_transform', 'rotate', 'sel', 'sphere', 'square', 'summary',
+           'union', 'workplane']
+
+# Unknown names raise errors that name the right helper (see _hints).
+_sys.modules[__name__].__class__ = _HintModule
+del _sys, _HintModule