Steps

One or more Steps form the simulation. Steps are executed in consecutive order, have a distinct (physical) runtime, and may contain multiple StepActions. Subsequent Steps inherit StepActions, and they may be updated.

class edelweissfe.steps.base.stepbase.StepBase(number, model, fieldOutputController, journal, jobInfo, solver, outputManagers, stepActions, **kwargs)[source]

Base class for simulation steps.

A step has a specific runtime, holds the StepActions to be executed, and delegates the incrementation to a time stepper, which is created by the concrete step type.

Parameters:

number (int) – The (unique) number of this step.
model (FEModel) – The current state of the model.
fieldOutputController (FieldOutputController) – The FieldOutputController instance for processing results.
journal (Journal) – The Journal instance for logging purposes.
jobInfo (dict) – Additional information about the job.
solver – The solver instance to be used for this step.
outputManagers (list) – The OutputManagers used.
stepActions (dict) – The collection of actions for this step, grouped by action type.
**kwargs – The options for this step.

Methods

`fallBackToCheckpoint`(model, outputManagers, ...)	Continue the step from its latest restart checkpoint, after an increment failed and could not be cut back any further, and cut the increment back from there.
`latestCheckpointOfStep`(restartWriter)	Open the latest restart checkpoint `restartWriter` offers (see `latestCheckpoint()`), if it belongs to this step.
`solve`([resumeFrom])	Solve this step, increment by increment.

fallBackToCheckpoint(model, outputManagers, fallbacksLeft)[source]

Continue the step from its latest restart checkpoint, after an increment failed and could not be cut back any further, and cut the increment back from there.

The increments accepted after the checkpoint are discarded, and the step resumes from the checkpoint exactly as a resumed run does (see ResumeCheckpoint): the model, the time stepper, the solver, the step actions, the output managers and the field outputs take over the checkpointed state, so that the output of the discarded increments is overwritten, not duplicated. The solver ends the abandoned attempt and begins anew from the checkpoint. The retried increments then take a different, smaller path through the same load history. If the increment the checkpoint holds cannot be cut back either, the step falls back further, to the checkpoint before it.

A checkpoint written after the last increment the step accepted holds the state the failed increment started from, from where every increment size down to the minimum has just failed: falling back to it would only retry them. The step goes back to the checkpoint before it instead. With a checkpoint after every accepted increment (writeInterval=1), the latest one always is such a checkpoint.

The checkpoints are those of the step’s restart output, of which there is exactly one, as long as their files hold them – a resumed step’s included: the checkpoint it resumed from, and those before it. Every checkpoint serves one fallback at most: falling back again takes the checkpoint before it, unless newer ones were written since. The step may fall back to checkpoints of its own only, and only as long as its mesh has not changed since (a mesh change cannot be undone).

Parameters:

model (FEModel) – The model tree.
outputManagers (list) – The output managers of the step.
fallbacksLeft (int) – How often the step may still fall back.

Returns:

How often the step may fall back after this.

Return type:

int

Raises:

ReachedMinIncrementSize – If there is no checkpoint of this step left to fall back to, or no fallback is left.
StepFailed – If the mesh has changed since the checkpoint, with a message saying so.

latestCheckpointOfStep(restartWriter)[source]

Open the latest restart checkpoint restartWriter offers (see latestCheckpoint()), if it belongs to this step. The writer’s checkpoints are offered newest first, so once one belongs to an earlier step, all that remain do.

Parameters:: restartWriter – The output manager writing the restart checkpoints of this step.
Returns:: The opened checkpoint, or None if no checkpoint of this step is left.
Return type:: ResumeCheckpoint | None

solve(resumeFrom=None)[source]

Solve this step, increment by increment.

The increment loop, the same for every solver:

begin the step
while the step is not finished:
    prepare the increment     topology update when due
    propose an increment      time stepper
    attempt it                solver; if it fails: reject it, retry smaller
                              (at the minimum size: fall back to a checkpoint, if allowed)
    accept it                 solver, then time stepper
    write output              field outputs, output managers, restart checkpoint last
end the step

