Mesh API

The reference uses implementation paths where necessary for static documentation, but the documented primitives and operations are exported from the top-level nmesh package. For example, use nmesh.Box, not an internal module import.

Loading and construction

Mesh region IDs may be arbitrary positive integers. When loading a simulation, materials are assigned to the distinct IDs in ascending order.

load

load(filename: str | Path, reorder: bool = False, distribute: bool = True) -> MeshFromFile

Load legacy Nmesh or a Meshio-supported mesh file.

Parameters:

Name	Type	Description	Default
filename	str | Path	Source mesh path.	required
reorder	bool	Request unsupported legacy node reordering.	False
distribute	bool	Keep true; manual distribution is unsupported.	True

Returns:

Type	Description
MeshFromFile	Mesh wrapper containing points, simplices, regions, and topology.

Raises:

Type	Description
FileNotFoundError	If filename does not exist.
ValueError	If the mesh layout or supported cells are invalid.
NotImplementedError	If reordering or manual distribution is requested.

mesh_from_points_and_simplices

mesh_from_points_and_simplices(points: Sequence[Sequence[float]] | None = None, simplices_indices: Sequence[Sequence[int]] | None = None, simplices_regions: Sequence[int] | None = None, periodic_point_indices: Sequence[Sequence[int]] | None = None, initial: int = 0, do_reorder: bool = False, do_distribute: bool = True)

Construct a mesh from explicit points, simplex indices, and regions.

Parameters:

Name	Type	Description	Default
points	Sequence[Sequence[float]] | None	Coordinate vectors with a consistent dimension.	None
simplices_indices	Sequence[Sequence[int]] | None	Point-index vectors defining simplex cells.	None
simplices_regions	Sequence[int] | None	Positive region ID for every simplex.	None
periodic_point_indices	Sequence[Sequence[int]] | None	Optional groups of equivalent periodic points. The micromagnetic simulation does not currently support periodic boundary physics.	None
initial	int	Use 1 to convert one-based simplex indices to zero-based.	0
do_reorder	bool	Request unsupported legacy node reordering.	False
do_distribute	bool	Keep true; manual distribution is unsupported.	True

Raises:

Type	Description
ValueError	If points, simplices, regions, or indices are inconsistent.
NotImplementedError	If reordering or manual distribution is requested.

points property

points: list[Point]

Return node coordinates.

simplices property

simplices: list[Simplex]

Return point indices for every simplex cell.

regions property

regions: list[int]

Return the region ID for every simplex cell.

dim property

dim: int

Return the mesh coordinate dimension.

surfaces property

surfaces: list[list[int]]

Return point indices for detected boundary simplices.

point_regions property

point_regions: list[list[int]]

Return incident region IDs for each point.

links property

links: list[tuple[int, int]]

Return unique mesh edges as point-index pairs.

region_volumes property

region_volumes: list[float]

Return geometric volume for each region.

num_regions property

num_regions: int

Return the number of mesh regions.

periodic_point_indices property

periodic_point_indices: list[list[int]]

Return groups of equivalent periodic point indices.

permutation property

permutation: list[int]

Return the node permutation mapping.

scale_node_positions

scale_node_positions(scale: float) -> None

Multiply every node coordinate by scale and clear caches.

save

save(filename: str | Path) -> None

Save the mesh using the format selected by the filename suffix.

to_lists

to_lists() -> list[object]

Return the backend's legacy mesh-data list representation.

set_vertex_distribution

set_vertex_distribution(dist: object) -> None

Sets vertex distribution.

save

save(mesh: MeshBase, filename: str | Path) -> None

Save a mesh using the format selected by the destination suffix.

Parameters:

Name	Type	Description	Default
mesh	MeshBase	Mesh to serialize.	required
filename	str | Path	Destination. .h5 selects Nmesh HDF5, .nmesh selects Nmesh ASCII, and other suffixes are delegated to Meshio.	required

Mesh objects

MeshBase

MeshBase(raw_mesh: RawMesh)

Expose mesh geometry and topology through cached Python values.

Attributes:

Name	Type	Description
points	list[Point]	Node coordinates.
simplices	list[Simplex]	Point indices for every simplex cell.
regions	list[int]	Region ID for every simplex.
dim	int	Coordinate dimension.
surfaces	list[list[int]]	Boundary simplex indices.
point_regions	list[list[int]]	Incident region IDs for every point.
links	list[tuple[int, int]]	Unique mesh edges as point-index pairs.
region_volumes	list[float]	Computed volume for each region.

points property

points: list[Point]

Return node coordinates.

simplices property

simplices: list[Simplex]

Return point indices for every simplex cell.

regions property

regions: list[int]

Return the region ID for every simplex cell.

dim property

dim: int

Return the mesh coordinate dimension.

surfaces property

surfaces: list[list[int]]

Return point indices for detected boundary simplices.

point_regions property

point_regions: list[list[int]]

Return incident region IDs for each point.

links property

links: list[tuple[int, int]]

Return unique mesh edges as point-index pairs.

region_volumes property

region_volumes: list[float]

Return geometric volume for each region.

num_regions property

num_regions: int

Return the number of mesh regions.

periodic_point_indices property

periodic_point_indices: list[list[int]]

Return groups of equivalent periodic point indices.

permutation property

permutation: list[int]

Return the node permutation mapping.

scale_node_positions

scale_node_positions(scale: float) -> None

Multiply every node coordinate by scale and clear caches.

save

save(filename: str | Path) -> None

Save the mesh using the format selected by the filename suffix.

to_lists

to_lists() -> list[object]

Return the backend's legacy mesh-data list representation.

Mesh

Mesh(bounding_box: Sequence[Sequence[float]] | None, objects: Sequence[MeshObject] | None = None, a0: float = 1.0, density: str = '', periodic: Sequence[bool] | Sequence[float] | None = None, fixed_points: Sequence[Sequence[float]] | None = None, mobile_points: Sequence[Sequence[float]] | None = None, simply_points: Sequence[Sequence[float]] | None = None, callback: tuple[MeshCallback, int] | None = None, mesh_bounding_box: bool = False, meshing_parameters: MeshingParameters | None = None, cache_name: str = '', hints: Sequence[tuple[MeshBase, MeshObject]] | None = None, **kwargs: Any)

Generate a simplex mesh from implicit geometric objects.

Parameters:

Name	Type	Description	Default
bounding_box	Sequence[Sequence[float]] | None	Lower and upper coordinate corners enclosing the model.	required
objects	Sequence[MeshObject] | None	Geometry primitives or boolean combinations to mesh.	None
a0	float	Target initial point spacing in mesh-coordinate units.	1.0
density	str	Optional legacy density expression.	''
periodic	Sequence[bool] | Sequence[float] | None	Periodic coordinate selectors for bounding-box meshing.	None
fixed_points	Sequence[Sequence[float]] | None	Additional points held fixed during relaxation.	None
mobile_points	Sequence[Sequence[float]] | None	Additional mobile seed points.	None
simply_points	Sequence[Sequence[float]] | None	Additional simple seed points.	None
callback	tuple[MeshCallback, int] | None	Mesher progress callback and interval.	None
mesh_bounding_box	bool	Mesh the complete bounding box when true.	False
meshing_parameters	MeshingParameters | None	Explicit mesher controls.	None
cache_name	str	Optional compatibility cache label.	''
hints	Sequence[tuple[MeshBase, MeshObject]] | None	Mesh/object hint pairs.	None
**kwargs	Any	Named meshing-parameter overrides.	{}

Raises:

Type	Description
ValueError	If the bounding box or object configuration is invalid.

raw_mesh instance-attribute

raw_mesh = raw_mesh

_cache instance-attribute

_cache: dict[str, Any] = {}

points property

points: list[Point]

Return node coordinates.

simplices property

simplices: list[Simplex]

Return point indices for every simplex cell.

regions property

regions: list[int]

Return the region ID for every simplex cell.

dim property

dim: int

Return the mesh coordinate dimension.

surfaces property

surfaces: list[list[int]]

Return point indices for detected boundary simplices.

