Step actions

Step actions define actions run during a simulation. They are defined within a *step definition, line by line, by specifying their name and a list of option=value, for example

*step, solver=mySolver
>>dirichlet, name=bottom,   nSet=bottom,   field=displacement, 2=0, 1=0
>>dirichlet, name=rightTop, nSet=rightTop, field=displacement, 2=0,
>>distributedload, name=dload1, surface=top,  type=pressure, magnitude=10, f(t)=t*2
>>distributedload, name=dload2, surface=left, type=pressure, magnitude=50, f(t)=t

`bodyforce` - Bodyforce loads

Relevant module: edelweissfe.stepactions.bodyforce

Options:
Option	Type / Default	Description
`forceVector`	str (required)	The force vector.
`f(t)`	str, default=None	Define an amplitude in the step progress interval [0…1]
`delta`	str, default=None	In subsequent steps only: define the updated force vector incrementally

Example: testfiles/BodyForce3D/test.inp

*include, input=mesh.inp

*material, name=linearelastic, id=le
30000.0, 0.15

*section, name=section1, material=le, type=solid
all

*job, name=c3d8job, domain=3d
*solver, solver=NIST, name=theSolver

*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
>>perNode, name=RF, nSet=top, result=P, field=displacement

*output, type=ensight, name=ensightExport
>>perNode,    fieldOutput=displacement
>>perElement, fieldOutput=stress
>>perElement, fieldOutput=strain
>>configuration, overwrite=yes

*output, type=monitor, name=myNodeSetMonitor
fieldOutput=RF, f(x)='sum(x[:,0])', label=ForceX
fieldOutput=RF, f(x)='sum(x[:,1])', label=ForceY
fieldOutput=RF, f(x)='sum(x[:,2])', label=ForceZ

*step, solver=theSolver
maxInc=1e-1, minInc=1e-5, maxNumInc=1000, maxIter=25, stepLength=1
>>options, name=theSolver, extrapolation=linear
>>dirichlet, name=top,  nSet=top,   field=displacement, 1=0.0, 2=0.0, 3=.0
>>bodyforce, name=bforce, elSet=all, forceVector='0.0, 10.0, 20.0', f(t)=t

`dirichlet` - Standard dirichlet BC

Relevant module: edelweissfe.stepactions.dirichlet

Options:
Option	Type / Default	Description
`field`	str (required)	Field for which the boundary condition is active.
`1`	float, default=None	Prescribe first component of field.
`2`	float, default=None	Prescribe second component of field.
`3`	float, default=None	Prescribe third component of field.
`4`	float, default=None	Prescribe fourth component of field.
`5`	float, default=None	Prescribe fifth component of field.
`6`	float, default=None	Prescribe sixth component of field.
`components`	str, default=None	Prescribe values using a numpy ndarray for representation; use ‘x’ for ignored values.
`f(t)`	str, default=None	Define an amplitude in the step progress interval [0…1]

Keyword: updatedirichlet
Option	Type / Default	Description
`1`	float, default=None	Prescribe first component of field.
`2`	float, default=None	Prescribe second component of field.
`3`	float, default=None	Prescribe third component of field.
`4`	float, default=None	Prescribe fourth component of field.
`5`	float, default=None	Prescribe fifth component of field.
`6`	float, default=None	Prescribe sixth component of field.
`components`	str, default=None	Prescribe values using a numpy ndarray for representation; use ‘x’ for ignored values.
`f(t)`	str, default=None	Define an amplitude in the step progress interval [0…1]

`distributedload` - Distributed surface loads

Relevant module: edelweissfe.stepactions.distributedload

Options:
Option	Type / Default	Description
`field`	str, default=’displacement’	Field for which the boundary condition is active.
`magnitude`	str (required)	Magnitude of the distributed load
`type`	str (required)	The load type, e.g., pressure or surface traction; Must be supported by the element type
`f(t)`	str, default=None	Define an amplitude in the step progress interval [0…1]
`delta`	str, default=None	In subsequent steps only: define the new magnitude incrementally

Keyword: updatedistributedload
Option	Type / Default	Description
`magnitude`	str, default=None	Magnitude of the distributed load
`delta`	str, default=None	In subsequent steps only: define the new magnitude incrementally
`f(t)`	str, default=None	Define an amplitude in the step progress interval [0…1]

Example: testfiles/marmot/DLoad/test.inp

*modelGenerator, generator=planeRectQuad, name=gen
elType=CPE4
nX=20
nY=5
l=100
h=25

*elSet, elSet=loadEls
100,95,90,85,80

*surface, type=element, name=surfaceLoad
**elset, faceID
loadEls, 3


*section, name=section1, thickness=1.0, material=mat, type=plane
all
*material, name=VonMises, id=mat
210000, 0.3, 550, 1000, 200, 1400

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

