2. CAD-to-CSG decomposition

The MCIO code uses the Open Cascade thin wrapped Python package OCP, and can take a STEP CAD file and convert it into a CSG model, which can then be written to an MCNP input deck or OpenMC XML files.

2.1. Running from the command line

The MCIO CAD-to-CSG decomposer can be run with the default values via the command line, running with single or multiprocess, and optionally with debugging and/or allowing failures to convert.

python -m mcio decompose -i my_model.stp --cores 8 --materials materials.json

To check if a model converts, it is useful to use the command line method using multiple cores. This will try to convert all bodies, with any bodies which fail to convert being saved to individual step files in the analysis/failed_to_convert directory. Typically, this will be caused by bodies being too complex or having possible geometry errors within them.

Possible reasons for failures:

  • Inexact edges (most common errors), to fix or split on edges, particularly with pipes

  • Solids too complex, try splitting them up into multiple bodies

  • Bad geometry, try to fix geometry errors or de-draw solids

  • Contain faces which don’t currently convert, such as off axis tori or splines

2.2. Running via the Python API

The MCIO CAD-to-CSG decomposer allows for either single core or multiple core use via the “multiprocessing” package. The latter provides significant speed increases during conversion but requires some boiler plate code to run, an example of which is given below.

2.2.1. Single core example

# import the decomposer class from mcio
import mcio 

# define your list of step files to combine into a single model
step_files = ['my_model_1.stp', 'my_model_2.stp']

# create an instance of the decomposer
decomposer = mcio.decompose.Decomposer(step_files, materials_file_path='materials.json')

# run the decomposer on a single core
decomposer.run(cores=1)

# save the model to an mcnp input deck
decomposer.model.write_mcnp('model.i')

# save the model to a folder of openmc xml files
decomposer.model.write_openmc('openmc_model')

2.2.2. Multiprocess example

Increasing the number of cores requested in the .run(cores=20) method allows the decomposer to run via multiprocessing, but this requires the if __name__ == "__main__": guard to be placed around the code, otherwise an infinitely recursive import will be triggered.

import mcio

# set up guard to stop recursive imports
if __name__ == '__main__':
    # define path to step files
    step_files = ['my_model_1.stp', 'my_model_2.stp']
    
    # create the decomposer and run on 20 cores
    decomposer = mcio.decompose.Decomposer(step_files, materials_file_path='materials.json')
    decomposer.run(cores=20, debug=False)

    # save the models to mcnp or openmc
    decomposer.model.write_mcnp('model.i')
    decomposer.model.write_openmc('openmc_model')

2.2.3. Assigning materials

Materials can be assigned within the CAD file either via setting the RGB colour of the solid or via the addition of a label of the form m, with being an integer. The materials can be defined within a JSON which the user is required to provide. It should be noted that single solids within a component will lose their labels as OCP will assign the parent component’s label to the solid; however, if there are two or more solids within a component then each solid keeps its own label.

python -m mcio decompose -i my_model.stp --cores 8 --materials materials.json
# create an instance of the decomposer, and provide path to json for materials
decomposer = mcio.decompose.Decomposer(['my_model.stp'], materials_file_path='materials.json')

2.2.3.1. Assign by label (m)

The below image shows material assignment via the label method, with an example of the required accompanying material definition in JSON format.

Warning

A single solid within a component, such as sphere_4 in the example below, will lose its label as OCP will assign the parent component to the solid.

Example of a structure tree with material assignment

Material assignment by label in the CAD structure tree.

{
    "m1": {
        "density": 0.997,
        "composition": {
            "H": 0.666667,
            "O": 0.333333
        },
        "number": 100,
        "reference": "",
        "fraction_type": "ao",
        "density_type": "g/cc",
        "name": "Water, Liquid",
        "mcnp": {
            "sab_cards": [],
            "libs": {},
            "library": ".32c",
            "library_by_isotopes": {"O18": ".80c"}
        }
    }
}

2.2.3.2. Assign by RGB colour

When assigning by RGB, the JSON should contain the RGB value as a string key in the format <red>_<green>_<blue>, with each value zero padded to three digits.

{
    "000_128_064": {
        "density": 0.997,
        "composition": {
            "H": 0.666667,
            "O": 0.333333
        },
        "number": 100,
        "reference": "",
        "fraction_type": "ao",
        "density_type": "g/cc",
        "name": "Water, Liquid",
        "mcnp": {
            "sab_cards": [],
            "libs": {},
            "library": ".32c",
            "library_by_isotopes": {"O18": ".80c"}
        }
    }
}

2.2.4. Debugging problem solids

