Python API Reference

Python API Reference#

Main Class#

class cad_to_dagmc.CadToDagmc[source]#

Bases: object

Converts Step files and CadQuery parts to a DAGMC h5m file

add_stp_file(filename, scale_factor=1.0, material_tags=None)[source]#

Loads the parts from stp file into the model.

Parameters:

  • filename (str) – the filename used to save the html graph.

  • material_tags (list[str] | str | None) – the names of the DAGMC material tags to assign. Can be a list of strings (one per volume), or one of the special strings “assembly_names” or “assembly_materials” to automatically extract tags from the STEP file’s assembly structure (if the STEP file contains named parts or materials). When using a list, tags must be in the same order as the volumes in the geometry.

  • scale_factor (float) – a scaling factor to apply to the geometry that can be used to increase the size or decrease the size of the geometry. Useful when converting the geometry to cm for use in neutronics simulations.

Returns:

number of volumes in the stp file.

Return type:

int

add_cadquery_object(cadquery_object, material_tags, scale_factor=1.0)[source]#

Loads the parts from CadQuery object into the model.

Parameters:

  • cadquery_object (Assembly | Compound | Solid) – the cadquery object to convert, can be a CadQuery assembly cadquery workplane or a cadquery solid

  • material_tags (list[str] | str) – the names of the DAGMC material tags to assign. These will need to be in the same order as the volumes in the geometry added (STP file and CadQuery objects) and match the material tags used in the neutronics code (e.g. OpenMC).

  • scale_factor (float) – a scaling factor to apply to the geometry that can be used to increase the size or decrease the size of the geometry. Useful when converting the geometry to cm for use in neutronics simulations.

Returns:

number of volumes in the stp file.

Return type:

int

export_unstructured_mesh_file(filename='umesh.vtk', min_mesh_size=1, max_mesh_size=5, mesh_algorithm=1, method='file', scale_factor=1.0, imprint=True, set_size=None, volumes=None, threads=0, meshing_backend=None, target_edge_length=None, tet_volumes=None, tolerance=0.01, angular_tolerance=0.2)[source]#

Exports an unstructured mesh file in VTK format for use with openmc.UnstructuredMesh. Compatible with the MOAB unstructured mesh library. Example useage openmc.UnstructuredMesh(filename=”umesh.vtk”, library=”moab”).

The mesh can be produced either with gmsh or with the cad-to-dagmc-mesher backend. The gmsh backend uses the min/max mesh size and set_size arguments, while the cad-to-dagmc-mesher backend uses target_edge_length (and optionally tet_volumes) to control the tetrahedra. gmsh is used unless meshing_backend or one of the cad-to-dagmc-mesher specific arguments is provided.

Parameters:#

filenamestr, optional

The name of the output file. Default is “umesh.vtk”.

min_mesh_size: the minimum mesh element size to use in Gmsh. Passed

into gmsh.option.setNumber(“Mesh.MeshSizeMin”, min_mesh_size)

max_mesh_size: the maximum mesh element size to use in Gmsh. Passed

into gmsh.option.setNumber(“Mesh.MeshSizeMax”, max_mesh_size)

mesh_algorithm: The Gmsh mesh algorithm number to use. Passed into

gmsh.option.setNumber(“Mesh.Algorithm”, mesh_algorithm)

method: the method to use to import the geometry into gmsh. Options

are ‘file’ or ‘in memory’. ‘file’ is the default and will write the geometry to a temporary file before importing it into gmsh. ‘in memory’ will import the geometry directly into gmsh but requires the version of OpenCASCADE used to build gmsh to be the same as the version used by CadQuery. This is possible to ensure when installing the package with Conda but harder when installing from PyPI.

scale_factor: a scaling factor to apply to the geometry that can be

used to enlarge or shrink the geometry. Useful when converting the geometry to cm for use in neutronics.

imprint: whether to imprint the geometry or not. Defaults to True as this is

normally needed to ensure the geometry is meshed correctly. However if you know your geometry does not need imprinting you can set this to False and this can save time. A positive int can be passed instead of True to imprint with that many threads, for example imprint=1 imprints on a single thread. Imprinting runs in parallel and its peak RAM scales with the number of threads, so fewer threads lowers the peak RAM of large models at the cost of speed. Only the imprint is limited, the meshing that follows it keeps all its threads whichever backend is used, and the thread count is restored afterwards so the cadquery operations that follow are unaffected.

set_size: a dictionary mapping volume IDs (int) or material tag names

