Microgen modules

Phase module

Phase class: a collection of OCCT solids belonging to the same phase.

The CAD path goes through OCCT directly via OCP (installed as the [cad] extra — cadquery-ocp-novtk); no cadquery anywhere. Shapes are stored as microgen.cad.CadShape and solids as raw OCCT TopoDS_Solid.

class microgen.phase.Phase(shape: ShapeLike | None = None, solids: list[TopoDS_Solid] | None = None, center: tuple[float, float, float] | None = None, orientation: tuple[float, float, float] | None = None)

Bases: object

Phase class: a collection of solids with shared material properties.

Exposes:

center_of_mass
inertia_matrix
shape (a CadShape)
solids (a list of raw OCCT TopoDS_Solid)

Parameters:

shape – a CadShape or raw TopoDS_Shape
solids – list of raw OCCT solids
center – center
orientation – orientation

property center_of_mass: ndarray[tuple[Any, ...], dtype[float64]]

Return the center of ‘mass’ of the phase.

Parameters:: compute – if False and center_of_mass already exists, does not compute it (use carefully)

classmethod generate_phase_per_raster(solids: list[TopoDS_Solid], rve: Rve, grid: list[int]) → list[Phase]

Raster solids into per-grid-cell Phases.

Parameters:

solids – list of OCCT solids
rve – RVE divided by the given grid
grid – number of divisions in each direction [x, y, z]

Returns:

list of Phase

get_center_of_mass(*, compute: bool = True) → ndarray[tuple[Any, ...], dtype[float64]]

Return the center of ‘mass’ of the phase.

Parameters:: compute – if False and center_of_mass already exists, does not compute it (use carefully)

get_inertia_matrix(*, compute: bool = True) → ndarray[tuple[Any, ...], dtype[float64]]

Calculate the inertia matrix of the phase.

Parameters:: compute – if False and inertia_matrix already exists, does not compute it (use carefully)

property inertia_matrix: ndarray[tuple[Any, ...], dtype[float64]]

Calculate the inertia matrix of the phase.

Parameters:: compute – if False and inertia_matrix already exists, does not compute it (use carefully)

num_instances = 0

rasterize(rve: Rve, grid: list[int], *, phase_per_raster: bool = True) → list[Phase] | None

Raster solids from phase according to the rve divided by the given grid.

Parameters:

rve – RVE divided by the given grid
grid – number of divisions in each direction [x, y, z]
phase_per_raster – if True, returns list of phases

Returns:

list of Phases if required

repeat(rve: Rve, grid: tuple[int, int, int]) → None: Repeat phase in place on a grid within the rve periodicity cell.

static repeat_shape(unit_geom: ShapeLike, rve: Rve, grid: tuple[int, int, int]) → CadShape

Repeat unit_geom on a grid within the rve periodicity cell.

Returns a CadShape wrapping an OCCT compound of translated copies of unit_geom.

rescale(scale: float | tuple[float, float, float]) → None: Rescale phase (in place) by scale = (sx, sy, sz) or a scalar.

static rescale_shape(shape: ShapeLike, scale: float | tuple[float, float, float]) → CadShape

Rescale shape by scale = (sx, sy, sz) (or a scalar).

Preserves the shape’s center of mass — scaling is performed about it.

property shape: CadShape | None: Return the shape of the phase as a CadShape.

property solids: list[TopoDS_Solid]: Return the list of OCCT TopoDS_Solid in the phase.

split_solids(rve: Rve, grid: list[int]) → list[TopoDS_Solid]

Split solids from phase according to the rve divided by the given grid.

Each solid is split by the (grid-1) interior planes along each axis; planes are constructed with microgen.cad.make_plane_face() and applied through OCCT’s BRepAlgoAPI_Splitter.

Parameters:

rve – RVE divided by the given grid
grid – number of divisions in each direction [x, y, z]

Returns:

list of raw OCCT TopoDS_Solid

translate(vec: Sequence[float]) → None: Translate phase by a given vector (in place).

Operations

Boolean operations.

All OCP imports are deferred so the module loads cleanly in a mesh-only install. Functions that use OCCT raise a clear ImportError (via microgen.cad.require_cad()) if the [cad] extra isn’t installed.

