mcdc.Simulation#

class mcdc.Simulation(name: str = '')#

The complete model and configuration for one MC/DC calculation.

Parameters:

name (str, optional) – User-facing simulation name.

Notes

Geometry, sources, and tallies are supplied with set_model(), set_sources(), and set_tallies(). compile() walks the resulting object graph, assigns IDs, and finalizes object-local and model-wide state before conversion to the packed arrays consumed by mcdc.transport.

MC/DC uses one active simulation context per Python process. A model-object instance belongs to one simulation, although it may be referenced multiple times within that model. Construct independent object graphs and use separate processes for concurrent simulations.

Each simulation owns its execution settings. Access them through simulation.settings by assigning values such as settings.N_particle or by calling configuration methods such as settings.set_eigenmode.

Transport techniques are configured directly on the simulation through methods such as implicit_capture and weight_windows.

Examples

Configure commonly adjusted settings:

>>> import mcdc
>>> simulation = mcdc.Simulation(name="Slab")
>>> simulation.settings.N_particle = 10_000
>>> simulation.settings.N_batch = 20
>>> simulation.settings.rng_seed = 12345
>>> simulation.settings.output_name = "slab"
compile() → None#

Compile and finalize the Python model into a simulation snapshot.

A globally unique compile_ID identifies the snapshot. Command-line overrides are applied before any derived state is resolved. Every embedded or registered MCDCBase reached during compilation records that ID. Object-local hooks discover and prepare their dependencies, then model-wide finalization resolves state that requires the complete simulation.

run() → None#

Compile when needed, execute transport, and write output.

Examples

Run a fully configured simulation:

>>> simulation.run()
set_model(cells: Sequence[Cell]) → None#

Set the root cells that define a complete model (geometry and materials) of the simulation.

Pass only cells that belong directly to the root universe. Do not include cells nested inside subuniverses; they are discovered automatically during model traversal as long as they are reachable through the root cells.

Parameters:

cells (sequence of Cell) – Cells to place in the root universe.

Examples

Attach previously constructed cells:

>>> simulation.set_model([fuel_cell, moderator_cell])
set_sources(sources: Sequence[Source]) → None#

Set particle sources for the simulation.

Parameters:

sources (sequence of Source) – Particle sources to sample during transport.

Examples

Attach previously constructed sources:

>>> simulation.set_sources([volume_source, boundary_source])
set_tallies(tallies: Sequence[Tally]) → None#

Set requested tallies for the simulation.

Parameters:

tallies (sequence of Tally) – Tallies to score during transport.

Examples

Attach previously constructed tallies:

>>> simulation.set_tallies([flux_tally, current_tally])
visualize_model(vis_plane, x, y, z, pixels, colors, time, save_as) → None#

Render a two-dimensional material map of the compiled model.

Parameters are forwarded to mcdc.visualize.visualize_model(). The model is compiled first when necessary.

Examples

Render an x-z slice of the model:

>>> simulation.visualize_model(
...     vis_plane="xz",
...     x=[0.0, 1.0],
...     y=0.0,
...     z=[-0.5, 0.5],
...     pixels=(100, 100),
...     colors=None,
...     time=[0.0],
...     save_as="slab",
... )

Settings

settings.N_particle: int = 0#

Number of particle histories simulated per batch or eigenvalue cycle. The default is 0.

settings.N_batch: int = 1#

Number of statistically independent fixed-source batches. The default is 1.

settings.rng_seed: int = 1#

Seed used to initialize the pseudorandom-number generator. The default is 1.

settings.time_boundary: float = inf#

Time in seconds at which particle transport terminates. The default is infinity.

settings.output_name: str = 'output'#

Base name used for the HDF5 output file. The default is "output".

settings.use_progress_bar: bool = True#

Whether to display transport progress. The default is True.

settings.active_bank_buffer: int = 100#

Additional particle capacity allocated for the active bank. The default is 100.

settings.census_bank_buffer_ratio: float = 2.0#

Capacity multiplier used when allocating the census bank. The default is 2.0.

settings.source_bank_buffer_ratio: float = 2.0#

Capacity multiplier used when allocating the source bank. The default is 2.0.

settings.future_bank_buffer_ratio: float = 1.5#

Capacity multiplier used when allocating the future bank. The default is 1.5.

settings.set_time_census(time, tally_frequency=None)#

Configure census times for time-dependent transport.

Parameters:

  • time (array_like of float) – Positive, nondecreasing census times in seconds. An infinite final census is appended automatically.

  • tally_frequency (int, optional) – Number of tally intervals per census period. A positive value enables census-based tally output.

Examples

Configure explicit census times:

>>> import mcdc
>>> simulation = mcdc.Simulation()
>>> simulation.settings.set_time_census(
...     time=[1.0e-6, 2.0e-6, 5.0e-6],
... )

Enable census-based tallies with ten intervals per census period:

>>> simulation.settings.set_time_census(
...     time=[1.0e-6, 2.0e-6, 5.0e-6],
...     tally_frequency=10,
... )
settings.set_eigenmode(N_inactive=0, N_active=0, k_init=1.0, gyration_radius=None, save_particle=False)#

Enable neutron k-eigenvalue mode.