A restart checkpoint is written after an accepted increment, as the last output, so it holds exactly the state the next increment starts from – and a resumed step simply continues this loop. It begins like any step, and then takes over the checkpointed state, in this one place.

An increment that fails at the minimum increment size fails the step, unless the step may fall back to a checkpoint (maxCheckpointFallbacks, see fallBackToCheckpoint()): it then continues from its latest restart checkpoint, as a resumed step would, with a smaller increment.

Parameters:: resumeFrom – The ResumeCheckpoint this step continues from, or None.

length: The duration of the step.

number: The (unique) number of the step.

class edelweissfe.steps.base.stepbase.StepIncrementationSchema(stepLength=1.0, startInc=1.0, maxInc=1.0, minInc=0.0001, maxNumInc=1000, maxIter=10, criticalIter=5, maxGrowIter=10, cutbackFactor=0.25, increaseFactor=1.1, goodIncrementsBeforeIncrease=3, makeZeroIncrementFirst=True, maxCheckpointFallbacks=0)[source]

The standard incrementation options common to every step type (*step keyword datalines), owned by this module and never mutated from outside it.

Every concrete StepBase subclass shares exactly this option set – there is no per-step-type variation – so it is declared once here rather than once per step type.

Parameters:

stepLength (float)
startInc (float)
maxInc (float)
minInc (float)
maxNumInc (int)
maxIter (int)
criticalIter (int)
maxGrowIter (int)
cutbackFactor (float)
increaseFactor (float)
goodIncrementsBeforeIncrease (int)
makeZeroIncrementFirst (bool)
maxCheckpointFallbacks (int)

Increment control of adaptive steps

An adaptive step cuts the increment back by cutbackFactor when an increment fails, and grows it by increaseFactor once goodIncrementsBeforeIncrease good increments have passed, counted from the step start (the zero increment included) or from the last cutback, which itself counts as one; after that, every further good increment lets the next one grow. With goodIncrementsBeforeIncrease=1 the increment grows again right after the increment retried after a cutback. An increment that needed at least criticalIter iterations does not let the next one grow. The defaults (increaseFactor=1.1, goodIncrementsBeforeIncrease=3) recover slowly from a cutback: from a quarter of the previous size it takes about 17 increments to get back. In softening problems with frequent cutbacks, a faster growth is usually much cheaper, with criticalIter keeping the increment from growing while Newton struggles, e.g.:

*step, solver=theSolver
maxInc=5e-3, minInc=1e-6, maxIter=25, criticalIter=10, increaseFactor=1.5, goodIncrementsBeforeIncrease=1

An adaptive step begins with an increment of size zero, which brings the model into equilibrium with the state the step starts from before time advances. makeZeroIncrementFirst=False leaves it out, e.g. for a model whose entities integrate in time and cannot be evaluated over a time increment of zero. The zero increment cannot be cut back: if it fails, the step fails. Any other increment, including a first increment of nonzero size, is cut back when it fails. An explicit step (AdaptiveStepForExplicitSimulations) always begins with the zero increment, in which the explicit solver builds its initial state, and refuses makeZeroIncrementFirst=False.

Falling back to a restart checkpoint

An increment that fails at the minimum increment size minInc fails the step, and so does a failing last increment of the step that is smaller than minInc already, the remainder of the step. With maxCheckpointFallbacks=n, the step instead goes back to its latest restart checkpoint and continues from there with an increment cut back by cutbackFactor, at most n times:

*output, type=restart, name=restart
writeInterval=5, baseName=restart, numberOfFilesToKeep=3

*step, solver=theSolver
maxInc=1e-2, minInc=1e-6, maxCheckpointFallbacks=3

The increments accepted after the checkpoint are discarded, and the step continues exactly as a run resumed from that checkpoint would (see Restart), with the one difference that its next increment is smaller. Their output is replaced: field output exports are cut back to the checkpoint, and the Ensight sequence continues from it. Path dependent materials (plasticity, damage) then follow a different, finer path through the same load history, which may pass where the coarser one got stuck. If the increment the checkpoint holds cannot be cut back either, the step goes back to the checkpoint before it.