microgen.operations.cut_phase_by_shape_list(phase_to_cut: Phase, shapes: list[CadShape]) → Phase

Cut a phase by a list of shapes.

Parameters:

phase_to_cut – phase to cut
shapes – list of cutting shapes

Return resultCut:

cut phase

microgen.operations.cut_phases(phases: list[Phase], *, reverse_order: bool = True) → list[Phase]

Cut list of shapes in the given order (or reverse) and fuse them.

Parameters:

phases – list of phases to cut
reverse_order – bool, order for cutting shapes, when True: the last shape of the list is not cut

:return list of phases

microgen.operations.cut_phases_by_shape(phases: list[Phase], cut_obj: CadShape) → list[Phase]

Cut list of phases by a given shape.

Parameters:

phases – list of phases to cut
cut_obj – cutting object

Return phase_cut:

final result

microgen.operations.cut_shapes(shapes: list[CadShape], *, reverse_order: bool = True) → list[CadShape]

Cut list of shapes in the given order (or reverse) and fuse them.

Parameters:

shapes – list of shapes to cut
reverse_order – bool, order for cutting shapes, when True: the last shape of the list is not cut

Return cutted_shapes:

list of CadShape

microgen.operations.fuse_shapes(shapes: list[CadShape], *, retain_edges: bool) → CadShape

Fuse all shapes in the list.

Parameters:

shapes – list of shapes to fuse
retain_edges – retain intersecting edges

Returns:

fused shape

microgen.operations.raster_phase(phase: Phase, rve: Rve, grid: list[int], *, phase_per_raster: bool = True) → Phase | list[Phase]

Raster solids from phase according to the rve divided by the given grid.

Parameters:

phase – phase to raster
rve – RVE divided by the given grid
grid – number of divisions in each direction [x, y, z]
phase_per_raster – if True, returns list of phases

Returns:

Phase or list of Phases

microgen.operations.repeat_polydata(mesh: pv.PolyData, rve: Rve, grid: tuple[int, int, int]) → pv.PolyData

Repeat mesh in each direction according to the given grid.

Parameters:

mesh – pv.PolyData to repeat
rve – RVE of the geometry to repeat
grid – list of number of geometry repetitions in each direction

Returns:

pv.PolyData of the repeated geometry

microgen.operations.repeat_shape(unit_geom: CadShape, rve: Rve, grid: tuple[int, int, int]) → CadShape

Repeat unit geometry in each direction according to the given grid.

Parameters:

unit_geom – Shape to repeat
rve – RVE of the geometry to repeat
grid – list of number of geometry repetitions in each direction

Returns:

cq shape of the repeated geometry

microgen.operations.rescale(shape: CadShape, scale: float | tuple[float, float, float]) → CadShape: Rescale given object according to scale parameters [dim_x, dim_y, dim_z].

microgen.operations.rotate(obj: CadShape, center: npt.NDArray[np.float64] | Sequence[float], rotation: Rotation) → CadShape

microgen.operations.rotate(obj: PolyData, center: npt.NDArray[np.float64] | Sequence[float], rotation: Rotation) → PolyData

microgen.operations.rotate(obj: UnstructuredGrid, center: npt.NDArray[np.float64] | Sequence[float], rotation: Rotation) → UnstructuredGrid

Rotate object according to given rotation.

Supports microgen.cad.CadShape and any pyvista.DataSet (PolyData, UnstructuredGrid, StructuredGrid, …) — i.e. any pyvista mesh exposing rotate_vector.

Parameters:

obj – Object to rotate
center – numpy array (x, y, z)
rotation – scipy Rotation object

Returns:

Rotated object (same type as input)

Raises:

ValueError – if object type is not supported

microgen.operations.rotate_euler(obj: CadShape, center: npt.NDArray[np.float64] | Sequence[float], angles_or_rotation: Sequence[float] | Rotation) → CadShape

microgen.operations.rotate_euler(obj: PolyData, center: npt.NDArray[np.float64] | Sequence[float], angles_or_rotation: Sequence[float] | Rotation) → PolyData

Rotate object according to ZXZ Euler angle convention.

Accepts CadShape or pyvista.PolyData.

Parameters:

obj – Object to rotate
center – numpy array (x, y, z)
angles_or_rotation – list of Euler angles (psi, theta, phi) in degrees, or a scipy Rotation object