Parameters:

  • N_inactive (int, optional) – Number of inactive cycles.

  • N_active (int, optional) – Number of active cycles used for statistics.

  • k_init (float, optional) – Initial multiplication-factor estimate.

  • gyration_radius (str, optional) – Gyration-radius mode: "all", "infinite-x", "infinite-y", "infinite-z", "only-x", "only-y", or "only-z".

  • save_particle (bool, optional) – Whether to save source-bank particles.

Examples

Configure a standard eigenvalue calculation:

>>> import mcdc
>>> simulation = mcdc.Simulation()
>>> simulation.settings.set_eigenmode(
...     N_inactive=20,
...     N_active=100,
...     k_init=1.0,
... )

Score the source gyration radius and save source particles:

>>> simulation.settings.set_eigenmode(
...     N_inactive=20,
...     N_active=100,
...     gyration_radius="all",
...     save_particle=True,
... )
settings.set_source_file(source_file_name)#

Use particles from an HDF5 source file.

The particle count is read from the file’s particles_size dataset.

Parameters:

source_file_name (str or path-like) – Source-particle HDF5 file.

Examples

Initialize a simulation from a previously written particle source:

>>> import mcdc
>>> simulation = mcdc.Simulation()
>>> simulation.settings.set_source_file("source.h5")
settings.set_transported_particles(transported_particles: List[str])#

Select the particle species enabled during transport.

Parameters:

transported_particles (list of {"neutron", "electron", "proton"}) – Particle species to enable. Species not listed are disabled.

Examples

Transport neutrons only:

>>> import mcdc
>>> simulation = mcdc.Simulation()
>>> simulation.settings.set_transported_particles(["neutron"])

Enable coupled neutron and electron transport:

>>> simulation.settings.set_transported_particles(
...     ["neutron", "electron"],
... )

Transport techniques

implicit_capture(active: bool = True)#

Configure implicit capture.

Parameters:

active (bool, optional) – Whether implicit capture is enabled.

Examples

Enable implicit capture:

>>> import mcdc
>>> simulation = mcdc.Simulation()
>>> simulation.implicit_capture()

Disable implicit capture:

>>> simulation.implicit_capture(active=False)
weighted_emission(active: bool = True, weight_target: float = 1.0)#

Configure weighted emission.

Parameters:

  • active (bool, optional) – Whether the technique is active.

  • weight_target (float, optional) – Target statistical weight for emitted particles.

Examples

Enable weighted emission with unit target weight:

>>> import mcdc
>>> simulation = mcdc.Simulation()
>>> simulation.weighted_emission(weight_target=1.0)

Select a different target weight:

>>> simulation.weighted_emission(weight_target=0.5)

Disable weighted emission:

>>> simulation.weighted_emission(active=False)
global_weight_roulette(weight_threshold: float = 0.0, weight_target: float = 1.0)#

Enable roulette below a global weight threshold.

Parameters:

  • weight_threshold (float, optional) – Particle weight below which roulette is applied.

  • weight_target (float, optional) – Statistical weight assigned to particles that survive roulette. Must be greater than or equal to weight_threshold.

Examples

Apply roulette below a particle weight of 0.25 and raise surviving particles to unit weight:

>>> import mcdc
>>> simulation = mcdc.Simulation()
>>> simulation.global_weight_roulette(
...     weight_threshold=0.25,
...     weight_target=1.0,
... )

Use a lower target weight:

>>> simulation.global_weight_roulette(
...     weight_threshold=0.1,
...     weight_target=0.5,
... )
weight_windows(weight_windows, mesh=None, energy=None)#

Configure lower, target, and upper particle weights.

Parameters:

  • weight_windows (ndarray, shape (Ne, Nx, Ny, Nz, 3)) – Lower, target, and upper weights in the final dimension. Every lower weight must be positive, and each window must satisfy lower <= target <= upper.

  • mesh (MeshUniform or MeshStructured, optional) – Spatial mesh. The default is one unbounded uniform bin.

  • energy (ndarray, optional) – Strictly increasing energy-group boundaries. The default is one all-energy bin.

Examples

Apply one weight window over all space and energy:

>>> import numpy as np
>>> import mcdc
>>> simulation = mcdc.Simulation()
>>> windows = np.array([0.5, 1.0, 2.0]).reshape(1, 1, 1, 1, 3)
>>> simulation.weight_windows(windows)

Configure weight windows on a uniform spatial mesh:

>>> mesh = mcdc.MeshUniform(x=(-5.0, 1.0, 10))
>>> windows = np.tile([0.25, 0.5, 1.0], (1, 10, 1, 1, 1))
>>> simulation.weight_windows(windows, mesh=mesh)

Configure both energy- and space-dependent windows:

>>> energy = np.array([0.0, 0.625e-6, 20.0])
>>> windows = np.tile([0.25, 0.5, 1.0], (2, 10, 1, 1, 1))
>>> simulation.weight_windows(
...     windows,
...     mesh=mesh,
...     energy=energy,
... )
population_control(active: bool = True)#

Configure source-bank population control.

Parameters:

active (bool, optional) – Whether source-bank population control is enabled.

Examples

Enable source-bank population control:

>>> import mcdc
>>> simulation = mcdc.Simulation()
>>> simulation.population_control()

Disable source-bank population control:

>>> simulation.population_control(active=False)