*fieldOutput
>>perNode, name=displacement, elSet=all, field=displacement, result=U
>>perNode, name=RF, nSet=gen_left, field=displacement, result=P
>>perElement, name=stress, elSet=all, result=stress, quadraturePoint=1
>>perElement, name=strain, elSet=all, result=strain, quadraturePoint=1

*output, type=monitor, name=ensightExport
fieldOutput = RF, f(x) = 'sum ( x[:, 1])'

*output, type=ensight, name=ensightExport
>>perNode,    fieldOutput=displacement
>>perElement, fieldOutput=stress
>>perElement, fieldOutput=strain
>>configuration, overwrite=yes
*step, solver=theSolver
maxInc=1e-1, minInc=1e-5, maxNumInc=1000, maxIter=25, stepLength=1
>>options, name=theSolver, extrapolation=linear
>>dirichlet, name=left,  nSet=gen_left,   field=displacement, 1=0.0, 2=0.0
>>distributedload, name=dload, surface=gen_top, type=pressure, magnitude=0.15, f(t)=t

`geostatic` - Geostatic stress states

Relevant module: edelweissfe.stepactions.geostatic

Initialize materials to an geostatic stress state

Options:
Option	Type / Default	Description
`p1`	float (required)	sig_x=sig_y=sig_z in first point.
`p2`	float, default=None	sig_x=sig_y=sig_z in second point.
`h1`	float, default=1.0	y coordinate of first point
`h2`	float, default=-1.0	y coordinate of second point
`xLateral`	float, default=1.0	ratio of sig_x/sig_y, default=1.0
`zLateral`	float, default=1.0	ratio of sig_z/sig_y, default=1.0

Example: testfiles/marmot/GeoStatic/test.inp

*modelGenerator, generator=planeRectQuad, name=gen
l=50
h=150
nX=10
nY=30
elType=CPE4

*material, name=linearElastic, id=le
210000, 0.3

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

*job, name=cpe4job, domain=2d
*solver, solver=NIST, name=theSolver
*fieldOutput
>>perNode, name=dispTop, nSet=gen_top,       field=displacement, result=U, f(x)='mean(x[:,1])'
>>perNode, name=RFBottom, nSet=gen_bottom,    field=displacement, result=P, f(x)='sum(x[:,1])'
>>perNode, elSet=all,  field=displacement, result=U, name=displacement
>>perElement, elSet=all,  result=stress,  name=S11,  quadraturePoint=1, f(x)='x[:,0]'
>>perElement, elSet=all,  result=stress,  name=S22,  quadraturePoint=1, f(x)='x[:,1]'
>>perElement, elSet=all,  result=stress,  name=S33,  quadraturePoint=1, f(x)='x[:,2]'

*output, type=monitor
fieldOutput=dispTop
*output, type=monitor
fieldOutput=RFBottom

*output, type=ensight, name=ensightExport
>>perNode, fieldOutput=displacement
>>perElement, fieldOutput=S11
>>perElement, fieldOutput=S22
>>perElement, fieldOutput=S33
>>configuration, overwrite=yes


*step, solver=theSolver
maxInc=0.5
>>dirichlet, name=left,   nSet=gen_left,   field=displacement, 1=0.0,
>>dirichlet, name=right,  nSet=gen_right,   field=displacement, 1=0.0
>>dirichlet, name=bottom, nSet=gen_bottom,   field=displacement, 2=0.0,
>>geostatic, name=geo, elSet=all, p1=-10, h1=150, p2=-5, h2=0, xLateral=1.0, zLateral=1.0
>>distributedload, name=dlTop, surface=gen_top, magnitude=10, f(t)=1, type=pressure

*step, solver=theSolver
maxInc=1e-1,
** >>updatedistributedload, name=dlTop, delta=-10.0, f(t)=t
>>distributedload, name=dlTop, delta=-10.0, f(t)=t

`indirectcontrol` - Indirect displacement control

Relevant module: edelweissfe.stepactions.indirectcontrol

An arc length controller (see Arc length control): the solver option arcLengthController of NISTPArcLength selects it by its name.

Options:
Option	Type / Default	Description
`dof1`	str (required)	Degree of freedom for the constraint (model access expression).
`dof2`	str (required)	Degree of freedom for the constraint (model access expression).
`cVector1`	str (required)	c vector.
`cVector2`	str (required)	c vector.
`L`	float (required)	Final distance (e.g. crack opening)
`exportCVector`	str, default=’’	File to export the computed c vector
`absolute`	bool, default=True	Use absolute formulation

Example: testfiles/marmot/IndirectDisplacementControl/test.inp

*job, name=job, domain=3d

*solver, solver=NISTPArcLength, name=NISTPArcLen

*modelGenerator, generator=boxGen, name=gen
lX     = 100
lY     = 1
lZ     = 1
nX     = 9
nY     = 1
nZ     = 1
elType = GC3D8