Returns:

Rotated object

microgen.operations.rotate_pv_euler(obj: pv.PolyData, center: Sequence[float], angles_or_rotation: Sequence[float] | Rotation) → pv.PolyData

Rotate object according to ZXZ Euler angle convention.

Parameters:

obj – Object to rotate
center – numpy array (x, y, z)
angles_or_rotation – list of Euler angles (psi, theta, phi) in degrees, or a scipy Rotation object

Returns:

Rotated object

Rve

Representative Volume Element (RVE).

The Rve.box attribute is a CadShape wrapping an OCCT box; it is built lazily on first access and requires the [cad] extra (cadquery-ocp-novtk).

class microgen.rve.Rve(center: Vector3DType = (0, 0, 0), dim: float | Vector3DType = 1)

Bases: object

Representative Volume Element (RVE).

Parameters:

center – center of the RVE
dim – dimensions of the RVE

property box: CadShape

Return a CadShape box of the RVE (cached).

Requires the [cad] extra.

classmethod from_min_max(min_point: Vector3DType = (-0.5, -0.5, -0.5), max_point: Vector3DType = (0.5, 0.5, 0.5)) → Rve

Generate a Rve from min and max corner points.

Parameters:

min_point – (x_min, y_min, z_min) corner of the RVE
max_point – (x_max, y_max, z_max) corner of the RVE

Periodic

Periodic cut — rearrange a shape so it wraps around an RVE.

Pure OCP implementation (cadquery-ocp-novtk); no cadquery dependency. Requires the [cad] extra.

microgen.periodic.periodic_split_and_translate(phase: Phase, rve: Rve) → Phase

Rearrange a phase periodically so it wraps the RVE.

Pure OCP implementation — no cadquery dependency.

Parameters:

phase – Phase to cut periodically
rve – RVE for periodicity

Returns:

resulting Phase

Mesh

Mesh using gmsh.

exception microgen.mesh.OutputMeshNotPeriodicError

Bases: Exception

Raised when output mesh from mesh_periodic is not periodic.

microgen.mesh.is_periodic(nodes_coords: ndarray[tuple[Any, ...], dtype[float64]], tol: float = 1e-08) → bool

Check whether a mesh is periodic, given its nodes’ coordinates.

Parameters:

nodes_coords – list of nodes coordinates of the analyzed mesh
tol – tolerance

microgen.mesh.mesh(mesh_file: str, list_phases: list[Phase], size: float, order: int, output_file: str = 'Mesh.msh', msh_file_version: int = 4) → None

Mesh step file with gmsh with list of phases management.

Parameters:

mesh_file – step file to mesh
list_phases – list of phases to mesh
size – mesh size constraint (see: gmsh.model.mesh.setSize(dimTags, size))
order – see gmsh.model.mesh.setOrder(order)
output_file – output file (.msh, .vtk)
msh_file_version – gmsh file version

microgen.mesh.mesh_periodic(mesh_file: str, rve: Rve, list_phases: list[Phase], size: float, order: int, output_file: str = 'MeshPeriodic.msh', msh_file_version: int = 4, tol: float = 1e-08) → None

Mesh periodic geometries with gmsh.

Parameters:

mesh_file – step file to mesh
rve – RVE for periodicity
list_phases – list of phases to mesh
size – mesh size constraint (see: gmsh.model.mesh.setSize(dimTags, size))
order – see gmsh.model.mesh.setOrder(order)
output_file – output file (.msh, .vtk)
msh_file_version – gmsh file version
tol – tolerance for periodicity check

Remesh

Remesh a mesh using mmg while keeping boundaries untouched.

exception microgen.remesh.InputMeshNotPeriodicError

Bases: Exception

Raised when the input mesh is not periodic.

Triggered when periodic=True is passed to remesh_keeping_boundaries_for_fem() but the supplied input mesh fails the periodicity check.

exception microgen.remesh.OutputMeshNotPeriodicError

Bases: Exception

Raised when the remeshed output is not periodic.

Triggered when periodic=True is passed to remesh_keeping_boundaries_for_fem() but mmg’s output fails the periodicity check.

