Outputmanagers

Outputmanagers are used for monitoring and exporting results to variuous formats. They are defined globally:

*output, type=ensight, jobName=cps4job, name=myEnsightExport
    create=perNode,    elSet=all, fieldOutput=Displacement
    create=perElement, elSet=all, fieldOutput=Stress
    create=perElement, elSet=all, fieldOutput=Strain

Full example: testfiles/marmot/OutputManagers/test.inp

*material, name=VonMises, id=mat
210000, 0.3, 550, 1000, 200, 1400

*section, name=section1, thickness=1.0, material=mat, type=plane
all

*job, name=cps4job, domain=2d
*solver, solver=NIST, name=theSolver

*modelGenerator, generator=planeRectQuad, name=gen
x0=0, l=50
y0=0, h=100
elType=CPS4
nX=25
nY=50

*fieldOutput
>>perNode, name=Displacement, elSet=all, field=displacement, result=U,
>>perElement, name=Stress, elSet=all, result=stress, quadraturePoint=1
>>perElement, name=Strain, elSet=all, result=strain, quadraturePoint=1
>>perElement, name=Kappa, elSet=all, result=kappa, quadraturePoint=1
>>perNode, name=Displacement_Top, nSet=gen_top, field=displacement, result=U
>>perNode, name=Force_Bottom, nSet=gen_bottom, field=displacement, result=P, saveHistory=True, export=ReactionForce, f_export(x)='x[:,:,1]'

*output, type=ensight, name=myEnsightExport
>>perNode,    fieldOutput=Displacement
>>perElement, fieldOutput=Stress
>>perElement, fieldOutput=Strain
>>perElement, fieldOutput=Kappa
>>configuration, overwrite=yes

*output, type=monitor, name=myNodeSetMonitor
fieldOutput=Displacement_Top, f(x)='mean(x[:,1])'
fieldOutput=Force_Bottom, f(x)='sum(x[:,1])'

*output, type=plotAlongPath, name=myNodeSetPlotter
fieldOutput=Displacement_Top, label=Ualongtopsurface, f(x)='x[:,1]', nStages=5, export=Ualongtopsurface_distances.csv

*step, solver=theSolver
maxInc=1e-1, minInc=1e-8, maxNumInc=1000, maxIter=25, stepLength=100
>>options, name=myEnsightExport, intermediateSaveInterval=2, minDTForOutput=20
>>options, name=theSolver, extrapolation=linear
>>dirichlet, name=1,          nSet=gen_leftBottom,    field=displacement, 2=0.0, 1=0.0
>>dirichlet, name=bottom,     nSet=gen_bottom,        field=displacement, 2=0
>>nodeforces, name=top,       nSet=gen_top,           field=displacement, 2=-1, f(t)=t**2

`ensight` - Export to Ensight Gold format

Options:
Option	Type / Default	Description
`perNode`	tuple, default=()	Node-based Ensight export.
`perElement`	tuple, default=()	Element-based Ensight export.
`configuration`	tuple, default=()
`intermediateSaveInterval`	int, default=None	Set the intermediate save interval for the Ensight export. Not writing it leaves whatever the ‘>>configuration’ block set (or its own default) in place.
`minDTForOutput`	float, default=None	Set the minimum time between two Ensight exports. Not writing it leaves no minimum in place.

Keyword: perNode
Option	Type / Default	Description
`fieldOutput`	str (required)	Name of the result, defined on an elSet (also for perNode results!)

Keyword: perElement
Option	Type / Default	Description
`fieldOutput`	str (required)	Name of the result, defined on an elSet (also for perNode results!)

Keyword: configuration
Option	Type / Default	Description
`overwrite`	bool, default=False	Overwrite results.
`intermediateSaveInterval`	int, default=10	Set intermediate save interval.
`elSet`	str, default=None	Element set.
`nSet`	str, default=None	Node set.
`transient`	bool, default=True	Set transient ensight output.

`monitor` - Monitor quantities in the terminal

Options:
Option	Type / Default	Description
`fieldOutput`	str (required)	Name of the field output to monitor.
`label`	str, default=’Monitor’	Name of the output manager.
`f(x)`	str, default=None	Apply a model accessible function on the result.

`meshplot` - Export to matplotlib

@author: Magdalena

Module meshplot divided into classes:

Triangulation:
creates triangles out of rectangles in order to use matplotlib plotting options
Plotter:
creates figures, axes, grid, labels
Outputmanager:
creates the plotting specific for the defined keyword lines

Options:
Option	Type / Default	Description
`jobs`	tuple, default=()	The plotting jobs, one or more per dataline.

`fractureenergyintegrator` - Determine the fracture energy

