`clump history`

command

Syntax

- clump history <name sid > keyword ...
Primary keywords:

displacement displacement-x displacement-y displacement-z euler-x euler-y euler-z extra force-contact force-contact-x force-contact-y force-contact-z force-unbalanced force-unbalanced-x force-unbalanced-y force-unbalanced-z moment-contact moment-contact-x moment-contact-y moment-contact-z moment-unbalanced moment-unbalanced-x moment-unbalanced-y moment-unbalanced-z position-x position-y position-z rotation spin spin-x spin-y spin-z stress velocity velocity-x velocity-y velocity-z

Adds a history of a clump value. A history is a table of floating point values assigned by sampling a model attribute periodically during a simulation. Review the common c history commands for details regarding the manipulation of histories.

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.

Following one of the keywords given below, either 1) an additional id keyword followed by an integer id, or 2) an additional position keyword followed by a position vector v must be given to define the specific clump.

- displacement [clumphistoryblock]
Magnitude of the accumulated clump displacement vector as a result of cycling.

- displacement-x [clumphistoryblock]
The \(x\)-component of accumulated displacement as a result of cycling.

- displacement-y [clumphistoryblock]
The \(y\)-component of accumulated displacement as a result of cycling.

- displacement-z (3D ONLY) [clumphistoryblock]
The \(z\)-component of accumulated displacement as a result of cycling.

- euler-x (3D ONLY) [clumphistoryblock]
The \(x\)-euler angle (in degrees) of the current clump orientation. The orientation is updated only when orientation tracking has been enabled (see the

`model orientation-tracking`

command). See the euler keyword of the`clump attribute`

command.

- euler-y (3D ONLY) [clumphistoryblock]
The \(y\)-euler angle (in degrees) of the current clump orientation. The orientation is updated only when orientation tracking has been enabled (see the

`model orientation-tracking`

command). See the euler keyword of the`clump attribute`

command.

- euler-z (3D ONLY) [clumphistoryblock]
The \(z\)-euler angle (in degrees) of the current clump orientation. The orientation is updated only when orientation tracking has been enabled (see the

`model orientation-tracking`

command). See the euler keyword of the`clump attribute`

command.

- extra [clumphistoryblock]
Take a history of an extra variable. Use index to specify the extra index and type to specify the type.

- force-contact [clumphistoryblock]
The magnitude of the force resulting from contacts.

- force-contact-x [clumphistoryblock]
The \(x\)-component of the contact force.

- force-contact-y [clumphistoryblock]
The \(y\)-component of the contact force.

- force-contact-z (3D ONLY) [clumphistoryblock]
The \(z\)-component of the contact force.

- force-unbalanced [clumphistoryblock]
The magnitude of the unbalanced force (sum of the applied, contact and gravitational forces).

- force-unbalanced-x [clumphistoryblock]
The \(x\)-component of the unbalanced force.

- force-unbalanced-y [clumphistoryblock]
The \(y\)-component of the unbalanced force.

- force-unbalanced-z (3D ONLY) [clumphistoryblock]
The \(z\)-component of the unbalanced force.

- moment-contact [clumphistoryblock]
{Value in 2D; Magnitude in 3D} of the sum of the contact moments.

- moment-contact-x (3D ONLY) [clumphistoryblock]
The \(x\)-component of the contact moment.

- moment-contact-y (3D ONLY) [clumphistoryblock]
The \(y\)-component of the contact moment.

- moment-contact-z (3D ONLY) [clumphistoryblock]
The \(z\)-component of the contact moment.

- moment-unbalanced [clumphistoryblock]
{Value in 2D; Magnitude in 3D} of the sum of the contact and applied moments.

- moment-unbalanced-x (3D ONLY) [clumphistoryblock]
The \(x\)-component of the unbalanced moment.

- moment-unbalanced-y (3D ONLY) [clumphistoryblock]
The \(y\)-component of the unbalanced moment.

- moment-unbalanced-z (3D ONLY) [clumphistoryblock]
The \(z\)-component of the unbalanced moment.

- position-x [clumphistoryblock]
The \(x\)-component of the location of clump centroid.

- position-y [clumphistoryblock]
The \(y\)-component of the location of clump centroid.

- position-z (3D ONLY) [clumphistoryblock]
The \(z\)-component of the location of clump centroid.

