openmc.model.Model

class openmc.model.Model(geometry=None, materials=None, settings=None, tallies=None, plots=None)[source]

Model container.

This class can be used to store instances of openmc.Geometry, openmc.Materials, openmc.Settings, openmc.Tallies, and openmc.Plots, thus making a complete model. The Model.export_to_xml() method will export XML files for all attributes that have been set. If the Model.materials attribute is not set, it will attempt to create a materials.xml file based on all materials appearing in the geometry.

Changed in version 0.13.0: The model information can now be loaded in to OpenMC directly via openmc.lib

Parameters
Variables
apply_tally_results(statepoint: str | os.PathLike | openmc.statepoint.StatePoint)[source]

Apply results from a statepoint to tally objects on the Model

Parameters

statepoint (PathLike or openmc.StatePoint) – Statepoint file used to update tally results

calculate_volumes(threads=None, output=True, cwd='.', openmc_exec='openmc', mpi_args=None, apply_volumes=True, export_model_xml=True, **export_kwargs)[source]

Runs an OpenMC stochastic volume calculation and, if requested, applies volumes to the model

New in version 0.13.0.

Parameters

  • threads (int, optional) – Number of OpenMP threads. If OpenMC is compiled with OpenMP threading enabled, the default is implementation-dependent but is usually equal to the number of hardware threads available (or a value set by the OMP_NUM_THREADS environment variable). This currenty only applies to the case when not using the C API.

  • output (bool, optional) – Capture OpenMC output from standard out

  • openmc_exec (str, optional) – Path to OpenMC executable. Defaults to ‘openmc’. This only applies to the case when not using the C API.

  • mpi_args (list of str, optional) – MPI execute command and any additional MPI arguments to pass, e.g. [‘mpiexec’, ‘-n’, ‘8’]. This only applies to the case when not using the C API.

  • cwd (str, optional) – Path to working directory to run in. Defaults to the current working directory.

  • apply_volumes (bool, optional) – Whether apply the volume calculation results from this calculation to the model. Defaults to applying the volumes.

  • export_model_xml (bool, optional) – Exports a single model.xml file rather than separate files. Defaults to True.

  • **export_kwargs – Keyword arguments passed to either Model.export_to_model_xml() or Model.export_to_xml().

deplete(timesteps, method='cecm', final_step=True, operator_kwargs=None, directory='.', output=True, **integrator_kwargs)[source]

Deplete model using specified timesteps/power

Changed in version 0.13.0: The final_step, operator_kwargs, directory, and output arguments were added.

Parameters

  • timesteps (iterable of float) – Array of timesteps in units of [s]. Note that values are not cumulative.

  • method (str, optional) – Integration method used for depletion (e.g., ‘cecm’, ‘predictor’). Defaults to ‘cecm’.

  • final_step (bool, optional) – Indicate whether or not a transport solve should be run at the end of the last timestep. Defaults to running this transport solve.

  • operator_kwargs (dict) – Keyword arguments passed to the depletion operator initializer (e.g., openmc.deplete.Operator())

  • directory (str, optional) – Directory to write XML files to. If it doesn’t exist already, it will be created. Defaults to the current working directory

  • output (bool) – Capture OpenMC output from standard out

  • integrator_kwargs (dict) – Remaining keyword arguments passed to the depletion Integrator initializer (e.g., openmc.deplete.integrator.cecm()).

differentiate_depletable_mats(diff_volume_method: str = None)[source]

Assign distribmats for each depletable material

New in version 0.14.0.

Changed in version 0.15.1: diff_volume_method default is None, do not set volumes on the new material ovjects. Is now a convenience method for differentiate_mats(diff_volume_method, depletable_only=True)

Parameters

diff_volume_method (str) – Specifies how the volumes of the new materials should be found. - None: Do not assign volumes to the new materials (Default) - ‘divide equally’: Divide the original material volume equally between the new materials - ‘match cell’: Set the volume of the material to the volume of the cell they fill

differentiate_mats(diff_volume_method: str = None, depletable_only: bool = True)[source]

Assign distribmats for each material

New in version 0.15.1.

Parameters

  • diff_volume_method (str) – Specifies how the volumes of the new materials should be found. - None: Do not assign volumes to the new materials (Default) - ‘divide equally’: Divide the original material volume equally between the new materials - ‘match cell’: Set the volume of the material to the volume of the cell they fill

  • depletable_only (bool) – Default is True, only depletable materials will be differentiated. If False, all materials will be differentiated.