point_regions property

point_regions: list[list[int]]

Return incident region IDs for each point.

links property

links: list[tuple[int, int]]

Return unique mesh edges as point-index pairs.

region_volumes property

region_volumes: list[float]

Return geometric volume for each region.

num_regions property

num_regions: int

Return the number of mesh regions.

periodic_point_indices property

periodic_point_indices: list[list[int]]

Return groups of equivalent periodic point indices.

permutation property

permutation: list[int]

Return the node permutation mapping.

_cached_backend_value

_cached_backend_value(cache_key: str, getter: Callable[[RawMesh], _T]) -> _T

scale_node_positions

scale_node_positions(scale: float) -> None

Multiply every node coordinate by scale and clear caches.

save

save(filename: str | Path) -> None

Save the mesh using the format selected by the filename suffix.

__str__

__str__() -> str

to_lists

to_lists() -> list[object]

Return the backend's legacy mesh-data list representation.

set_vertex_distribution

set_vertex_distribution(dist: object) -> None

Sets vertex distribution.

Geometry primitives

Box

Box(p1: ArrayLike, p2: ArrayLike, transform: Iterable[TransformationStep] | None = None, fixed: Sequence[Sequence[float]] | None = None, mobile: Sequence[Sequence[float]] | None = None, system_coords: bool = True, use_fixed_corners: bool = False)

Create a box from two opposite corners.

Parameters:

Name	Type	Description	Default
p1	ArrayLike	First corner coordinates.	required
p2	ArrayLike	Opposite corner coordinates.	required
transform	Iterable[TransformationStep] | None	Optional transformation steps applied in order.	None
fixed	Sequence[Sequence[float]] | None	Extra fixed mesher points.	None
mobile	Sequence[Sequence[float]] | None	Extra mobile mesher points.	None
system_coords	bool	Apply transformations in system coordinates when true.	True
use_fixed_corners	bool	Add every box corner as a fixed mesher point.	False

dim instance-attribute

dim = int(dim)

fixed_points instance-attribute

fixed_points = _as_float_points(fixed)

mobile_points instance-attribute

mobile_points = _as_float_points(mobile)

obj instance-attribute

obj = body

_require_body

_require_body() -> Body

signed_distance

signed_distance(points: ArrayLike) -> float | FloatArray

Evaluate the object's scalar field at one point or many points.

contains

contains(points: ArrayLike) -> bool | BoolArray

Return whether the supplied point or points lie inside the object.

shift

shift(vector: ArrayLike, system_coords: bool = True) -> None

Translate the object by the given vector.

scale

scale(factors: ArrayLike) -> None

Scale the object in body coordinates by the supplied per-axis factors.

rotate

rotate(a1: int, a2: int, angle: float, system_coords: bool = True) -> None

Rotate the object in the plane spanned by the two axis indices.

rotate_3d

rotate_3d(axis: ArrayLike, angle: float, system_coords: bool = True) -> None

Rotate a three-dimensional object about the supplied axis vector.

transform

transform(transformations: Iterable[TransformationStep] | None, system_coords: bool = True) -> None

Apply a sequence of named transform tuples in the given order.

Ellipsoid

Ellipsoid(lengths: ArrayLike, transform: Iterable[TransformationStep] | None = None, fixed: Sequence[Sequence[float]] | None = None, mobile: Sequence[Sequence[float]] | None = None, system_coords: bool = True)

Create an axis-aligned ellipsoid from its principal radii.

Parameters:

Name	Type	Description	Default
lengths	ArrayLike	Positive radius along each coordinate axis.	required
transform	Iterable[TransformationStep] | None	Optional transformation steps applied in order.	None
fixed	Sequence[Sequence[float]] | None	Extra fixed mesher points.	None
mobile	Sequence[Sequence[float]] | None	Extra mobile mesher points.	None
system_coords	bool	Apply transformations in system coordinates when true.	True

dim instance-attribute

dim = int(dim)

fixed_points instance-attribute

fixed_points = _as_float_points(fixed)

mobile_points instance-attribute

mobile_points = _as_float_points(mobile)