Options:
Option	Type / Default	Description
`forceFieldOutput`	str (required)	fieldOutput for force (with time history).
`displacementFieldOutput`	str (required)	fieldOutput for displacement (with time history).
`f(x)`	str, default=’1’	Apply a model accessible function on the result.

`plotalongpath` - Plot a result along a line

Options:
Option	Type / Default	Description
`fieldOutput`	str (required)	Name of the field output.
`figure`	int, default=1	Figure of the plotter.
`axSpec`	int, default=111	AxSpec (MATLAB syntax) in the figure.
`normalize`	int, default=111	Normalize results.
`label`	str, default=None	Label.
`f(x)`	str, default=None	Function to apply in each increment.
`nStages`	int, default=1
`export`	str, default=None	Export the field output to a file at the end of the job.

`conditionalstop` - Conditional stop if expression becomes true

Options:
Option	Type / Default	Description
`stop`	str (required)	Model accessible function describing the stop condition.

`statusfile` - Write the status of the simulation to a file

Options:
Option	Type / Default	Description
`filename`	str, default=’job.sta’	Name of the output manager.

`meshdatatofile` - Write the (generated) mesh data to a file

Options:
Option	Type / Default	Description
`filename`	str, default=None	Name of file for writing output.

`computetimemonitor` - Print and write compute times per increment

Options:
Option	Type / Default	Description
`export`	str, default=None	Provide a filename to export the results.

`restart` - Write restart checkpoints during the analysis

Options:
Option	Type / Default	Description
`writeInterval`	int, default=1	write a checkpoint every N converged increments
`baseName`	str, default=’restart’	base file name for restart checkpoints
`numberOfFilesToKeep`	int, default=3	number of most recent restart checkpoints to keep (ring buffer)

Checkpoint file layout

The layout of a checkpoint – what is written, and how a resumed run reads it back – lives in one module, used by this output manager for writing and by the driver for resuming (*restart, readFrom=).

Restart checkpoints: the one place that knows how a checkpoint file is laid out.

A checkpoint is an HDF5 file holding

the attribute stepNumber, the step the run was in, and numberOfIncrementsDone, how many increments of it were accepted;
the model’s state, written by writeRestart();
groups timestepper and solver with the time stepper’s and the solver’s state;
a group stepActions with the state of every step action, by type and name – including what the steps before carried over, e.g. an accumulated load, and whether an action is still active;
a group outputManagers with the state of every output manager of the step, by name;
a group fieldOutputs with the history of every field output, and how much of its export file belongs to the run.

Every component other than the model hands over its state as a mapping of arrays, through getRestartData and setRestartData; most just declare which of their attributes it is (see checkpointedstate).

writeCheckpoint() writes one, the restart output manager calls it; ResumeCheckpoint reads one back, the driver uses it.

class edelweissfe.utils.checkpoint.ResumeCheckpoint(fileName)[source]

A restart checkpoint opened for resuming a run, restored piece by piece as the run is set up.

The pieces are restored at different moments, because the objects they belong to are created at different moments: the model first (restoreModel()), the time stepper before the resumed step begins (restoreTimeStepper()), and the solver, the step actions, the output managers and the field outputs of the step once it has begun (restoreStep()). Close the checkpoint right after that, see close().

Parameters:: fileName (str) – The checkpoint to resume from.

Methods