*material, name=gcdp, id=concrete
**E         nu      fcy         fcu         fbu         ftu         Df          Ah
100.0,      0.00,   10,         30,         35,         3.00,       0.85,       0.12,
**Bh        Ch      Dh          As          softmod     l           m           omegaMax
0.003,      2.0,    1e-6,       15.0,       .1,         2,          1.05,       1,
**derivativeMethod, dTThresholdElasticStiffness, viscoplasticity
1,                  1e-8,       0

*section, name=concrete, material=concrete, type=solid
all

*modelGenerator, generator=findClosestNode, name=closestN1, executeAfterManualGeneration=True
location='40, 0, 0'
storeIn=IDC1

*modelGenerator, generator=findClosestNode, name=closestN2, executeAfterManualGeneration=True
location='60, 0, 0'
storeIn=IDC2

*step, solver=NISTPArcLen
maxInc=1, minInc=1, maxNumInc=100000, maxIter=25, stepLength=1
>>setfield,   name=omegaIni,  fieldOutput=alphaDWeak, value=1e-2, type=uniform

*step, solver=NISTPArcLen
maxInc=1e-2, startInc=1e-2, minInc=1e-6, maxNumInc=100000, maxIter=25, stepLength=1
>>options, name=test, intermediateSaveInterval=1, minDTForOutput=0
>>options, name=NISTPArcLen, arcLengthController=opening, stopCondition='fieldOutputs["I1pMax"] > 0.01'

>>indirectcontrol, name=opening, dof1='model.nodeSets["IDC1"][0].fields["displacement"]', cVector1='[-1,0,0]', dof2='model.nodeSets["IDC2"][0].fields["displacement"]', cVector2='[1,0,0]', L=1.,

>>dirichlet, name=leftX, nSet=gen_left,  field=displacement, 1=0.
>>dirichlet, name=leftY, nSet=gen_left,  field=displacement, 2=0.
>>dirichlet, name=leftZ, nSet=gen_left,  field=displacement, 3=0.
>>dirichlet, name=right, nSet=gen_right, field=displacement, 1=1.

*fieldOutput
>>perNode, name=displacement,    elSet=all, field=displacement, result=U
>>perNode, name=nonlocal_damage, elSet=all, field=nonlocal damage, result=U

>>perElement, name=strain, elSet=all, result=strain, quadraturePoint=0:8, f(x)='np.mean(x,axis=1)'
>>perElement, name=stress, elSet=all, result=stress, quadraturePoint=0:8, f(x)='np.mean(x,axis=1)'
>>perElement, name=omega,  elSet=all, result=omega,  quadraturePoint=0:8, f(x)='np.mean(x,axis=1)'
>>perElement, name=alphaP, elSet=all, result=alphaP, quadraturePoint=0:8, f(x)='np.mean(x,axis=1)'
>>perElement, name=alphaD, elSet=all, result=alphaD, quadraturePoint=0:8, f(x)='np.mean(x,axis=1)'
>>perElement, name=I1p,    elSet=all, result=I1p,    quadraturePoint=0:8, f(x)='np.mean(x,axis=1)'

>>perElement, name=I1pMax,    elSet=all, result=I1p,    quadraturePoint=0:8, f(x)='np.max(x)', saveHistory=true
>>perElement, name=alphaDMax, elSet=all, result=alphaD, quadraturePoint=0:8, f(x)='np.max(x)', saveHistory=true
>>perElement, name=omegaMax,  elSet=all, result=omega,  quadraturePoint=0:8, f(x)='np.max(x)', saveHistory=true

>>perElement, name=alphaDWeak, elSet=gen_centerSliceX, result=alphaD, quadraturePoint=0:8

>>perNode, name=U1,  nSet=gen_right, field=displacement, result=U, f(x)='mean(x[:,0])', saveHistory=true, export=U
>>perNode, name=RF1, nSet=gen_right, field=displacement, result=P, f(x)='sum(x[:,0])', saveHistory=true, export=RF

*output, type=ensight, name=test
>>perNode, fieldOutput=displacement
>>perNode, fieldOutput=nonlocal_damage
>>perElement, fieldOutput=omega
>>perElement, fieldOutput=I1p
>>perElement, fieldOutput=alphaP
>>perElement, fieldOutput=alphaD
>>perElement, fieldOutput=stress
>>perElement, fieldOutput=strain
>>configuration, overwrite=yes

*output, type=meshPlot
figure=1, axSpec=111, create=xyData, x=U1, y=RF1

`indirectcontractioncontrol` - Indirect displacement – contraction ring control

Relevant module: edelweissfe.stepactions.indirectcontractioncontrol

An arc length controller (see Arc length control): the solver option arcLengthController of NISTPArcLength selects it by its name.

Options:
Option	Type / Default	Description
`L`	float (required)	Final distance (e.g. crack opening)
`exportCVector`	str, default=None	File to export the computed c vector
`absolute`	bool, default=True	Use absolute formulation

`initializematerial` - Initialize materials

Relevant module: edelweissfe.stepactions.initializematerial

Let materials initialize themselves (e.g., state vars depending on material parameters…) !

`modelupdate` - Update the model

Relevant module: edelweissfe.stepactions.modelupdate