export_to_model_xml(path: str | os.PathLike = 'model.xml', remove_surfs: bool = False, nuclides_to_ignore: collections.abc.Iterable[str] | None = None)[source]

Export model to a single XML file.

New in version 0.13.3.

Parameters

  • path (str or PathLike) – Location of the XML file to write (default is ‘model.xml’). Can be a directory or file path.

  • remove_surfs (bool) – Whether or not to remove redundant surfaces from the geometry when exporting.

  • nuclides_to_ignore (list of str) – Nuclides to ignore when exporting to XML.

export_to_xml(directory: str | os.PathLike = '.', remove_surfs: bool = False, nuclides_to_ignore: collections.abc.Iterable[str] | None = None)[source]

Export model to separate XML files.

Parameters

  • directory (str) – Directory to write XML files to. If it doesn’t exist already, it will be created.

  • remove_surfs (bool) –

    Whether or not to remove redundant surfaces from the geometry when exporting.

    New in version 0.13.1.

  • nuclides_to_ignore (list of str) – Nuclides to ignore when exporting to XML.

finalize_lib()[source]

Finalize simulation and free memory allocated for the C API

New in version 0.13.0.

classmethod from_model_xml(path='model.xml')[source]

Create model from single XML file

New in version 0.13.3.

Parameters

path (str or PathLike) – Path to model.xml file

classmethod from_xml(geometry='geometry.xml', materials='materials.xml', settings='settings.xml', tallies='tallies.xml', plots='plots.xml') → Model[source]

Create model from existing XML files

Parameters

  • geometry (str) – Path to geometry.xml file

  • materials (str) – Path to materials.xml file

  • settings (str) – Path to settings.xml file

  • tallies (str) –

    Path to tallies.xml file

    New in version 0.13.0.

  • plots (str) –

    Path to plots.xml file

    New in version 0.13.0.

Returns

Model created from XML files

Return type

openmc.model.Model

import_properties(filename)[source]

Import physical properties

Changed in version 0.13.0: This method now updates values as loaded in memory with the C API

Parameters

filename (str) – Path to properties HDF5 file

See also

openmc.lib.export_properties

init_lib(threads=None, geometry_debug=False, restart_file=None, tracks=False, output=True, event_based=None, intracomm=None)[source]

Initializes the model in memory via the C API

New in version 0.13.0.

Parameters

  • threads (int, optional) – Number of OpenMP threads. If OpenMC is compiled with OpenMP threading enabled, the default is implementation-dependent but is usually equal to the number of hardware threads available (or a value set by the OMP_NUM_THREADS environment variable).

  • geometry_debug (bool, optional) – Turn on geometry debugging during simulation. Defaults to False.

  • restart_file (str, optional) – Path to restart file to use

  • tracks (bool, optional) – Enables the writing of particles tracks. The number of particle tracks written to tracks.h5 is limited to 1000 unless Settings.max_tracks is set. Defaults to False.

  • output (bool) – Capture OpenMC output from standard out

  • event_based (None or bool, optional) – Turns on event-based parallelism if True. If None, the value in the Settings will be used.

  • intracomm (mpi4py.MPI.Intracomm or None, optional) – MPI intracommunicator

plot(origin: collections.abc.Sequence[float] | None = None, width: collections.abc.Sequence[float] | None = None, pixels: int | collections.abc.Sequence[int] = 40000, basis: str = 'xy', color_by: str = 'cell', colors: dict | None = None, seed: int | None = None, openmc_exec: str | os.PathLike = 'openmc', axes=None, legend: bool = False, axis_units: str = 'cm', outline: bool | str = False, show_overlaps: bool = False, overlap_color: collections.abc.Sequence[int] | str | None = None, n_samples: int | None = None, plane_tolerance: float = 1.0, legend_kwargs: dict | None = None, source_kwargs: dict | None = None, contour_kwargs: dict | None = None, **kwargs)[source]

Display a slice plot of the model.

New in version 0.15.1.