- rotation (2D ONLY) [clumphistoryblock]
Current clump orientation. The orientation is updated only when orientation tracking has been enabled (see

`model orientation-tracking`

command).

- spin [clumphistoryblock]
{Value in 2D; Magnitude in 3D} of the clump angular velocity in radians per second.

- spin-x (3D ONLY) [clumphistoryblock]
The \(x\)-component of the clump angular velocity in radians per second.

- spin-y (3D ONLY) [clumphistoryblock]
The \(y\)-component of the clump angular velocity in radians per second.

- spin-z (3D ONLY) [clumphistoryblock]
The \(z\)-component of the clump angular velocity in radians per second.

- stress [clumphistoryblock]
The clump stress. Use the quantity keyword to specify the quantity to be recorded.

- velocity [clumphistoryblock]
Magnitude of the clump translational velocity vector.

- velocity-x [clumphistoryblock]
The \(x\)-component of the clump velocity.

- velocity-y [clumphistoryblock]
The \(y\)-component of the clump velocity.

- velocity-z (3D ONLY) [clumphistoryblock]
The \(z\)-component of the clump velocity.

`clump history`

Keyword Block

The following modifiers are available to specify addition information for the `clump history`

keywords. They will not modify history values to which they are not applicable. In other words, the component keyword will not modify scalar or tensor values. `displacement`

, `displacement-x`

, `displacement-y`

, `displacement-z`

, `euler-x`

, `euler-y`

, `euler-z`

, `extra`

, `force-contact`

, `force-contact-x`

, `force-contact-y`

, `force-contact-z`

, `force-unbalanced`

, `force-unbalanced-x`

, `force-unbalanced-y`

, `force-unbalanced-z`

, `moment-contact`

, `moment-contact-x`

, `moment-contact-y`

, `moment-contact-z`

, `moment-unbalanced`

, `moment-unbalanced-x`

, `moment-unbalanced-y`

, `moment-unbalanced-z`

, `position-x`

, `position-y`

, `position-z`

, `rotation`

, `spin`

, `spin-x`

, `spin-y`

, `spin-z`

, `stress`

, `velocity`

, `velocity-x`

, `velocity-y`

and `velocity-z`

.

- 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
Record the \(x\)-component of the vector.

- y
Record the \(y\)-component of the vector.

- z (3D ONLY)
Record the \(z\)-component of the vector.

- magnitude
Record the vector magnitude.

- index i
For keywords that require it (most notably extra), this specifies the index that should be used.

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

- 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 (3D ONLY)
Record the intermediate principal value of the tensor.

- maximum
Record the maximum (most positive) principal value of the tensor. Note that compressive stresses are negative.

- mean
Record the mean value, defined as the trace of the tensor divided by { 2 in 2D; 3 in 3D}. For stresses this is most often referred to as the pressure.

- minimum
Record the minimum (most negative) principal value of the tensor. Note that compressive stresses are negative.

- norm
Record the norm of the full tensor. This is defined as the sum of each tensor component squared.

- octahedral (3D ONLY)
Record the octahedral measure of the tensor.

- shear-maximum
Record the maximum shear value.

- total-measure (3D ONLY)
Record the distance of the tensor value to the origin in principal space.

- volumetric
Record the volumetric change, or trace of the tensor.

- von-mises (3D ONLY)
Record the Von Mises measure.

- xx
Record the

xx-component of the tensor.

- xy
Record the

xy-component of the tensor.

- xz (3D ONLY)
Record the

xz-component of the tensor.

- yy
Record the

yy-component of the tensor.

- yz (3D ONLY)
Record the

yz-component of the tensor.

- zz (3D ONLY)
Record the

zz-component of the tensor.

- type keyword
In certain cases the type (scalar, vector, or 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
Specify a scalar float type.

- tensor
Specify a tensor type.

- vector
Specify a vector type.

Usage Examples

Record the \(z\)-component of position of clump with ID 1. The history is named `10`

.

```
clump history name '10' position-z id 1
```

Record the \(y\)-component of position of clump with ID 2.

```
clump history position-y id 2
```

CS: BEEFUP. ‘history’ for balls, clumps, etc is pretty thin. Greater use in examples seems advisable.

Was this helpful? ... | PFC © 2021, Itasca | Updated: Aug 19, 2023 |