Simulation¶

Introduction¶

Simulation is the top-level object of a mufem analysis. It owns the geometry, the physics models, and the runner that drives execution. It also owns the supporting managers. These managers query coefficients, collect reports, monitor metrics, and export fields.

You create a simulation with the Simulation.New factory. Then you configure it with a runner and one or more models, and run it with run().

Creating a Simulation¶

import mufem

sim = mufem.Simulation.New("My Example", "data/geometry.mesh")

Simulation.New accepts:

Parameter	Description
`name`	Display name of the simulation.
`mesh_path`	Optional path to the mesh file. If omitted, load the mesh later via `sim.get_domain().load_mesh(...)`.
`verbosity_level`	Minimum level of the log messages that mufem prints (`mufem.Verbosity.DEBUG`, `INFO`, `DEFAULT`, `WARNING`, or `ERROR`). The default is `mufem.Verbosity.DEFAULT`.
`mesh_ordering`	Element ordering that mufem applies when it loads `mesh_path` (see Element Ordering). The default is `mufem.MeshOrdering.HILBERT`. mufem ignores this parameter if `mesh_path` is not set.

To show only warnings and errors, and to keep the element order of the mesh file:

sim = mufem.Simulation.New(
    "My Example",
    "data/geometry.mesh",
    verbosity_level=mufem.Verbosity.WARNING,
    mesh_ordering=mufem.MeshOrdering.NONE,
)

Lifecycle¶

A simulation runs in three phases:

Initialization — sim.initialize() prepares the domain, models, materials, and the initial solution. sim.run() calls it automatically, so you rarely call it directly.
Run — sim.run() hands control to the configured runner, which advances the simulation until it completes.
Reset — sim.reset() returns the runner to its starting state so you can replay the simulation.

Accessors¶

The simulation exposes the managers that hold the rest of the state:

Method	Returns
`get_domain()`	The computational domain (mesh, regions).
`get_model_manager()`	Registry of the active physics models.
`get_coefficient_manager()`	Coefficient functions available as inputs to models.
`get_report_manager()`	Reports collected during the run.
`get_monitor_manager()`	Monitors emitted during the run.
`get_field_exporter()`	Field exporter for visualization output.
`get_runner()`	The currently configured runner.
`get_machine()`	Machine context (e.g. MPI process information).
`get_name()`	The simulation name.

Machine¶

sim.get_machine() returns the mufem.Machine object. It gives information about the MPI processes and the hardware:

Method	Returns
`is_main_process()`	`True` on the main MPI process (rank 0).
`is_mpi_build()`	`True` if the mufem build has MPI support.
`number_of_processes()`	Number of MPI processes. The value is 1 for a serial run.
`get_info()`	A multi-line text with the CPU model, the number of physical and logical cores, the maximum clock, the SIMD instruction sets, the cache sizes, the total memory, the NUMA topology, the number of MPI processes, and the GPU (if one is set).

Use mufem.print to print a message on the main process only. For example, to write the hardware information to the log of the case:

mufem.print(sim.get_machine().get_info())

Lifecycle Events¶

Components attach callbacks to Event instances so that work runs at well-defined points in the simulation lifecycle. The most common use configures the field exporter to write at run completion (see Runners and the field exporter documentation).

The built-in events are:

Event	Fires
`Event.Initialization`	Once after `sim.initialize()` completes.
`Event.RunCompletion`	Once when the runner's main loop finishes.
`Event.TimeStep`	At the end of each time step (unsteady runs).
`Event.Iteration`	At the end of each inner iteration.

Two policies are available to thin out a stream of events:

# Fire on every 10th time step.
every_ten = mufem.Event.TimeStep(10)

# Fire when the simulation passes specific times.
checkpoints = mufem.Event.AtTimes([0.1, 0.5, 1.0])

Example¶

import mufem

sim = mufem.Simulation.New("My Example", "data/geometry.mesh")

runner = mufem.SteadyRunner(total_iterations=3)
sim.set_runner(runner)

# Configure models, materials, exports here ...

sim.run()