Runners¶

Introduction¶

Runners drive the progression of a simulation. The simulation hands control to its runner when sim.run() is called; the runner advances state, asks the model manager to iterate, and fires lifecycle events.

Two runners are provided:

mufem.SteadyRunner — stationary problems advanced over a fixed number of iterations.
mufem.UnsteadyRunner — time-dependent problems advanced with finite time steps and inner iterations.

Constructing either runner registers it with the active simulation, but it is good practice to attach it explicitly so the intent is visible in the case file:

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

SteadyRunner¶

runner = mufem.SteadyRunner(total_iterations=5)

Parameter	Description
`total_iterations`	Total number of iterations the runner will perform.

Methods¶

Method	Description
`run()`	Execute the steady-state loop.
`advance(iterations=1)`	Continue past the configured budget by the given number of iterations.
`get_total_iterations()`	The configured iteration budget.

UnsteadyRunner¶

runner = mufem.UnsteadyRunner(
    total_time=1.0,
    time_step_size=0.1,
    total_inner_iterations=3,
)

Parameter	Description
`total_time`	Final physical time.
`time_step_size`	Initial time step size.
`total_inner_iterations`	Number of inner iterations performed at every time step.

Methods¶

Method	Description
`run()`	Execute the time-stepping loop.
`advance(time_steps=1)`	Continue past the configured budget by the given number of time steps.
`get_time()`	Current physical time.
`get_time_step_size()`	Current time step size.
`set_time_step_size(time_step_size)`	Change the time step size for the remaining run.
`get_total_time()`	Final physical time.
`set_total_time(total_time)`	Change the final physical time.

Coefficients¶

Each runner registers progress fields as coefficient functions so they can be queried, exported, or used as inputs to model expressions.

SteadyRunner Fields
Name	Field Type	Description
Iteration [-]	Scalar	Current iteration index of the steady-state loop.

UnsteadyRunner Fields
Name	Field Type	Description
Time [s]	Scalar	Current physical simulation time.
Time Step [-]	Scalar	Index of the current time step.
Iteration [-]	Scalar	Cumulative inner iteration counter across all time steps.

Events¶

Runners fire lifecycle events that other components subscribe to:

Event	SteadyRunner	UnsteadyRunner
`Event.Iteration`	Every iteration.	Every inner iteration.
`Event.TimeStep`	—	End of every time step.
`Event.RunCompletion`	When the loop finishes.	When the loop finishes.

Example¶

import mufem

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

runner = mufem.UnsteadyRunner(
    total_time=1.0,
    time_step_size=0.1,
    total_inner_iterations=3,
)
sim.set_runner(runner)

# Configure models and materials here ...

field_exporter = sim.get_field_exporter()
field_exporter.add_field_output("Time")
field_exporter.add_field_output("Time Step")
field_exporter.set_events(events=[mufem.Event.RunCompletion])

sim.run()