# block history command

Syntax

block history <name s > location-keyword variable-keyword <keyword ...>

Primary keywords:

Adds a history of a block value. Review the common c history commands. The history can be assigned a name for later reference with the optional name keyword. If not, the history will be given a default name based on its internally assigned id number.

This command requires that one location-keyword and one variable-keyword are provided. These are shown in groups below.

Block histories can be taken of any scalar field variable, at any location encompassed by the block. Once specified, the history location will travel with the block.

The location of the history may be specified in varying ways: by location in space, by selecting the centroid of a block with a specific ID number, or by the location of the gridpoint with a specific ID number.

If the history value is gridpoint-based, then a value is calculated using a weighting function inside the block.

If the value is zone-based and the location does not correspond to the zone centroid, the value will be determined by a curve fitting algorithm. Which algorithm used can be specified in the following [blockhistoryoptions]. By default a value is considered constant within a zone.

Note that to take a history of a specific gridpoint, you take a block history using the gridpointid as the location, or specify the position of a gridpoint.

Keyword Options For location-keyword

gridpointid i

Set history location at the gridpoint with ID i.

position v

Set history location at the position v.

zoneid i

Set history location as the centroid of the zone with ID i.

Keyword Options For variable-keyword

This will repeat in at least one other place

acceleration [blockhistoryoptions]

acceleration magnitude at the gridpoint (only available if model configure dynamic has been specified)

acceleration-x [blockhistoryoptions]

x-acceleration at the gridpoint (only available if model configure dynamic has been specified)

acceleration-y [blockhistoryoptions]

y-acceleration at the gridpoint (only available if model configure dynamic has been specified)

acceleration-z [blockhistoryoptions]

z-acceleration at the gridpoint (only available if model configure dynamic has been specified)

condition [blockhistoryoptions]

a measure of how badly deformed a zone is. This is a number between 0 and 1 with 1 an ideal tetrahedron and 0 a critically deformed zone. This is the minimum measure of aspect ratio, volume ratio and orthogonality. See block.zone.condition.

density [blockhistoryoptions]

The density of the zone.

displacement [blockhistoryoptions]

displacement magnitude at the gridpoint

displacement-x [blockhistoryoptions]

x-displacement at the gridpoint

displacement-y [blockhistoryoptions]

y-displacement at the gridpoint

displacement-z [blockhistoryoptions]

z-displacement at the gridpoint

extra [blockhistoryoptions]

extra variable value. The extra variable index used will default to 1 and can be changed with the index modifier keyword. The value will by default come from the grid point extra variables, but this can be specified using the source modifier keyword. The value will by default be treated as a scalar floating point type, but this can be specified using the type modifier keyword.

pore-pressure [blockhistoryoptions]

pore pressure in zone. By default this will be the grid point pore pressure, but the zone average pore pressure can be specified by using the source keyword modifier.

property [blockhistoryoptions]

a property of the mechanical constitutive model of the zone. The property name must be specified using the name keyword modifier. By default it will be assumed the property is a floating point scalar, but this can be specified using the type modifier keyword.

property-fluid [blockhistoryoptions]

a property of the fluid constitutive model of the zone. The property name must be specified using the name keyword modifier. By default it will be assumed the property is a floating point scalar, but this can be specified using the type modifier keyword.

property-thermal [blockhistoryoptions]

a property of the thermal constitutive model of the zone. The property name must be specified using the name keyword modifier. By default it will be assumed the property is a floating point scalar, but this can be specified using the type modifier keyword.

ratio-local [blockhistoryoptions]

the local unbalanced force ratio at each gridpoint. Like all results, this can be changed to the logarithm of the value by using the :lkwd:’log’ keyword modifier.

strain-increment [blockhistoryoptions]

the strain increment tensor of the zone, determined by the current displacement field. Use the quantity keyword to specify which scalar value to retrieve from the tensor.

strain-rate [blockhistoryoptions]

the strain rate tensor of the zone, determined by the current velocity field. Use the quantity keyword to specify which scalar value to retrieve from the tensor.

stress [blockhistoryoptions]

the stress tensor of the zone, determined by the weighted average of the subzone stresses. Use the quantity keyword to specify which scalar value to retrieve from the tensor.

stress-strength-ratio [blockhistoryoptions]

the ratio of the current stress to a failure surface of the zone, as determined by the current zone constitutive model. Not all constitutive models support this calculation. If unsupported, the value returned will be 10. The value returned is generally held to a maximum of 10.

stress-effective [blockhistoryoptions]

the effective stress tensor of the zone, determined by the weighted average of the subzone stresses minus the zone averaged pore pressure. Use the quantity keyword to specify which scalar value to retrieve from the tensor.

temperature [blockhistoryoptions]