microgen.remesh.remesh_keeping_boundaries_for_fem(input_mesh: BoxMesh, *, periodic: bool = True, mesh_version: int = 2, dimension: int = 3, tol: float = 1e-08, hausd: float | None = None, hgrad: float | None = None, hmax: float | None = None, hmin: float | None = None, hsiz: float | None = None) → BoxMesh

microgen.remesh.remesh_keeping_boundaries_for_fem(input_mesh: UnstructuredGrid, *, periodic: bool = True, mesh_version: int = 2, dimension: int = 3, tol: float = 1e-08, hausd: float | None = None, hgrad: float | None = None, hmax: float | None = None, hmin: float | None = None, hsiz: float | None = None) → UnstructuredGrid

Remesh a mesh using mmg while keeping boundary elements untouched.

See https://www.mmgtools.org/mmg-remesher-try-mmg/mmg-remesher-options for the full reference on each h* parameter.

Parameters:

input_mesh – BoxMesh or pv.UnstructuredGrid mesh to be remeshed
periodic – whether the mesh is periodic and must stay periodic
mesh_version – mesh file version
dimension – mesh dimension
tol – tolerance for the periodicity check
hausd – maximal Hausdorff distance for the boundaries approximation
hgrad – gradation value, i.e. ratio between lengths of adjacent mesh edges
hmax – maximal edge size
hmin – minimal edge size
hsiz – build a constant size map of size hsiz

External

Wrappers around external command-line tools.

class microgen.external.Mmg

Bases: object

Wrapper around the mmg2d_O3 / mmgs_O3 / mmg3d_O3 binaries.

Each method exposes the underlying mmg CLI flags as keyword arguments using the same short names as the binaries themselves (input, output, ls, nr, A, ar, …). See the mmg documentation for the full reference.

A larger redesign of this interface is planned; for now it intentionally mirrors the original flat-kwarg shape.

static mmg2d(d=None, h=None, m=None, v=None, val=None, default=None, input=None, output=None, solution=None, metric=None, A=None, ar=None, hausd=None, hgrad=None, hmax=None, hmin=None, hsiz=None, lag=None, ls=None, _3dMedit=None, noinsert=None, nomove=None, nosurf=None, noswap=None, nr=None, nreg=None, nsd=None, optim=None, opnbdy=None, rmc=None): Run mmg2d_O3 from the command line with given arguments.

static mmg3d(d=None, h=None, m=None, v=None, val=None, default=None, input=None, output=None, solution=None, metric=None, A=None, ar=None, octree=None, hausd=None, hgrad=None, hmax=None, hmin=None, hsiz=None, lag=None, ls=None, nofem=None, noinsert=None, nomove=None, nosurf=None, noswap=None, nr=None, nreg=None, nsd=None, optim=None, optimLES=None, opnbdy=None, rmc=None, rn=None): Run mmg3d_O3 from the command line with given arguments.

static mmgs(d=None, h=None, m=None, v=None, val=None, default=None, input=None, output=None, solution=None, metric=None, A=None, ar=None, hausd=None, hgrad=None, hmax=None, hmin=None, hsiz=None, ls=None, noinsert=None, nomove=None, nosurf=None, noswap=None, nr=None, nreg=None, nsd=None, optim=None, rn=None): Run mmgs_O3 from the command line with given arguments.

exception microgen.external.MmgError

Bases: Exception

Raised when an mmg command fails.

class microgen.external.Neper

Bases: object

Wrapper around the neper command-line tool.

static parse_tess(filename: str) → dict[str, dict]

Parse a tessellation (.tess) file generated by neper.

Returns a dictionary with keys cells, vertices, edges, faces, polyhedra. Follows the .tess structure from `neper's documentation`_.

static run(filename: str, n_cells: int, cube_dim: tuple[float, float, float]) → None

Run a neper tessellation from the command line.

Equivalent to:

neper -T -n n_cells -id 1 -dim 3 \
      -domain 'cube(cube_dim[0], cube_dim[1], cube_dim[2])' \
      -morpho gg -o filename

Parameters:

filename – output file
n_cells – number of cells of the tessellation
cube_dim – see `neper's documentation`_

static voronoi_from_tess_file(filename: str) → list[Polyhedron]: Build Polyhedron shapes from a neper-generated .tess file.