(str) to target mesh sizes (floats). Material tags are resolved to all volume IDs that have that tag. Only used by the gmsh backend.

volumes: a list of volume ids (int) to include in the mesh. If left

as default (None) then all volumes will be included. Only used by the gmsh backend.

threads: the number of threads for Gmsh to use. 0 uses all

available cores (default), 1 uses a single thread.

meshing_backend: the backend used to generate the tetrahedra, either

“gmsh” or “cad-to-dagmc-mesher”. If not set, the backend is auto-selected: “cad-to-dagmc-mesher” when target_edge_length or tet_volumes is provided, otherwise “gmsh”.

target_edge_length: the target tetrahedron edge length used by the

cad-to-dagmc-mesher backend. Required when meshing_backend is “cad-to-dagmc-mesher”.

tet_volumes: an iterable of material tag names identifying which

volumes to fill with tetrahedra when using the cad-to-dagmc-mesher backend. Defaults to all volumes.

tolerance: linear deflection tolerance for the surface mesh, used by

the cad-to-dagmc-mesher backend. This is in the units of the SCALED geometry, since scale_factor is applied before meshing, so scale it alongside scale_factor. With scale_factor=100 the 0.01 default is a 0.1 mm deflection, which on a large model can produce a very fine mesh and exhaust memory. The same applies to min_mesh_size/max_mesh_size/set_size for the gmsh backend.

angular_tolerance: angular deflection tolerance for the surface mesh,

used by the cad-to-dagmc-mesher backend. An angle, so unaffected by scale_factor.

Returns:#

:
filenamestr

The filename of the written unstructured mesh file.

Parameters:
export_gmsh_mesh_file(filename='mesh.msh', min_mesh_size=None, max_mesh_size=None, mesh_algorithm=1, dimensions=2, method='file', scale_factor=1.0, imprint=True, set_size=None, threads=0)[source]#

Saves a GMesh msh file of the geometry in either 2D surface mesh or 3D volume mesh.

Parameters:

  • filename (str)

  • min_mesh_size (float | None) – the minimum size of mesh elements to use.

  • max_mesh_size (float | None) – the maximum size of mesh elements to use.

  • mesh_algorithm (int) – the gmsh mesh algorithm to use.

  • dimensions (int) – The number of dimensions, 2 for a surface mesh 3 for a volume mesh. Passed to gmsh.model.mesh.generate()

  • method (str) – the method to use to import the geometry into gmsh. Options are ‘file’ or ‘in memory’. ‘file’ is the default and will write the geometry to a temporary file before importing it into gmsh. ‘in memory’ will import the geometry directly into gmsh but requires the version of OpenCASCADE used to build gmsh to be the same as the version used by CadQuery. This is possible to ensure when installing the package with Conda but harder when installing from PyPI.

  • scale_factor (float) – a scaling factor to apply to the geometry that can be used to enlarge or shrink the geometry. Useful when converting Useful when converting the geometry to cm for use in neutronics

  • imprint (bool | int) – whether to imprint the geometry or not. Defaults to True as this is normally needed to ensure the geometry is meshed correctly. However if you know your geometry does not need imprinting you can set this to False and this can save time. A positive int can be passed instead of True to imprint with that many threads, for example imprint=1 imprints on a single thread. Imprinting runs in parallel and its peak RAM scales with the number of threads, so fewer threads lowers the peak RAM of large models at the cost of speed. The thread count is restored afterwards so the cadquery operations that follow are unaffected.

  • set_size (dict[int | str, float] | None) – a dictionary mapping volume IDs (int) or material tag names (str) to target mesh sizes (floats). Material tags are resolved to all volume IDs that have that tag.

  • threads (int) – the number of threads for Gmsh to use. 0 uses all available cores (default), 1 uses a single thread.

export_dagmc_h5m_file(filename='dagmc.h5m', implicit_complement_material_tag=None, scale_factor=1.0, imprint=True, **kwargs)[source]#

Saves a DAGMC h5m file of the geometry