Options:
Option	Type / Default	Description
`update`	str (required)	Model accessible, executable expression

`nodeforces` - Concentrated node forces

Relevant module: edelweissfe.stepactions.nodeforces

Options:
Option	Type / Default	Description
`field`	str (required)	Field for which the boundary condition is active.
`1`	float, default=None	Prescribe first component of field.
`2`	float, default=None	Prescribe second component of field.
`3`	float, default=None	Prescribe third component of field.
`4`	float, default=None	Prescribe fourth component of field.
`5`	float, default=None	Prescribe fifth component of field.
`6`	float, default=None	Prescribe sixth component of field.
`components`	str, default=None	Prescribe values using a numpy ndarray for representation; use ‘x’ for ignored values.
`f(t)`	str, default=None	Define an amplitude in the step progress interval [0…1]

Keyword: updatenodeforces
Option	Type / Default	Description
`1`	float, default=None	Prescribe first component of field.
`2`	float, default=None	Prescribe second component of field.
`3`	float, default=None	Prescribe third component of field.
`4`	float, default=None	Prescribe fourth component of field.
`5`	float, default=None	Prescribe fifth component of field.
`6`	float, default=None	Prescribe sixth component of field.
`components`	str, default=None	Prescribe values using a numpy ndarray for representation; use ‘x’ for ignored values.
`f(t)`	str, default=None	Define an amplitude in the step progress interval [0…1]

Example: testfiles/marmot/NodeForces/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=10
nY=10

*fieldOutput
>>perNode, nSet=gen_bottom, result=P, field=displacement, name=RF
>>perNode, elSet=all, field=displacement, result=U, name=displacement

*output, type=monitor
fieldOutput=RF, f(x)='mean(x[:,1])'

*output, type=ensight, name=esExport
>>perNode, fieldOutput=displacement
>>configuration, overwrite=yes

*step, solver=theSolver
maxInc=1e-1, minInc=1e-8, maxNumInc=50, maxIter=25, stepLength=100
>>dirichlet, name=bottom, nSet=gen_bottom,  field=displacement, 2=0, 1=0
>>nodeforces, name=cloadTop, nSet=gen_top, field=displacement, 2=-50
*step, solver=theSolver
maxInc=1e-1, minInc=1e-8, maxNumInc=1000, maxIter=25, stepLength=100
>>nodeforces, name=cloadTop, 2=-10, f(t)=sin(t*2*pi)
*step, solver=theSolver
maxInc=1e-1, minInc=1e-8, maxNumInc=1000, maxIter=25, stepLength=100
>>nodeforces, name=cloadTop, 2=+50, f(t)=t

`setfield` - Set a field to a prescribed value

Relevant module: edelweissfe.stepactions.setfield

Options:
Option	Type / Default	Description
`type`	str (required)	Either ‘uniform’ or ‘analyticalField’.
`value`	str (required)	Scalar value if type ‘const’; name of analyticalField if type ‘analyticalField’

`setinitialconditions` - Set initial conditions to elements

Relevant module: edelweissfe.stepactions.setinitialconditions

Pass initial conditions to elements.

Options:
Option	Type / Default	Description
`property`	str (required)	The name of the property to be initialized
`values`	str (required)	Comma separated property values.

`changematerialproperty` - Change a material property during a step

Relevant module: edelweissfe.stepactions.changematerialproperty

Change a property of a material during a step.

At the start of every increment, one entry of the material’s property vector is set to a value prescribed as a function of the step time, for every element of every section using the material. The elements keep their state: a changed property affects how the state evolves from then on, but the state accumulated so far (stress, plastic strain, damage, …) is neither reset nor re-initialized. Properties an element was assigned individually (materialParameterFromField) are kept, apart from the changed one.

Options:
Option	Type / Default	Description
`index`	int (required)	The index of the property in the material properties vector
`f(t)`	str, default=None	Define an amplitude in the step progress interval [0…1]

Example: testfiles/marmot/ChangeMaterialProperties/test.inp

*material, name=LinearElastic, id=myMaterial
**Isotropic
**E    nu
1000, 0.2

*job, name=job, domain=3d
*solver, solver=NIST, name=theSolver

*modelGenerator, generator=boxGen, name=gen
x0      =0
y0      =0
z0      =0
nX      =1
nY      =1
nZ      =1
lX      =50
lY      =50
lZ      =10
elType  =C3D8

*section, name=section1, material=myMaterial, type=solid
all

*fieldOutput
>>perNode, elSet=all, field=displacement, result=U, name=displacement
>>perNode, nSet=gen_top, field=displacement, result=U, name=disp_top
>>perElement, elSet=all, result=strain, name=strain, quadraturePoint=0:8, f(x)='np.mean(x,axis=1)'
>>perElement, elSet=all, result=stress, name=stress, quadraturePoint=0:8, f(x)='np.mean(x,axis=1)'