The checkpoints are those of the restart output, of which the job must define exactly one: with none, or several, the step refuses to start. A resumed run may go back to the checkpoint it resumed from, and to the ones the interrupted run wrote before it, as long as their files still hold them.
The step does not go back to a checkpoint that holds the state the failed increment started from, i.e., one written after the last increment it accepted: from there, every increment size down to minInc has just failed. It goes back to the checkpoint before it instead. With writeInterval=1, the latest checkpoint always is such a one, so a fallback goes back at least one increment before the failed one.
Every checkpoint serves one fallback: falling back again takes the checkpoint before it, unless the step has written newer ones since. How far back the step can go is set by writeInterval and numberOfFilesToKeep of the restart output.
The step falls back to checkpoints of its own only, never into an earlier step: a failed zero increment, or a failure before the step has written a checkpoint after its zero increment, still fails the step.
A mesh change cannot be undone, so a step whose mesh has changed since the checkpoint (e.g. by adaptive refinement) cannot go back to it, nor to any older one, and fails, naming the checkpoint and the mesh change it predates. A step with adaptive refinement can fall back only to checkpoints written after its last refinement.
Each fallback is reported, together with the performance timing of the discarded part of the step.

`AdaptiveStep` - A classical adpative step for transient simulations

class edelweissfe.steps.adaptivestep.AdaptiveStep(number, model, fieldOutputController, journal, jobInfo, solver, outputManagers, stepActions, **kwargs)[source]

An adaptive incremental step to be used in nonlinear simulations with implicit time integration.

Methods

`fallBackToCheckpoint`(model, outputManagers, ...)	Continue the step from its latest restart checkpoint, after an increment failed and could not be cut back any further, and cut the increment back from there.
`latestCheckpointOfStep`(restartWriter)	Open the latest restart checkpoint `restartWriter` offers (see `latestCheckpoint()`), if it belongs to this step.
`schema`	Option schema for this step; all step types share the same incrementation options.
`solve`([resumeFrom])	Solve this step, increment by increment.

Parameters:

number (int)
model (FEModel)
fieldOutputController (FieldOutputController)
journal (Journal)
jobInfo (dict)
outputManagers (list)
stepActions (dict)

schema

Option schema for this step; all step types share the same incrementation options.

alias of StepIncrementationSchema

`AdaptiveStepForExplicitSimulations` - An adaptive step for explicit simulations

class edelweissfe.steps.adaptivestepforexplicitsimulations.AdaptiveStepForExplicitSimulations(number, model, fieldOutputController, journal, jobInfo, solver, outputManagers, stepActions, **kwargs)[source]

An adaptive incremental step to be used in nonlinear simulations with explicit time integration.

It always begins with the zero increment, in which the explicit solver builds its initial state before time advances (see SimpleTimeStepper), and refuses makeZeroIncrementFirst=False.

Methods

`fallBackToCheckpoint`(model, outputManagers, ...)	Continue the step from its latest restart checkpoint, after an increment failed and could not be cut back any further, and cut the increment back from there.
`latestCheckpointOfStep`(restartWriter)	Open the latest restart checkpoint `restartWriter` offers (see `latestCheckpoint()`), if it belongs to this step.
`schema`	Option schema for this step, per OptionSchemaProvider.
`solve`([resumeFrom])	Solve this step, increment by increment.

Parameters:

number (int)
model (FEModel)
fieldOutputController (FieldOutputController)
journal (Journal)
jobInfo (dict)
outputManagers (list)
stepActions (dict)

schema

Option schema for this step, per OptionSchemaProvider. Shared with AdaptiveStep – see that class’s own docstring.

alias of StepIncrementationSchema

Steps

Increment control of adaptive steps

Falling back to a restart checkpoint

AdaptiveStep - A classical adpative step for transient simulations

AdaptiveStepForExplicitSimulations - An adaptive step for explicit simulations

`AdaptiveStep` - A classical adpative step for transient simulations

`AdaptiveStepForExplicitSimulations` - An adaptive step for explicit simulations