Parameters:

  • filename (str) – the filename to use for the saved DAGMC file.

  • implicit_complement_material_tag (str | None) – the name of the material tag to use for the implicit complement (void space).

  • scale_factor (float) – a scaling factor to apply to the geometry. All the linear mesh sizing arguments (min_mesh_size, max_mesh_size and set_size for gmsh, tolerance and target_edge_length for cad-to-dagmc-mesher, tolerance for cadquery) are in the units of the SCALED geometry, so the same number means the same thing on the output mesh whichever backend is used. For example with scale_factor=100 (m to cm) a tolerance of 0.5 is a 5 mm deflection. Note this means the defaults get finer as scale_factor grows: the cad-to-dagmc-mesher tolerance default of 0.01 is a 0.1 mm deflection at scale_factor=100, which on a large model can produce a very fine mesh and exhaust memory, so scale the tolerance along with the geometry. angular_tolerance is an angle and so is unaffected by scaling.

  • imprint (bool | int) – whether to imprint the geometry or not. A positive int can be passed instead of True to imprint with that many threads, for example imprint=1 imprints on a single thread. Imprinting runs in parallel and its peak RAM scales with the number of threads, so fewer threads lowers the peak RAM of large models at the cost of speed. Only the imprint is limited, the meshing that follows it keeps all its threads whichever backend is used, and the thread count is restored afterwards so the cadquery operations that follow are unaffected.

  • **kwargs –

    Backend-specific parameters:

    Backend selection: - meshing_backend (str, optional): explicitly specify ‘gmsh’,

    ’cadquery’ or ‘cad-to-dagmc-mesher’. If not provided, backend is auto-selected based on other arguments: tet_volumes or target_edge_length select ‘cad-to-dagmc-mesher’, gmsh-specific arguments select ‘gmsh’. Defaults to ‘cad-to-dagmc-mesher’ if no backend-specific arguments are given, falling back to ‘cadquery’ when cad-to-dagmc-mesher is not installed.

    • h5m_backend (str, optional): ‘pymoab’ or ‘h5py’ for writing h5m files. Defaults to ‘h5py’.

    For GMSH backend: - min_mesh_size (float): minimum mesh element size - max_mesh_size (float): maximum mesh element size - mesh_algorithm (int): GMSH mesh algorithm (default: 1) - method (str): import method ‘file’ or ‘in memory’ (default: ‘file’) - set_size (dict[int | str, float]): volume IDs (int) or material tag

    names (str) mapped to target mesh sizes. Material tags are resolved to all volume IDs that have that tag.

    • unstructured_volumes (Iterable[int | str]): volume IDs (int) or material tag names (str) for unstructured mesh. Material tags are resolved to all volume IDs that have that tag. Can mix ints and strings.

    • umesh_filename (str): filename for unstructured mesh (default: ‘umesh.vtk’)

    • threads (int): number of threads for Gmsh to use. 0 uses all available cores (default), 1 uses a single thread.

    For CadQuery backend: - tolerance (float): meshing tolerance (default: 0.1), in the

    units of the scaled geometry (see scale_factor above)

    • angular_tolerance (float): angular tolerance (default: 0.1)

    For cad-to-dagmc-mesher backend: - tolerance (float): surface meshing tolerance (default: 0.01),

    in the units of the scaled geometry (see scale_factor above). With scale_factor=100 the 0.01 default is a 0.1 mm deflection, which on a large model can produce a very fine mesh and exhaust memory; scale the value with scale_factor.

    • angular_tolerance (float): surface angular tolerance (default: 0.2)

    • tet_volumes (Iterable[str]): material tag names of the volumes to fill with tetrahedra for an unstructured volume mesh.

    • target_edge_length (float): target tetrahedron edge length. Both tet_volumes and target_edge_length must be given together to write a volume mesh; when they are, the return value is a (dagmc_filename, umesh_filename) tuple.

    • umesh_filename (str): filename for the unstructured volume mesh (default: ‘umesh.vtk’).

Returns:

the filename(s) for the files created.

Return type:

str

Raises:

ValueError – If invalid parameter combinations are used.

Standalone Functions#

GMSH to DAGMC Conversion#

cad_to_dagmc.export_gmsh_file_to_dagmc_h5m_file(gmsh_filename, material_tags=None, implicit_complement_material_tag=None, dagmc_filename='dagmc.h5m', h5m_backend='h5py')[source]#

Saves a DAGMC h5m file of the geometry GMsh file. This function initializes and finalizes Gmsh.

Parameters:

  • gmsh_filename (str) – the filename of the GMSH mesh file.

  • material_tags (list[str] | None) – the names of the DAGMC material tags to assign. These will need to be in the same order as the volumes in the GMESH mesh and match the material tags used in the neutronics code (e.g. OpenMC).

  • implicit_complement_material_tag (str | None) – the name of the material tag to use for the implicit complement (void space). Defaults to None which is a vacuum.

  • dagmc_filename (str) – Output filename. Defaults to “dagmc.h5m”.

  • h5m_backend (str) – Backend for writing h5m file, ‘pymoab’ or ‘h5py’. Defaults to ‘h5py’.