CAD-to-CSG decomposition can fail or cause problems with lost particles, which can also have a wide range of reasons for these issues. The failed cad solids will be output to the analysis/failed_to_convert/ directory, which can then be loaded into your chosen CAD software. A text file containing the exception for each failed solid is output to the analysis/trackbacks/ directory.

Some common issues are:

  1. Inexact edges on connected 2nd order faces, particularly cylinders joined at an angle

  2. Rounding errors in coincident surface

  3. Rounding errors introduced during the splitting / cut / common operations in OCP

  4. Overlapping geometry

  5. Failure to generate correct void space

  6. Incorrect auxiliary surface generation

  7. Solids slow to convert as too complex for recursive splitting

There is also a command line tool for extracting the lost particles from an MCNP output file, which produces a step file with spherical points and lines as vectors for the particles directions. This can be accessed via the command line tool.

python -m mcio lost_particles -i my_mcnp_run.o -o lost_particles.stp --max_particles 100 --radius 0.5 --vector_length 200.0

Or it can be scripted using the function lost_particles_from_mcnp_run

from mcio.diagnostic import lost_particles_from_mcnp_run

lost_particles_from_mcnp_run(
    'my_mcnp_run.o',
    output_file_path='lost_particles.stp',
    max_particles=100,
    radius=0.5,
    vector_length=200.0
)

2.2.5. Altering the decomposition parameters

The Decomposer() has a set of default parameters for carrying out decomposition and conversion to CSG. These parameters can be printed using a python script.

# import mcio
import mcio

# create instance of DecompositionParameters containing default values
decom_params = mcio.decomposeparams.DecompositionParameters()

# write these to screen as a table, with a description of each parameter
print(decom_params)

# write to json
decom_params.write('decompose_parameters.json')

# read in decomposition parameters, and pass them to the decomposer
decom_params = mcio.decomposeparams.DecompositionParameters.read('decompose_parameters.json')
decomposer = mcio.decompose.Decomposer(['my_model.stp'], decompose_parameters=decom_params)

The default decomposition parameters are:

Parameter

Value

Description

doc_unit_in_metres

0.01

input unit length (m)

doc_xcaf_formatting

BinXCAF

XCAF Formatting

presplit_pipes

True

pre-split: use pipe splitting tools for connected cylinders of equal radius

presplit_pipes_cyl_angle_tol

0.01

pre-split on pipe cylinders: angle tolerance

presplit_concentril_2nd_order

True

pre-split: split connected 2nd order surfaces which are on the same axix with circular edge

presplit_about_axis

z

pre-split: split using planes about axis, either x, y or z

presplit_about_axis_n_times

4

pre-split: number of planes about axis to split, n * 2 = segments, e.g. 4 = 8 octants

presplit_rectilinear_voxels

False

pre-split: split all solids using a rectilinear grid

presplit_rectilinear_voxels_width

50.0

pre-split: width of voxels in rectilinear grid split

cleanup_unify_same_domains

False

unify domains can reduce number of preiodic boundaries

cleanup_shape_fix

False

apply clean up using ShapeFix_Solid before decomposition

cleanup_shape_fix_tol_min

1e-08

ShapeFix_ShapeTolerance minimum tolerance

cleanup_shape_fix_tol_max

1e-06

ShapeFix_ShapeTolerance maximum tolerance

cleanup_inexact_edges

False

check for inexact edges and cleanup with tolerance bounds

cleanup_inexact_edges_tol

0.0001

threshold tolerance for inexact edge fix

cleanup_inexact_edge_fix_tol_min

1e-08

inexact edges minimum tolerance

cleanup_inexact_edge_fix_tol_max

1e-06

inexact edges maximum tolerance

split_max_distnace_between_face_and_halfspace

0.0001

max dist between face and halfspace used to recursively split

split_unify_same_domains

False

apply unify same domains to merge periodic or duplicated conicident faces following splitting

split_sew

False

split sew to solids following recursive splitting

split_skip_non_cutting_planes

True

skip the half space and split of planar faces whose plane leaves the whole solid on the material side (they cannot split it)

split_skip_non_cutting_planes_rel_tol

1e-07

tolerance, relative to the solid size, for a solid to count as lying behind a planar face

split_solid_timeout

200.0

multiprocess runs only: seconds a single solid may take to decompose before its worker is stopped and the solid is saved as failed to convert (0 for no limit)

bool_common_fuzzy_value

1e-06

fuzzy logic value passed to common boolean operation

bool_cutter_fuzzy_value

1e-06

fuzzy logic value passed to the cut boolean operation

bool_splitter_fuzzy_value

1e-06

fuzzy logic value passed to the split boolean operation

bool_degenerate_min_area_to_vol_ratio

0.0001

area to vol ration limit, used to filter degenerate solids in boolean operations

bool_degenerate_min_vol_fraction_of_original

1e-10

minumum volume required as a fraction of the original solid