*output, type=ensight, name=test
>>perNode, fieldOutput=displacement
>>perElement, fieldOutput=stress
>>perElement, fieldOutput=strain
>>configuration, overwrite=yes

*output, type=monitor, name=dispMon
fieldOutput=disp_top, f(x)='mean(x[:,1])'


*step, solver=theSolver
maxInc=1e0, minInc=1e0, maxNumInc=100, maxIter=25, stepLength=1
** >>setfield,   name=sf,  fieldOutput=alphaP, type=analyticalField, value=AnalyticalField-01
>>dirichlet,  name=x0u, nSet=gen_left,      field=displacement, 1=0.
>>dirichlet,  name=y0u, nSet=gen_bottom,    field=displacement, 2=0.
>>dirichlet,  name=z0u, nSet=gen_back,      field=displacement, 3=0.

*step, solver=theSolver
maxInc=2e-2, minInc=1e-6, maxNumInc=1000, maxIter=25, stepLength=1
>>changeMaterialProperty, name=chProp,  material=myMaterial, index=0, f(t)='1000 - 500 * t'
>>distributedload, name=p_top, surface=gen_top, magnitude=1, f(t)=1, type=pressure

Implementing your own step actions

Subclass from the step action base class in module edelweissfe.stepactions.base.stepactionbase

class edelweissfe.stepactions.base.stepactionbase.StepActionBase(name, definition, jobInfo, model, fieldOutputController, journal)[source]

This is the base class for all step actions. User defined step actions must implement the methods.

Attributes:

checkpointedState
schema

Parameters:

name (str)
definition (dict)
jobInfo (dict)
model (FEModel)
fieldOutputController (FieldOutputController)
journal (Journal)

Methods

`applyAtIncrementStart`(model, timeStep)	Is called when a step increment starts.
`applyAtStepEnd`(model)	Is called when a step successfully finished.
`applyAtStepStart`(model)	Is called when a step starts.
`fromStepActionDefinition`(name, definition, ...)	Create this step action from a parsed `.inp` step action definition.
`getRestartData`()	The state this step action carries; by default the attributes declared in `checkpointedState`.
`setRestartData`(data)	Restore the state `getRestartData()` returned.
`updateStepAction`(definition, jobInfo, model, ...)	Is called when an updated definition is present for a new step.
`updateStepActionFromDefinition`(definition, ...)	Update this step action from a parsed `.inp` step action definition.

classmethod fromStepActionDefinition(name, definition, jobInfo, model, fieldOutputController, journal)[source]

Create this step action from a parsed .inp step action definition.

This is the one place a module’s input-file shape (numbered component options, a f(t) expression string, a node set name) is turned into the typed arguments its real constructor takes. Override it together with a typed __init__; leave it alone and the default dict-consuming constructor is used unchanged.

Parameters:

name (str) – The name of the step action.
definition (dict) – The parsed option mapping for this step action.
jobInfo (dict) – A dictionary containing the information about the job.
model (FEModel) – The model tree.
fieldOutputController (FieldOutputController) – The field output controlling object.
journal (Journal) – The journal object for logging.

Returns:

The constructed step action.

Return type:

StepActionBase

applyAtIncrementStart(model, timeStep)[source]

Is called when a step increment starts.

Parameters:

model (FEModel) – The current state of the model.
timeStep (TimeStep) – The definition of the time increment.

applyAtStepEnd(model)[source]

Is called when a step successfully finished.

Parameters:: model (FEModel) – The current state of the model.

applyAtStepStart(model)[source]

Is called when a step starts.

Parameters:: model (FEModel) – The current state of the model.

getRestartData()[source]

The state this step action carries; by default the attributes declared in checkpointedState.

Returns:: A flat mapping of array name to array.
Return type:: dict[str, numpy.ndarray]

setRestartData(data)[source]

Restore the state getRestartData() returned.

Parameters:: data (dict[str, ndarray]) – The mapping of arrays.

updateStepAction(definition, jobInfo, model, fieldOutputController, journal)[source]

Is called when an updated definition is present for a new step.

Parameters:

definition (dict) – A dictionary containing the options for this step action.
jobInfo (dict) – A dictionary containing the information about the job.
model (FEModel) – The model tree.
fieldOutputController (FieldOutputController) – The field output controlling object.
journal (Journal) – The journal object for logging.

updateStepActionFromDefinition(definition, jobInfo, model, fieldOutputController, journal)[source]

Update this step action from a parsed .inp step action definition.

The update counterpart of fromStepActionDefinition(), needed as its own hook because a later step re-declaring an action reaches the instance, not the class. Override both or neither: a module whose constructor is typed but whose update path still consumed a dict would work only until the first multi-step input.

Parameters:

definition (dict) – The parsed option mapping for this step action.
jobInfo (dict) – A dictionary containing the information about the job.
model (FEModel) – The model tree.
fieldOutputController (FieldOutputController) – The field output controlling object.
journal (Journal) – The journal object for logging.