Returns:

The filename of the generated DAGMC h5m file.

Return type:

str

Raises:

ValueError – If the number of material tags does not match the number of volumes in the GMSH object.

cad_to_dagmc.export_gmsh_object_to_dagmc_h5m_file(material_tags=None, implicit_complement_material_tag=None, filename='dagmc.h5m', h5m_backend='h5py')[source]#

Exports a GMSH object to a DAGMC-compatible h5m file. Note gmsh should be initialized by the user prior and the gmsh model should be meshed before calling this. Also users should ensure that the gmsh model is finalized.

Parameters:

  • material_tags (list[str] | None) – A list of material tags corresponding to the volumes in the GMSH object.

  • implicit_complement_material_tag (str | None) – The material tag for the implicit complement (void space).

  • filename (str) – The name of the output h5m file. Defaults to “dagmc.h5m”.

  • h5m_backend (str) – Backend for writing h5m file, ‘pymoab’ or ‘h5py’. Defaults to ‘h5py’.

Returns:

The filename of the generated DAGMC h5m file.

Return type:

str

Raises:

ValueError – If the number of material tags does not match the number of volumes in the GMSH object.

Low-Level Functions#

cad_to_dagmc.vertices_to_h5m(vertices, triangles_by_solid_by_face, material_tags, h5m_filename='dagmc.h5m', implicit_complement_material_tag=None, method='h5py')[source]#

Converts vertices and triangle sets into a tagged h5m file compatible with DAGMC enabled neutronics simulations

Parameters:

  • vertices (list[tuple[float, float, float]] | list[cadquery.occ_impl.geom.Vector]) – List of vertex coordinates as (x, y, z) tuples or CadQuery vectors

  • triangles_by_solid_by_face (dict[int, dict[int, list[list[int]]]]) – Dict mapping solid_id -> face_id -> list of triangles

  • material_tags (list[str]) – List of material tag names, one per solid

  • h5m_filename (str) – Output filename for the h5m file

  • implicit_complement_material_tag (str | None) – Optional material tag for implicit complement

  • method (str) – Backend to use for writing h5m file (‘pymoab’ or ‘h5py’)

cad_to_dagmc.init_gmsh()[source]#
cad_to_dagmc.get_volumes(gmsh, assembly, method='file', scale_factor=1.0)[source]#
cad_to_dagmc.set_sizes_for_mesh(gmsh, min_mesh_size=None, max_mesh_size=None, mesh_algorithm=1, set_size=None, original_set_size=None, threads=0)[source]#

Sets up the mesh sizes for each volume in the mesh.

Parameters:

  • occ_shape – the occ_shape of the Brep file to convert

  • min_mesh_size (float | None) – the minimum mesh element size to use in Gmsh. Passed into gmsh.option.setNumber(“Mesh.MeshSizeMin”, min_mesh_size)

  • max_mesh_size (float | None) – the maximum mesh element size to use in Gmsh. Passed into gmsh.option.setNumber(“Mesh.MeshSizeMax”, max_mesh_size)

  • mesh_algorithm (int) – The Gmsh mesh algorithm number to use. Passed into gmsh.option.setNumber(“Mesh.Algorithm”, mesh_algorithm)

  • set_size (dict[int | str, float] | None) – a dictionary of volume ids (int) and target mesh sizes (floats) to set for each volume, passed to gmsh.model.mesh.setSize.

  • threads (int) – the number of threads for Gmsh to use. Passed into gmsh.option.setNumber(“General.NumThreads”, threads). 0 uses all available cores (default), 1 uses a single thread.

  • original_set_size (dict[int | str, float] | None)

Returns:

The resulting gmsh object and volumes

cad_to_dagmc.mesh_to_vertices_and_triangles(dims_and_vol_ids)[source]#

Converts gmsh volumes into vertices and triangles for each face.

Parameters:

volumes – the volumes in the gmsh file, found with gmsh.model.occ.importShapes

Returns:

vertices and triangles (grouped by solid then by face)

Exceptions#

exception cad_to_dagmc.PyMoabNotFoundError(message=None)[source]#

Bases: ImportError

Raised when pymoab is not installed but the pymoab backend is requested.

exception cad_to_dagmc.CadToDagmcMesherNotFoundError(message=None)[source]#

Bases: ImportError

Raised when cad-to-dagmc-mesher is not installed but its backend is requested.