bool_degenerate_min_ab_vol

1e-10

minimum volume of any split solid produced via boolean operation

make_face_tol

1e-06

tolerance used when making a face

surf_plane_tol_normal_angle

1e-06

coincident planes: normal angle tolerance (degrees)

surf_plane_tol_on_axis

1e-06

ocp to mcio plane: on axis tol angle (degrees)

surf_plane_tol_distance

1e-06

ocp to mcio plane: distance between planes with same normal

surf_plane_rounding_lateral

5

ocp to mcio plane: decimal place rounding of lateral x, y, z and d parameters

surf_plane_rounding_vector

8

ocp to mcio plane: decimal place rounding of vector a, b, c parameters

surf_cylinder_tol_axis_angle

1e-06

ocp to mcio cyl: on axis tol angle (degrees)

surf_cylinder_tol_radius

1e-06

coincident cyl: radius tolerance

surf_cylinder_tol_axis_distance

1e-06

coincident cyl: axis distance

surf_cylinder_rounding_lateral

5

ocp to mcio cyl: decimal place rounding of lateral x, y, and z parameters

surf_cylinder_rounding_radius

5

ocp to mcio cyl: decimal place rounding of radius parameter

surf_sph_radius_tol

1e-06

coincident sph: radius tolerance

surf_sph_position_tol

1e-06

coincident sph: distance of centres tolerance

surf_cone_semi_angle_tol

1e-06

coincident cone: semi angle tolerance (degrees)

surf_cone_axis_angle_tol

1e-06

ocp to mcio cone: on axis angle tolerance (degrees)

surf_cone_axis_distance_tol

1e-06

ocp to mcio cone: on axis tolerance

surf_cone_rounding_lateral

5

ocp to mcio cone: rounding number of dp for apex cartesian x,y,z

surf_cone_rounding_t_sq

8

ocp to mcio cone: rounding of t_sq number of dp, t_sq = tan(semi_angle)**2

surf_tol_tori_minor_radius

1e-06

coincident tori: minor radius tolerance

surf_tol_tori_major_radius

1e-06

coincident tori: major radius tolerance

surf_tol_tori_axis_angle

1e-06

ocp to mcio tori: on axis angle tolerance (degrees)

surf_tol_tori_centre

1e-06

coincident tori: distance of centres tolerance

surf_tori_rounding_lateral

8

ocp to mcio tori: decimal place rounding of lateral x, y, and z parameters

surf_tori_rounding_radii

8

ocp to mcio tori: decimal place rounding of major and minor radii parameters

surf_general_quadratic_rounding_abc

8

decimal places to round GQ a, b and c params

surf_general_quadratic_rounding_def

8

decimal places to round GQ d, e and f params

surf_general_quadratic_rounding_ghj

8

decimal places to round GQ g, h and k params

surf_general_quadratic_rounding_k

8

decimal places to round GQ a, b and c params

wire_is_closed_tol

1e-06

tolerance checking if wire is closed

void_max_recursion_depth

30

maximum recursive depth

void_min_width

10.0

minimum void width of octant

void_max_split_solids_per_octant

50

maximum split solids in octant

void_max_faces_per_octant

250

maximum split solid faces per octant (excludes auxiliaries)

void_use_split_solid_distance_check

False

void_split_solid_fractoin_of_bounding_box

0.5

maximum fraction of the bounding box a split solid can contain before distance checks carried out

void_split_solid_distance_tol

0.01

void_filter_by_face

False

void_face_distance_tol

0.01

distance tolerance for BRepExtrema_DistanceShapeShapes between void bounding box and face

void_bounding_box_use_optimal

False

during void generation use the AddOptimal method for tighter bounding boxes

void_use_obb_check

True

filter split solids per octant by oriented bounding box (separating axis test) after the axis aligned check

void_use_halfspace_pruning

True

classify split solid half spaces against each octant: drop solids proven outside, drop half spaces proven to contain the octant, skip octants inside a solid

bounding_box_multiplier_half_space

10

expansion factor for bounding box rpp solid used for halfspace

aux_generate

True

generate auxiliary surfaces for second order faces

aux_bounding_box_analysis

1.5

extension of bounding box for aux surface in analysis save to cad

aux_surface_face_distace_tol

0.0001

distance tolerance for faces to be grouped fo coincident surfaces

aux_surface_cylinder_angle_tol

1e-06

aux surface cylinder angle tolerance (degrees)

aux_surface_cylinder_small_angle

0.0017453292519943296

aux surface cylinder small angle tolerance (degrees)

aux_surface_cylinder_simple

True

apply simple auxiliary surface method (true or false)

aux_surface_cone_angle_tol

1e-06

aux surface cone angle tolerance (degrees)