checkpointedState: dict | None = None: The state this step action carries from one increment (and step) to the next, by attribute name and type; see checkpointedstate. Undeclared, getRestartData() and setRestartData() must be overridden for checkpointing.

Implementing your own loads

A load is a step action that derives from LoadBase and assembles its own contribution to the equation system in assembleLoad: the negative of the external load it applies, and the tangent of that contribution, nonzero only for a load that follows the deformation (see The residual and the tangent). The solvers do not need to know what a load acts on; their assembleLoads only loops over the loads of the step and lets each assemble itself. They find the loads by this base class, whatever step action module defines them: a load module of its own, registered like any step action, needs no change to any solver, and an arc length step scales it at its end like any other load.

Three bases implement assembleLoad once for all loads of their kind, so that a load deriving from them only says how large it is at a time (getCurrentLoad) and where it acts:

NodalLoadBase: concentrated loads on the degrees of freedom of a field on a node set, such as nodeforces;
DistributedLoadBase: loads per unit area on the faces of a surface, which every element integrates over its loaded face, such as distributedload;
BodyLoadBase: loads per unit volume, which every element of an element set integrates over its volume, such as bodyforce.

A load that acts on something else – the cells or particles of a meshfree model, say – derives from LoadBase directly.

class edelweissfe.stepactions.base.loadbase.LoadBase(name, definition, jobInfo, model, fieldOutputController, journal)[source]

A load: a step action that adds the residual contribution of the external load it applies – the negative of that load, see The residual and the tangent – and the tangent of that contribution, which is nonzero only for a load that follows the deformation.

Every load assembles its own contribution in assembleLoad(), wherever it acts: a node force goes to the degrees of freedom of its nodes, a distributed load or a body force asks each of its elements for the integral over the loaded face or volume. A solver therefore only loops over the loads, see assembleLoads(), which it finds among the step’s actions by this base class, whatever step action module holds them (see collectLoads()): a new kind of load – one acting on the cells or particles of a meshfree model, say – needs no change to any solver.

Over a step, a load changes along its amplitude \(a(t)\), from its value at the start of the step, \(f(0)\), to \(f(1)\) at the end; at the end of the step it keeps the value it reached, from which the next step starts (see applyAtStepEnd()).

Attributes:

checkpointedState
schema

Parameters:

name (str)
definition (dict)
jobInfo (dict)
model (FEModel)
fieldOutputController (FieldOutputController)
journal (Journal)

Methods

`amplitudeAtStepEnd`(amplitude, loadParameter)	The value of a load's amplitude at the end of a step, by which the load keeps the change the step declared.
`applyAtIncrementStart`(model, timeStep)	Is called when a step increment starts.
`applyAtStepEnd`(model[, loadParameter])	Keep the value the load reached at the end of the step, from which the next step starts, and go idle until a later step declares a change again.
`applyAtStepStart`(model)	Is called when a step starts.
`assembleLoad`(P, K, U_np, dU, timeStep, ...)	Add this load's residual contribution to `P`, and its tangent to `K`.
`fromStepActionDefinition`(name, definition, ...)	Create this step action from a parsed `.inp` step action definition.
`getRestartData`()	The state this step action carries; by default the attributes declared in `checkpointedState`.
`setRestartData`(data)	Restore the state `getRestartData()` returned.
`updateStepAction`(definition, jobInfo, model, ...)	Is called when an updated definition is present for a new step.
`updateStepActionFromDefinition`(definition, ...)	Update this step action from a parsed `.inp` step action definition.

static amplitudeAtStepEnd(amplitude, loadParameter)[source]

The value of a load’s amplitude at the end of a step, by which the load keeps the change the step declared.

A step that follows the amplitudes ends at the end of the amplitude, \(a(1)\). An arc length step scales the change of every load over the step, \(f(1) - f(0)\), by its load parameter \(\lambda\), and so it ends on the straight line from the start to the end of the amplitude:

\[a(0) + \lambda \, \left( a(1) - a(0) \right).\]

With the default linear amplitude, this is the load parameter itself. A load the step holds at a constant amplitude, e.g. a self-weight declared with f(t)='1', is part of the dead load of the arc length step, and keeps its full value, whatever the load parameter.

Parameters:

amplitude (Callable[[float], float]) – The amplitude of the load over the step progress interval [0...1].
loadParameter (float | None) – The load parameter an arc length step ended at; None for a step that follows the amplitudes.

Returns:

The amplitude at the end of the step.

Return type:

float

abstractmethod applyAtStepEnd(model, loadParameter=None)[source]

Keep the value the load reached at the end of the step, from which the next step starts, and go idle until a later step declares a change again.

A step that follows the amplitudes ends at \(f(1)\). An arc length step (see Arc length control) applies \(f(0) + \lambda \, (f(1) - f(0))\), the change over the step scaled by its load parameter \(\lambda\), and the load keeps exactly that: the factor of the change is amplitudeAtStepEnd().

Parameters:

model – The current state of the model.
loadParameter (float | None) – The load parameter an arc length step ended at; None for a step that follows the amplitudes.