obj instance-attribute

obj = body

_require_body

_require_body() -> Body

signed_distance

signed_distance(points: ArrayLike) -> float | FloatArray

Evaluate the object's scalar field at one point or many points.

contains

contains(points: ArrayLike) -> bool | BoolArray

Return whether the supplied point or points lie inside the object.

shift

shift(vector: ArrayLike, system_coords: bool = True) -> None

Translate the object by the given vector.

scale

scale(factors: ArrayLike) -> None

Scale the object in body coordinates by the supplied per-axis factors.

rotate

rotate(a1: int, a2: int, angle: float, system_coords: bool = True) -> None

Rotate the object in the plane spanned by the two axis indices.

rotate_3d

rotate_3d(axis: ArrayLike, angle: float, system_coords: bool = True) -> None

Rotate a three-dimensional object about the supplied axis vector.

transform

transform(transformations: Iterable[TransformationStep] | None, system_coords: bool = True) -> None

Apply a sequence of named transform tuples in the given order.

Conic

Conic(c1: ArrayLike, r1: float, c2: ArrayLike, r2: float, transform: Iterable[TransformationStep] | None = None, fixed: Sequence[Sequence[float]] | None = None, mobile: Sequence[Sequence[float]] | None = None, system_coords: bool = True)

Create a conical frustum from two centers and radii.

Parameters:

Name	Type	Description	Default
c1	ArrayLike	First end center.	required
r1	float	Non-negative first-end radius.	required
c2	ArrayLike	Second end center.	required
r2	float	Non-negative second-end radius.	required
transform	Iterable[TransformationStep] | None	Optional transformation steps applied in order.	None
fixed	Sequence[Sequence[float]] | None	Extra fixed mesher points.	None
mobile	Sequence[Sequence[float]] | None	Extra mobile mesher points.	None
system_coords	bool	Apply transformations in system coordinates when true.	True

dim instance-attribute

dim = int(dim)

fixed_points instance-attribute

fixed_points = _as_float_points(fixed)

mobile_points instance-attribute

mobile_points = _as_float_points(mobile)

obj instance-attribute

obj = body

_require_body

_require_body() -> Body

signed_distance

signed_distance(points: ArrayLike) -> float | FloatArray

Evaluate the object's scalar field at one point or many points.

contains

contains(points: ArrayLike) -> bool | BoolArray

Return whether the supplied point or points lie inside the object.

shift

shift(vector: ArrayLike, system_coords: bool = True) -> None

Translate the object by the given vector.

scale

scale(factors: ArrayLike) -> None

Scale the object in body coordinates by the supplied per-axis factors.

rotate

rotate(a1: int, a2: int, angle: float, system_coords: bool = True) -> None

Rotate the object in the plane spanned by the two axis indices.

rotate_3d

rotate_3d(axis: ArrayLike, angle: float, system_coords: bool = True) -> None

Rotate a three-dimensional object about the supplied axis vector.

transform

transform(transformations: Iterable[TransformationStep] | None, system_coords: bool = True) -> None

Apply a sequence of named transform tuples in the given order.

union

union(objects: Sequence[MeshObject]) -> MeshObject

Return a geometry that is inside any supplied object.

Parameters:

Name	Type	Description	Default
objects	Sequence[MeshObject]	At least two objects with the same dimension.	required

Returns:

Type	Description
MeshObject	Combined mesh object.

difference

difference(mother: MeshObject, subtract: Sequence[MeshObject]) -> MeshObject

Carve each subtractor out of a mother object.

Parameters:

Name	Type	Description	Default
mother	MeshObject	Object to retain.	required
subtract	Sequence[MeshObject]	Same-dimensional objects to remove.	required

Returns:

Type	Description
MeshObject	Resulting mesh object.

intersect

intersect(objects: Sequence[MeshObject]) -> MeshObject

Return a geometry that is inside every supplied object.

Parameters:

Name	Type	Description	Default
objects	Sequence[MeshObject]	At least two objects with the same dimension.	required

Returns:

Type	Description
MeshObject	Intersected mesh object.