mphkit 0.1.0__py3-none-any.whl

mphkit/_expr.py

@@ -0,0 +1,37 @@
+"""Conversion of Python values to COMSOL expression strings."""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from numbers import Real
+
+Expr = str | Real
+Vector = Sequence[Expr]
+
+
+def expr(value: Expr) -> str:
+    """Return `value` as a COMSOL expression string.
+
+    Numbers are written in plain form (interpreted in the geometry's length
+    unit); strings are passed through, so `'5[mm]'` or `'r0/2'` work as-is.
+    """
+    if isinstance(value, bool):
+        raise TypeError(f'Expected a number or expression, got {value!r}.')
+    if isinstance(value, str):
+        return value
+    if isinstance(value, Real):
+        return repr(float(value)) if not float(value).is_integer() else str(int(value))
+    raise TypeError(f'Expected a number or expression, got {value!r}.')
+
+
+def vector(values: Vector, length: int | None = None) -> list[str]:
+    """Return a sequence of numbers/expressions as a list of strings.
+
+    MPh casts a list based on its first item, so a mixed list such as
+    `[0, 'x1', 0]` fails there. Converting every item to a string avoids that.
+    """
+    if isinstance(values, str):
+        raise TypeError(f'Expected a sequence, got the string {values!r}.')
+    items = [expr(v) for v in values]
+    if length is not None and len(items) != length:
+        raise ValueError(f'Expected {length} components, got {len(items)}.')
+    return items

mphkit/_measure.py

