Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Mechanics, circulation and output

Mechanics problems

simcardemsx uses pulse’s problems unmodified, with the activation backend as the active model of the pulse.CardiacModel:

Solver options belong to whoever builds the problem. The examples tighten pulse’s absolute Newton tolerance snes_atol to 1e-9. At resting calcium the first residual is already at round-off, which a purely relative tolerance cannot reduce further.

A DynamicProblem’s own time step, parameters["dt"], is in seconds and compiled into the form. The controller refuses a problem whose time step differs from dt_mech.

Mechanics drivers

The controller never calls problem.solve() itself. It calls advance(t_n, dt), in ms, on a mechanics driver (simcardemsx.mechanics). The driver says how one mechanics step is taken:

DriverUse it for
Solve(problem)A plain solve. A bare problem passed to the controller is wrapped in this
CirculationClock(problem, …)A closed-loop circulation solved with the mechanics. Sets the circuit’s own clock, in the .ode file’s time unit
Cycle(controller)An open-loop cardiac cycle run by pulse.cycle.CycleController, which is in SI units

Closed loop

pulse.circulation.GotranxCirculation solves Regazzoni’s 0D circulation model in the same Newton system as the displacement. Each 3D cavity replaces the corresponding chamber of the circuit. Its volume is the volume of the deformed cavity, and its pressure is the Lagrange multiplier of the constraint. Blood goes round the loop, the total volume is conserved, and each beat starts where the last one left the circuit. The BiV example runs one beat.

Open loop

A controlled cavity (pulse.problem.CavityControl) has one pressure unknown whose equation can be switched at run time: a prescribed volume, a prescribed pressure, or a pressure tied to the volume as in a Windkessel. pulse.cycle.CycleController switches each cavity through preload, isovolumic contraction, ejection, isovolumic relaxation and filling. Ejected blood leaves the model, and filling is prescribed. The Rodero example runs one beat.

The cavity multiplier is the wall pressure only when the cavity surface is closed, or when its open rim stays in a plane through the origin. Close an open base with valve plugs or constrain it.

Rollback and checkpoints

Every component that carries state from one step to the next is checkpointable (simcardemsx.checkpoint.Checkpointable): EP’s states, the transfer arrays, the mechanics problem, the cycle controller and the backend. What a beat, pulse or crossbridge object must save is listed by that library’s own restart API.

from simcardemsx.checkpoint import Checkpointer

checkpointer = Checkpointer(controller, outdir, physics=settings)
...
checkpointer.write()  # between steps

# later, in a new process, after building the same objects:
t = checkpointer.restore()

physics is a dictionary of everything that defines the physics, and its hash is stored with the checkpoint. A restore refuses a checkpoint written with other physics, so a restart can change the run’s length, output and solver options, but nothing else. Under pulse’s default direct solver a restarted run continues bit for bit. With a lagged preconditioner, whose factorization cannot be saved, it agrees with the uninterrupted run to within the solver tolerances.

Results

simcardemsx.results writes output in the layout of the pulse and beat command-line tools:

FileContents
config.resolved.tomlEvery setting of the run
results.bpFields over time (ResultsWriter), readable by ParaView and read_results
log.csvOne row per step (CsvLog)
restart.bp, restart.jsonThe latest checkpoint
run.jsonHow the run ended, with the software versions and git commit (simcardemsx.provenance)
timings.jsonWhere the time went

prepare_output(folder, restart=..., overwrite=...) refuses to write into a folder that already holds results, unless the run is a restart of the same physics or is told to overwrite them. The applications all use this layout, and each has a post.py that replots a finished run from these files.