the temperature at the gridpoints. The source modifier keyword can be used to specify that zone based temperature should be used instead.

timestep-dynamic [blockhistoryoptions]

the local critical dynamic time step of that particular gridpoint. (only available in if model configure dynamic has been specified)

unbalanced-force [blockhistoryoptions]

the unbalanced force magnitude at the gridpoint.

unbalanced-force-x [blockhistoryoptions]

x-unbalanced force at the gridpoint.

unbalanced-force-y [blockhistoryoptions]

y-unbalanced force at the gridpoint

unbalanced-force-z [blockhistoryoptions]

z-unbalanced force at the gridpoint

velocity [blockhistoryoptions]

the velocity magnitude at the gridpoint

velocity-x [blockhistoryoptions]

x-velocity at the gridpoint

velocity-y [blockhistoryoptions]

y-velocity at the gridpoint

velocity-z [blockhistoryoptions]

z-velocity at the gridpoint

block history Keyword Block

The following modifiers are available to specify additional information for the block history keywords. When using any of them, the location of the history must be specified using either position, zone-id, or gridpoint-id as described above.

component keyword

This keyword selects which scalar to retrieve from a vector type value, such as velocity or displacement. If the value type is not a vector, this setting is ignored. The available options are:

x

x-component of the vector

y

y-component of the vector

z

z-component of the vector

magnitude

vector magnitude

index i

For keywords that require it (most notably extra), this specifies the index that should be used. The default value will be 1.

gravity b

If on, then gravitational forces are included in the returned applied force. The default is off.

gridpointid i

Specifies the location of the history by the location of the gridpoint with ID number i.

label s

Assigns a label to the history, used in prints and plots.

log b

If on, the returned number is the base 10 log of the absolute value of the original value. The default is off.

method

This specifies the method of calculation used to bring zone-based quantities to arbitrary locations in space (including at gridpoint positions).

constant

Assumes values are constant inside zones. This is the default option. Values at gridpoints or at zone boundaries will pick one adjacent zone to use.

average

This uses an volume weighted average of all the zones connected to the gridpoint.

inverse-distance-weight

This uses an weighted average of up to 32 zones in the immediate vicinity of the point. The weighting is determined by a power of the distance of the zone centroid from the specified point.

power f

Specifies the power of the distance used to weight values. The default power is 3.0.

Specifies the ratio of the maximum distance from the point of the zones selected, to the ratio used to calculate weighted values. Zones farther from this value are discounted. The default value is 0.75.

polynomial <tolerance f >

Uses a fit to a polynomial function based on the zones in the vicinity of the point. Degenerate degrees of freedom are detected and removed. The optional tolerance flag can be used to change the value used to detect a degenerancy. The default value is 1e-7.

name s

Certain keywords (most notably property) require a name value to be fully specified. This will determine the specific property name retrieved.

position v

Specifies the location of the history at v. This location must be inside a zone.

quantity keyword

This keyword selects which scalar to retrieve from a symmetric tensor type value, such as stress or strain. If the value type is not a tensor, this setting is ignored. The available options are:

intermediate

intermediate principal stress

maximum

the maximum (most positive) value of principal stress. Note that in 3DEC compressive stresses are negative.

mean

The mean pressure value, defined as the trace of the tensor divided by 3. For stresses this is most often referred to as the pressure.

minimum

The minimum (most negative) principal stress. Note that in 3DEC compressive stresses are negative.

norm

The norm of the strain rate; see the equation in Zone Field Data Names

octahedral

octahedral stress; see the equation in Zone Field Data Names

shear-maximum

maximum shear stress

total-measure

distance of tensor value to the origin in principal space

volumetric

volumetric change, or trace

von-mises

Von Mises measure; see the equation in Zone Field Data Names

xx

xx-component of the tensor

xy

xy-component of the tensor

xz

xz-component of the tensor

yy

yy-component of the tensor

yz

yz-component of the tensor

zz

zz-component of the tensor

source keyword

Certain keywords (like extra and pore-pressure) can be retrieved either from the zone structure or from the gridpoint structure. The default value is gridpoint.

gridpoint

Values are retrieved directly from the gridpoint.

zone

stress b

A few of the tensor type quantity options do different things depending if the value is considered a stress. When coming from a value like extra, this cannot be determined automatically. This allows the user to specify that the incoming tensor value should be considered a stress quantity.

type keyword

In certain cases the type (scalar, vector, ro tensor) of the value cannot necessarily be determined ahead of time. Extra variables, for example, can hold values of all three types. This keyword allows one to specify which type it is assumed to be. If the original value type does not match, 0.0 is returned.

scalar

A scalar float type. This is the default.

vector

A vector type.

tensor

A tensor type.

zoneid i

Specifies the location of the history is at the centroid of zone with ID i.