@@ -0,0 +1,102 @@
+"""
+Measurements of the finished geometry. Public as `mk.measure` and
+`mk.bounding_box`.
+
+Both return plain numbers in the geometry's length unit and leave nothing
+in the model. Curved geometry is measured on a rendering mesh, so volumes,
+areas and lengths of curved entities are approximate (a cylinder about
+0.3 % too small, a sphere 0.3 to 0.6 % depending on the geometry kernel);
+planar geometry is exact.
+"""
+from __future__ import annotations
+
+import numbers
+
+import numpy
+from mph import Node
+
+from . import _comsol
+
+AXES = 'xyz'
+
+
+def _final(geom: Node, entity: str, selection):
+    """
+    Returns a measurement of the finished geometry, or `None` if empty.
+
+    `selection` is an entity number, a list of numbers, a selection node at
+    the level of `entity`, or `None` for all entities of that level.
+    """
+    _comsol.check_built(geom)
+    dim = _comsol.entity_dim(geom, entity)
+    count = _comsol.entity_count(geom, dim)
+    if selection is None:
+        found = list(range(1, count + 1))
+    elif isinstance(selection, Node):
+        java = _comsol.check_selection(geom, selection)
+        level = [int(d) for d in java.dimension()]
+        if level != [dim]:
+            raise ValueError(f'Selection "{selection}" is not a {entity} '
+                             'selection.')
+        found = [int(e) for e in java.entities()]
+    else:
+        items = selection if isinstance(
+            selection, (list, tuple, numpy.ndarray)) else [selection]
+        found = []
+        for item in items:
+            if isinstance(item, bool) or not isinstance(item, numbers.Integral):
+                raise TypeError(f'Expected entity numbers, a selection node '
+                                f'or None, not {selection!r}.')
+            found.append(int(item))
+        wrong = [n for n in found if not 1 <= n <= count]
+        if wrong:
+            raise ValueError(f'No {entity} {wrong} in geometry "{geom}"; it '
+                             f'has {count} {entity} entities.')
+    if not found:
+        return None
+    measurement = geom.java.measureFinal()
+    measurement.selection().geom(geom.tag(), dim)
+    measurement.selection().set(found)
+    return measurement
+
+
+def measure(geom: Node, entity: str, /, selection=None) -> float:
+    """
+    Returns the size of entities: volume, area or length.
+
+    What is measured follows the level of `entity`: the volume of domains
+    (the area of 2D domains), the area of boundaries, the length of edges.
+    `selection` is an entity number, a list of them, a selection node, or
+    `None` for all entities of that kind. Several entities give the sum; a
+    number given twice counts once. An empty selection gives 0.
+
+    The geometry must be built. Curved entities are measured on a
+    rendering mesh and are approximate (a cylinder about 0.3 % too small);
+    planar ones are exact.
+    """
+    _comsol.check_not_workplane(geom, 'measure')
+    if _comsol.entity_dim(geom, entity) == 0:
+        raise ValueError('Points have no size; use bounding_box() for their '
+                         'coordinates.')
+    measurement = _final(geom, entity, selection)
+    return 0.0 if measurement is None else float(measurement.getVolume())
+
+
+def bounding_box(geom: Node, entity: str, /, selection=None) -> dict | None:
+    """
+    Returns the bounding box of entities as `{'x': (min, max), ...}`.
+
+    Has one pair per space dimension, so it can be passed on as
+    `sel.box(geom, entity, **box)`. Allow a margin then: the values may
+    carry single-precision noise, which makes `condition='inside'` miss
+    the entity itself. For a single point, min equals max: its
+    coordinates. `selection` works as in `measure()`. Returns `None` for
+    an empty selection.
+    """
+    _comsol.check_not_workplane(geom, 'bounding_box')
+    measurement = _final(geom, entity, selection)
+    if measurement is None:
+        return None
+    values = [float(v) for v in measurement.getBoundingBox()]
+    return {axis: (values[2*i], values[2*i + 1])
+            for i, axis in enumerate(AXES[:len(values) // 2])}

mphkit/_props.py

@@ -0,0 +1,62 @@
+"""
+Setting properties of any COMSOL object. Public as `mk.set`.
+
+Calling a Java `set()` directly fails for plain Python ints ("Ambiguous
+overloads"), numpy arrays and lists that mix numbers and expressions;
+`mk.set` converts them the same way the other helpers do.
+"""
+from __future__ import annotations
+
+from mph import Node
+from mph.node import join
+
+from . import _comsol
+from ._comsol import WorkPlaneNode
+
+
+def set_(target, /, **properties):
+    """
+    Sets properties of an MPh node or a Java object, and returns it.
+
+    For example on a mesh size feature,
+    `mk.set(size, custom=True, hmax='L/10', hgrad=1.45)`. The target may be
+    any MPh node, or a Java object MPh does not reach, such as a probe, a
+    material function or `physics.java.prop('ShapeProperty')`. Keyword
+    arguments are COMSOL property names, set in the given order (e.g.
+    `custom` before `hmax`); `None` values are skipped.
+
+    Ints, numpy arrays and lists mixing numbers and expressions are
+    converted for COMSOL; lists of numbers become string arrays. Unknown
+    names raise `ValueError` with a suggestion, invalid choices list the
+    allowed values. If one property fails, the ones before it stay set.
+
+    A geometry feature node also takes input selections (`input`,
+    `input2`) as in `feature()`; build the geometry again afterwards. To
+    turn on a result selection use `sel.result()` rather than `selresult`,
+    because it checks for label clashes. On variables
+    (`component.variable()`) any value is taken as an expression, and
+    `True` becomes 1.
+    """
+    owner = container = None
+    if isinstance(target, Node):
+        if (len(target.path) >= 4 and target.path[0] == 'geometries'
+                and not isinstance(target, WorkPlaneNode)):
+            # A plain node cannot resolve features inside a work plane.
+            target = WorkPlaneNode(target.model, join(target.path))
+        java = target.java_if_exists()
+        if len(target.path) >= 3 and target.path[0] == 'geometries':
+            owner = target.parent()
+            container = _comsol.feature_container(owner)
+    elif hasattr(target, 'set'):
+        java = target
+        for key, value in properties.items():
+            if value is not None and _comsol.is_selection_input(java, key):
+                raise TypeError(
+                    f'"{key}" is an input selection; use '
+                    f'java.selection("{key}"), or pass a geometry feature '
+                    'as an MPh node.')
+    else:
+        raise TypeError(f'Cannot set properties of {target!r}; expected an '
+                        'MPh node or a COMSOL Java object.')
+    _comsol.set_properties(java, properties, owner, container)
+    return target