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
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.
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:
Inexact edges on connected 2nd order faces, particularly cylinders joined at an angle
Rounding errors in coincident surface
Rounding errors introduced during the splitting / cut / common operations in OCP
Overlapping geometry
Failure to generate correct void space
Incorrect auxiliary surface generation
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