`close`()	Close the file.
`restoreModel`(model, journal)	Restore the model's state, see `readRestart()`.
`restoreStep`(step)	Restore everything else `step` continues from, after it began as if cold: the solver's state between increments, the state of the step actions -- which the skipped steps before it never brought to their step end -- and the state of the step's output managers (Ensight's file numbering, for instance).
`restoreTimeStepper`(step)	Restore the progress of `step`'s time stepper, before the step begins: it is what tells the step that it is not at its start (see `isAtStepStart()`).

close()[source]: Close the file. Nothing reads the checkpoint after restoreStep(), and it must not stay open: the restart output manager’s ring buffer overwrites the oldest of its files, which can be this very one, and HDF5 cannot truncate a file it still holds open. The resumed run would then fail mid-step with “unable to truncate a file which is already open”, which reads like a solver failure and is not one.

restoreModel(model, journal)[source]

Restore the model’s state, see readRestart().

Parameters:

model – The model tree, rebuilt from the same input file.
journal – The journal, for the progress messages of the topology replay.

restoreStep(step)[source]

Restore everything else step continues from, after it began as if cold: the solver’s state between increments, the state of the step actions – which the skipped steps before it never brought to their step end – and the state of the step’s output managers (Ensight’s file numbering, for instance). An output manager added for the resumed run starts afresh.

Parameters:: step – The resumed step.

restoreTimeStepper(step)[source]: Restore the progress of step’s time stepper, before the step begins: it is what tells the step that it is not at its start (see isAtStepStart()).

numberOfIncrementsDone: How many increments of that step were accepted when the checkpoint was written (see numberOfIncrementsDone()).

stepNumber: The step the checkpointed run was in; the steps before it are not solved again.

time: The model time the checkpoint was written at.

edelweissfe.utils.checkpoint.readRestartDataInto(group, entities, newEntitiesStartAfresh=False)[source]

Hand each entity the restart data writeRestartDataOf() stored for it.

Parameters:

group (Group) – The group holding the subgroups.
entities (dict) – The entities, by name.
newEntitiesStartAfresh (bool) – If True, an entity the checkpoint holds nothing for keeps its initial state (an output manager added for the resumed run). Otherwise it is refused: it does not belong to the checkpointed run.

edelweissfe.utils.checkpoint.writeCheckpoint(fileName, model, step, serial)[source]

Write a restart checkpoint of the converged state.

Written to a temporary file first, and renamed to fileName only once complete: a job killed while writing leaves the previous checkpoint of that name intact, never a truncated one.

Parameters:

fileName (str) – The file to write; replaced if it exists.
model – The model tree.
step – The current step, whose time stepper, solver, step actions, output managers and field outputs write their own state.
serial (int) – The number of this checkpoint in the sequence its writer writes, stored in the file: it orders checkpoints independently of file times.

edelweissfe.utils.checkpoint.writeRestartDataOf(group, entities)[source]

Store the restart data of each entity in its own subgroup, named after it.

Parameters:

group (Group) – The group to create the subgroups in.
entities (dict) – The entities, by name.

edelweissfe.utils.checkpoint.CHECKPOINT_FORMAT_VERSION = 13

a run resumes only from checkpoints of its own layout.

Type:: The layout of a checkpoint. Raise it whenever a checkpoint gains or changes state

The state each component carries between increments is declared on the component, and packed and unpacked by one module:

The state a component carries from one increment to the next, written to and read from a restart checkpoint as it is.

A component declares that state: a mapping of attribute name to type, for instance the implicit solver’s – the last accepted increments and their dU, the digest of the numbering of the degrees of freedom these are vectors of, and the convergence criterion, a helper object (see below):

checkpointedState = {
    "prevTimeStep": TimeStep,
    "dUOfLastIncrement": np.ndarray,
    "timeStepOfIncrementBeforeLast": TimeStep,
    "dUOfIncrementBeforeLast": np.ndarray,
    "dofNumberingOfLastIncrement": str,
    "convergenceCriterion": ConvergenceCriterionBase,
}

and packState() / unpackState() turn the declared attributes into the flat mapping of arrays a checkpoint stores, and back. An empty mapping declares that a component carries nothing between increments. A component whose declaration is still None has not been declared at all, and cannot be checkpointed.

An attribute that is None is simply left out, and read back as None. A str is stored as bytes; a dict maps strings to floats. An attribute whose type is none of the plain ones is a helper object that declares its own checkpointedState; its state is stored under the attribute’s name as a prefix. A helper that declares an empty mapping stores nothing and keeps itself as it is.

edelweissfe.utils.checkpointedstate.packState(component)[source]

The declared state of component, as a flat mapping of arrays.

Parameters:: component – Any object with a checkpointedState declaration.
Returns:: One array per declared attribute that is not None.
Return type:: dict[str, numpy.ndarray]

edelweissfe.utils.checkpointedstate.unpackState(component, state)[source]

Set the declared attributes of component from what packState() returned.

Parameters:

component – Any object with a checkpointedState declaration.
state (dict[str, ndarray]) – The mapping of arrays.

Outputmanagers

ensight - Export to Ensight Gold format

monitor - Monitor quantities in the terminal

meshplot - Export to matplotlib

fractureenergyintegrator - Determine the fracture energy

plotalongpath - Plot a result along a line

conditionalstop - Conditional stop if expression becomes true

statusfile - Write the status of the simulation to a file

meshdatatofile - Write the (generated) mesh data to a file

computetimemonitor - Print and write compute times per increment

restart - Write restart checkpoints during the analysis

Checkpoint file layout

`ensight` - Export to Ensight Gold format

`monitor` - Monitor quantities in the terminal

`meshplot` - Export to matplotlib

`fractureenergyintegrator` - Determine the fracture energy

`plotalongpath` - Plot a result along a line

`conditionalstop` - Conditional stop if expression becomes true

`statusfile` - Write the status of the simulation to a file

`meshdatatofile` - Write the (generated) mesh data to a file

`computetimemonitor` - Print and write compute times per increment

`restart` - Write restart checkpoints during the analysis