aux_surface_cone_small_angle

0.0017453292519943296

aux surface cone small angle tolerance (degrees)

aux_surface_cone_simple

True

apply simple auxiliary surface method (true or false)

aux_surface_sphere_angle_tol

1e-06

aux surface sphere angle tolerance (degrees)

aux_surface_sphere_small_angle

0.0017453292519943296

aux surface sphere small angle tolerance (degrees)

aux_surface_sphere_simple

True

apply simple auxiliary surface method (true or false)

aux_surface_tori_angle_tol

1e-06

auxiliary surface: tori angle tolerance (degrees)

aux_surface_tori_small_angle

0.0017453292519943296

auxiliary surface: tori small angle tolerance (degrees)

aux_surface_tori_aux_surface_simple

True

apply simple auxiliary surface method (true or false)

model_set_output_cell_vols

True

assign volume to output csg file

model_implicit_void_for_no_mateirals

True

Where no material is assigned, cells set to void be default. Otherwise require material assignment

debug_invalid_solid_path

analysis/invalid_solid/invalid_solid.stp

debugging: path of solids failing the validity check after clean up

debug_write_added_solids

False

debugging: write each solid added to the decomposer to a STEP file in added_solids/

debug_cut_fatal_path

analysis/cut_fatal/cut_fatal.stp

debugging: path of failed cut operations, dumps solids to step file

debug_cut_warning_path

analysis/cut_warnings/cut_warning.stp

debugging: path of cut operation with warning(s)

debug_cut_error_path

analysis/cur_errors/cut_error.stp

debugging: path of cut with error(s)

debug_common_fatal_path

analysis/common_fatal/common_fatal.stp

debugging: path of failed common operations, dumps solids to step file

debug_common_warning_path

analysis/common_warnings/common_warning.stp

debugging: path of common operation with warning(s)

debug_common_error_path

analysis/common_errors/common_error.stp

debugging: path of common operation with error(s)

debug_splitter_fatal_path

analysis/splitter_fatal/splitter_fatal.stp

debugging: path of failed splitter operations, dumps solids to step file

debug_splitter_warning_path

analysis/splitter_warnings/splitter_warning.stp

debugging: path of splitter operation with warning(s)

debug_splitter_error_path

analysis/splitter_errors/splitter_error.stp

debugging: path of splitter operation with error(s)

debug_filter_degenerate_solid_path

analysis/degenerate_solids/degenerate_solid.stp

debugging: path of filtered degenerate solids

debug_cut_common_path

analysis/cut_andcut_common/cut_common.stp

debugging: path of cut and common operation where 2+ commons created

debug_volume_conserved_path

analysis/vol_not_conserved/vol_not_conserved.stp

debugging: path of failed conserved volume operations, dumps solids to step file

debug_halfspace_manual_cylinder_path

analysis/halfspace_manual_cylinder/halfspace_manual_cylinder.stp

debugging: path for the cylinder and half space made when a cylinder half space is built manually (debug logging only)

debug_pipe_splitter

analysis/pre_pipe_splitter/pre_pipe_split.stp

debugging: path of step output following successful split of pipe

debug_concentric_splitter

analysis/concentric_splitter/pre_concentric_split.stp

debugging: path to step output following successful split of concentril second order surfaces

debug_rectilinear_splitter

analysis/rectilinear_splitter/pre_rectilinear_split.stp

debugging: path to step output following successful rectilinear pre-split

debug_half_space_failed_to_generate_path

analysis/half_space_fatal/half_space_fatal.stp

debugging: path of failed to generate half space, dumps to step file

debug_failed_to_convert_directory

analysis/failed_to_convert

debugging: each failed decomposition solid will be saved to this directory

debug_save_solid

analysis/solids

debugging: save the solid before attempting to convert

debug_cad_output_verbosity

1

level of debugging output to step files, either 0 for nothing, 1 for printing and 2 for saving to step

debug_logger_verbosity

1

level of debugging output to logger, either 0 for nothing, 1 for repoting issues or 2 for step by step reporting

debug_long_conversion_time

20.0

debug: save output file to stp showing long conversion times above this value (seconds)

debug_long_conversion_time_directory

analysis/long_conversion_time

debuig: output dir for solids with long conversion times

debug_large_number_of_split_solids

50

debug: save output file to stp for solids with large numbers of split solids produced

debug_large_number_of_split_solids_directory

analysis/large_number_of_split_solids

debug: save dir for output of solids with large numbers of split solids

debug_trackback_directory

analysis/trackbacks

debug: save trackback for multiprocessing to text files for each failed solid to this directory

other_nominal_gap

0.0

The command line tool for decomposition can also read in a set of decomposition parameters.

python -m mcio decompose -i my_model.stp -rdp decom_parameters.json