abstractmethod assembleLoad(P, K, U_np, dU, timeStep, dofManager)[source]

Add this load’s residual contribution to P, and its tangent to K.

Both are augmented, never overwritten.

Parameters:

P (DofVector) – The global residual contribution vector to augment.
K (SystemMatrixBlocks | None) – The blocks of the global system matrix to augment: K[entity] hands out the block of an entity (an element, a cell, a particle) to add to, see SystemMatrixBlocks; the solver commits the last one. None for an explicit solver, which needs no tangent.
U_np (DofVector) – The current global solution.
dU (DofVector) – The global solution increment since the last converged state.
timeStep (TimeStep) – The current time step.
dofManager (DofManager) – The DOF manager of the equation system, which locates the degrees of freedom the load acts on.

class edelweissfe.stepactions.base.nodalloadbase.NodalLoadBase(name, definition, jobInfo, model, fieldOutputController, journal)[source]

Concentrated loads on the degrees of freedom of a field on a node set, such as node forces.

Attributes:

checkpointedState
field
nodeSet
schema

Parameters:

name (str)
definition (dict)
jobInfo (dict)
model (FEModel)
fieldOutputController (FieldOutputController)
journal (Journal)

Methods

`amplitudeAtStepEnd`(amplitude, loadParameter)	The value of a load's amplitude at the end of a step, by which the load keeps the change the step declared.
`applyAtIncrementStart`(model, timeStep)	Is called when a step increment starts.
`applyAtStepEnd`(model[, loadParameter])	Keep the value the load reached at the end of the step, from which the next step starts, and go idle until a later step declares a change again.
`applyAtStepStart`(model)	Is called when a step starts.
`assembleLoad`(P, K, U_np, dU, timeStep, ...)	Subtract the current node loads from the residual contribution at the degrees of freedom of the field on the node set; a dead load, so without a tangent.
`fromStepActionDefinition`(name, definition, ...)	Create this step action from a parsed `.inp` step action definition.
`getCurrentLoad`(timeStep)	Return the current loads of the nodes.
`getRestartData`()	The state this step action carries; by default the attributes declared in `checkpointedState`.
`setRestartData`(data)	Restore the state `getRestartData()` returned.
`updateStepAction`(definition, jobInfo, model, ...)	Is called when an updated definition is present for a new step.
`updateStepActionFromDefinition`(definition, ...)	Update this step action from a parsed `.inp` step action definition.

assembleLoad(P, K, U_np, dU, timeStep, dofManager)[source]

Subtract the current node loads from the residual contribution at the degrees of freedom of the field on the node set; a dead load, so without a tangent. See assembleLoad().

Only the nodes of the set that are part of the equation system are loaded (see locateFieldOnNodeSet()): every node of the set in a finite element model, those in the active domain in a meshfree one.

Parameters:

P (DofVector) – The global residual contribution vector to augment.
K (SystemMatrixBlocks | None) – The global system matrix; untouched.
U_np (DofVector) – The current global solution.
dU (DofVector) – The global solution increment.
timeStep (TimeStep) – The current time step.
dofManager (DofManager) – The DOF manager of the equation system, which locates the degrees of freedom of the node set.

abstractmethod getCurrentLoad(timeStep)[source]

Return the current loads of the nodes.

Returns:: The loads, one row per node of the set, in its order, with the components of the field.
Return type:: np.ndarray
Parameters:: timeStep (TimeStep)

class edelweissfe.stepactions.base.distributedloadbase.DistributedLoadBase(name, definition, jobInfo, model, fieldOutputController, journal)[source]

A load per unit area on a surface, such as a pressure: each element of the surface integrates it over its loaded face, see computeDistributedLoad().

Attributes:

checkpointedState
loadType: Return the type of load (e.g., pressure, surface traction, …
schema
surface: The surface this distributed load ist acting on.

Parameters:

name (str)
definition (dict)
jobInfo (dict)
model (FEModel)
fieldOutputController (FieldOutputController)
journal (Journal)

Methods

`amplitudeAtStepEnd`(amplitude, loadParameter)	The value of a load's amplitude at the end of a step, by which the load keeps the change the step declared.
`applyAtIncrementStart`(model, timeStep)	Is called when a step increment starts.
`applyAtStepEnd`(model[, loadParameter])	Keep the value the load reached at the end of the step, from which the next step starts, and go idle until a later step declares a change again.
`applyAtStepStart`(model)	Is called when a step starts.
`assembleLoad`(P, K, U_np, dU, timeStep, ...)	Let every element of the surface add the residual contribution of the load on its face, the negative of the external load, and its tangent; see `assembleLoad()`.
`fromStepActionDefinition`(name, definition, ...)	Create this step action from a parsed `.inp` step action definition.
`getCurrentLoad`(timeStep)	Return the current load for this distributed load.
`getRestartData`()	The state this step action carries; by default the attributes declared in `checkpointedState`.
`setRestartData`(data)	Restore the state `getRestartData()` returned.
`updateStepAction`(definition, jobInfo, model, ...)	Is called when an updated definition is present for a new step.
`updateStepActionFromDefinition`(definition, ...)	Update this step action from a parsed `.inp` step action definition.

assembleLoad(P, K, U_np, dU, timeStep, dofManager)[source]

Let every element of the surface add the residual contribution of the load on its face, the negative of the external load, and its tangent; see assembleLoad().

Parameters:

P (DofVector) – The global residual contribution vector to augment.
K (SystemMatrixBlocks | None) – The global system matrix to augment; None for an explicit solver, which needs no tangent.
U_np (DofVector) – The current global solution.
dU (DofVector) – The global solution increment.
timeStep (TimeStep) – The current time step.
dofManager (DofManager) – The DOF manager of the equation system.

abstractmethod getCurrentLoad(timeStep)[source]

Return the current load for this distributed load.

Returns:: The magnitude.
Return type:: np.ndarray
Parameters:: timeStep (TimeStep)

abstract property loadType: str

Return the type of load (e.g., pressure, surface traction, … )

Returns:: The magnituide.
Return type:: float

abstract property surface: dict

The surface this distributed load ist acting on.

Returns:: The surface definition.
Return type:: dict

class edelweissfe.stepactions.base.bodyloadbase.BodyLoadBase(name, definition, jobInfo, model, fieldOutputController, journal)[source]

A load per unit volume on a set of elements, such as gravity: each element integrates it over its volume, see computeBodyForce().

Attributes:

checkpointedState
elementSet: The elements this load is acting on
schema

Parameters:

name (str)
definition (dict)
jobInfo (dict)
model (FEModel)
fieldOutputController (FieldOutputController)
journal (Journal)

Methods

`amplitudeAtStepEnd`(amplitude, loadParameter)	The value of a load's amplitude at the end of a step, by which the load keeps the change the step declared.
`applyAtIncrementStart`(model, timeStep)	Is called when a step increment starts.
`applyAtStepEnd`(model[, loadParameter])	Keep the value the load reached at the end of the step, from which the next step starts, and go idle until a later step declares a change again.
`applyAtStepStart`(model)	Is called when a step starts.
`assembleLoad`(P, K, U_np, dU, timeStep, ...)	Let every element of the element set add the residual contribution of the body force, the negative of the external load, and its tangent; see `assembleLoad()`.
`fromStepActionDefinition`(name, definition, ...)	Create this step action from a parsed `.inp` step action definition.
`getCurrentLoad`(timeStep)	Return the current magnitude for this body load.
`getRestartData`()	The state this step action carries; by default the attributes declared in `checkpointedState`.
`setRestartData`(data)	Restore the state `getRestartData()` returned.
`updateStepAction`(definition, jobInfo, model, ...)	Is called when an updated definition is present for a new step.
`updateStepActionFromDefinition`(definition, ...)	Update this step action from a parsed `.inp` step action definition.

assembleLoad(P, K, U_np, dU, timeStep, dofManager)[source]

Let every element of the element set add the residual contribution of the body force, the negative of the external load, and its tangent; see assembleLoad().

Parameters:

P (DofVector) – The global residual contribution vector to augment.
K (SystemMatrixBlocks | None) – The global system matrix to augment; None for an explicit solver, which needs no tangent.
U_np (DofVector) – The current global solution.
dU (DofVector) – The global solution increment.
timeStep (TimeStep) – The current time step.
dofManager (DofManager) – The DOF manager of the equation system.

abstractmethod getCurrentLoad(timeStep)[source]

Return the current magnitude for this body load.

Returns:: The magnitude.
Return type:: np.ndarray
Parameters:: timeStep (TimeStep)

abstract property elementSet: ElementSet

The elements this load is acting on

Returns:: The list of elements.
Return type:: list

Step actions

bodyforce - Bodyforce loads

dirichlet - Standard dirichlet BC

distributedload - Distributed surface loads

geostatic - Geostatic stress states

indirectcontrol - Indirect displacement control

indirectcontractioncontrol - Indirect displacement – contraction ring control

initializematerial - Initialize materials

modelupdate - Update the model

nodeforces - Concentrated node forces

setfield - Set a field to a prescribed value

setinitialconditions - Set initial conditions to elements

changematerialproperty - Change a material property during a step

Implementing your own step actions

Implementing your own loads

`bodyforce` - Bodyforce loads

`dirichlet` - Standard dirichlet BC

`distributedload` - Distributed surface loads

`geostatic` - Geostatic stress states

`indirectcontrol` - Indirect displacement control

`indirectcontractioncontrol` - Indirect displacement – contraction ring control

`initializematerial` - Initialize materials

`modelupdate` - Update the model

`nodeforces` - Concentrated node forces

`setfield` - Set a field to a prescribed value

`setinitialconditions` - Set initial conditions to elements

`changematerialproperty` - Change a material property during a step