Parameters

  • origin (iterable of float) – Coordinates at the origin of the plot. If left as None, the center of the bounding box will be used to attempt to ascertain the origin with infinite values being replaced by 0.

  • width (iterable of float) – Width of the plot in each basis direction. If left as none then the width of the bounding box will be used to attempt to ascertain the plot width. Defaults to (10, 10) if the bounding box contains inf values.

  • pixels (Iterable of int or int) – If iterable of ints provided then this directly sets the number of pixels to use in each basis direction. If int provided then this sets the total number of pixels in the plot and the number of pixels in each basis direction is calculated from this total and the image aspect ratio.

  • basis ({'xy', 'xz', 'yz'}) – The basis directions for the plot

  • color_by ({'cell', 'material'}) – Indicate whether the plot should be colored by cell or by material

  • colors (dict) –

    Assigns colors to specific materials or cells. Keys are instances of Cell or Material and values are RGB 3-tuples, RGBA 4-tuples, or strings indicating SVG color names. Red, green, blue, and alpha should all be floats in the range [0.0, 1.0], for example:

    # Make water blue
water = openmc.Cell(fill=h2o)
universe.plot(..., colors={water: (0., 0., 1.))

  • seed (int) – Seed for the random number generator

  • openmc_exec (str) – Path to OpenMC executable.

  • axes (matplotlib.Axes) –

    Axes to draw to

    New in version 0.13.1.

  • legend (bool) –

    Whether a legend showing material or cell names should be drawn

    New in version 0.14.0.

  • axis_units ({'km', 'm', 'cm', 'mm'}) –

    Units used on the plot axis

    New in version 0.14.0.

  • outline (bool or str) –

    Whether outlines between color boundaries should be drawn. If set to ‘only’, only outlines will be drawn.

    New in version 0.14.0.

  • show_overlaps (bool) – Indicate whether or not overlapping regions are shown. Default is False.

  • overlap_color (Iterable of int or str) – Color to apply to overlapping regions. Default is red.

  • n_samples (int, optional) – The number of source particles to sample and add to plot. Defaults to None which doesn’t plot any particles on the plot.

  • plane_tolerance (float) – When plotting a plane the source locations within the plane +/- the plane_tolerance will be included and those outside of the plane_tolerance will not be shown

  • legend_kwargs (dict) –

    Keyword arguments passed to matplotlib.pyplot.legend().

    New in version 0.14.0.

  • source_kwargs (dict, optional) – Keyword arguments passed to matplotlib.pyplot.scatter().

  • contour_kwargs (dict, optional) – Keyword arguments passed to matplotlib.pyplot.contour().

  • **kwargs – Keyword arguments passed to matplotlib.pyplot.imshow().

Returns

Axes containing resulting image

Return type

matplotlib.axes.Axes

plot_geometry(output=True, cwd='.', openmc_exec='openmc', export_model_xml=True, **export_kwargs)[source]

Creates plot images as specified by the Model.plots attribute

New in version 0.13.0.

Parameters

  • output (bool, optional) – Capture OpenMC output from standard out

  • cwd (str, optional) – Path to working directory to run in. Defaults to the current working directory.

  • openmc_exec (str, optional) – Path to OpenMC executable. Defaults to ‘openmc’. This only applies to the case when not using the C API.

  • export_model_xml (bool, optional) – Exports a single model.xml file rather than separate files. Defaults to True.

  • **export_kwargs – Keyword arguments passed to either Model.export_to_model_xml() or Model.export_to_xml().

rotate_cells(names_or_ids, vector)[source]

Rotate the identified cell(s) by the specified rotation vector. The rotation is only applied to cells filled with a universe.

Note

If applying this change to a name that is not unique, then the change will be applied to all objects of that name.

New in version 0.13.0.

Parameters

  • names_or_ids (Iterable of str or int) – The cell names (if str) or id (if int) that are to be translated or rotated. This parameter can include a mix of names and ids.

  • vector (Iterable of float) – The rotation vector of length 3 to apply. This array specifies the angles in degrees about the x, y, and z axes, respectively.

run(particles=None, threads=None, geometry_debug=False, restart_file=None, tracks=False, output=True, cwd='.', openmc_exec='openmc', mpi_args=None, event_based=None, export_model_xml=True, apply_tally_results=False, **export_kwargs)[source]

Run OpenMC

If the C API has been initialized, then the C API is used, otherwise, this method creates the XML files and runs OpenMC via a system call. In both cases this method returns the path to the last statepoint file generated.

Changed in version 0.12: Instead of returning the final k-effective value, this function now returns the path to the final statepoint written.

Changed in version 0.13.0: This method can utilize the C API for execution

Parameters

  • particles (int, optional) – Number of particles to simulate per generation.

  • threads (int, optional) – Number of OpenMP threads. If OpenMC is compiled with OpenMP threading enabled, the default is implementation-dependent but is usually equal to the number of hardware threads available (or a value set by the OMP_NUM_THREADS environment variable).

  • geometry_debug (bool, optional) – Turn on geometry debugging during simulation. Defaults to False.

  • restart_file (str or PathLike) – Path to restart file to use

  • tracks (bool, optional) – Enables the writing of particles tracks. The number of particle tracks written to tracks.h5 is limited to 1000 unless Settings.max_tracks is set. Defaults to False.

  • output (bool, optional) – Capture OpenMC output from standard out

  • cwd (PathLike, optional) – Path to working directory to run in. Defaults to the current working directory.

  • openmc_exec (str, optional) – Path to OpenMC executable. Defaults to ‘openmc’.

  • mpi_args (list of str, optional) – MPI execute command and any additional MPI arguments to pass, e.g. [‘mpiexec’, ‘-n’, ‘8’].

  • event_based (None or bool, optional) – Turns on event-based parallelism if True. If None, the value in the Settings will be used.

  • export_model_xml (bool, optional) –

    Exports a single model.xml file rather than separate files. Defaults to True.

    New in version 0.13.3.

  • apply_tally_results (bool) –

    Whether to apply results of the final statepoint file to the model’s tally objects.

    New in version 0.15.1.

  • **export_kwargs – Keyword arguments passed to either Model.export_to_model_xml() or Model.export_to_xml().

Returns

Path to the last statepoint written by this run (None if no statepoint was written)

Return type

Path

sample_external_source(n_samples: int = 1000, prn_seed: int | None = None, **init_kwargs) → ParticleList[source]

Sample external source and return source particles.

New in version 0.15.1.

Parameters

  • n_samples (int) – Number of samples

  • prn_seed (int) – Pseudorandom number generator (PRNG) seed; if None, one will be generated randomly.

  • **init_kwargs – Keyword arguments passed to openmc.lib.init()

Returns

List of samples source particles

Return type

openmc.ParticleList

sync_dagmc_universes()[source]

Synchronize all DAGMC universes in the current geometry.

This method iterates over all DAGMC universes in the geometry and synchronizes their cells with the current material assignments. Requires that the model has been initialized via Model.init_lib().

New in version 0.15.1.

translate_cells(names_or_ids, vector)[source]

Translate the identified cell(s) by the specified translation vector. The translation is only applied to cells filled with a universe.

Note

If applying this change to a name that is not unique, then the change will be applied to all objects of that name.

New in version 0.13.0.

Parameters

  • names_or_ids (Iterable of str or int) – The cell names (if str) or id (if int) that are to be translated or rotated. This parameter can include a mix of names and ids.

  • vector (Iterable of float) – The translation vector of length 3 to apply. This array specifies the x, y, and z dimensions of the translation.

update_cell_temperatures(names_or_ids, temperature)[source]

Update the temperature of a set of cells to the given value

Note

If applying this change to a name that is not unique, then the change will be applied to all objects of that name.

New in version 0.13.0.

Parameters

  • names_or_ids (Iterable of str or int) – The cell names (if str) or id (if int) that are to be updated. This parameter can include a mix of names and ids.

  • temperature (float) – The temperature to apply in units of Kelvin

update_densities(names_or_ids, density, density_units='atom/b-cm')[source]

Update the density of a given set of materials to a new value

Note

If applying this change to a name that is not unique, then the change will be applied to all objects of that name.

New in version 0.13.0.

Parameters

  • names_or_ids (Iterable of str or int) – The material names (if str) or id (if int) that are to be updated. This parameter can include a mix of names and ids.

  • density (float) – The density to apply in the units specified by density_units

  • density_units ({'atom/b-cm', 'g/cm3'}, optional) – Units for density. Defaults to ‘atom/b-cm’

update_material_volumes(names_or_ids, volume)[source]

Update the volume of a set of materials to the given value

Note

If applying this change to a name that is not unique, then the change will be applied to all objects of that name.

New in version 0.13.0.

Parameters

  • names_or_ids (Iterable of str or int) – The material names (if str) or id (if int) that are to be updated. This parameter can include a mix of names and ids.

  • volume (float) – The volume to apply in units of cm^3