Itasca - Flac3d 6.0 PDF

FLAC3D Elements Page 1 of 772
FLAC3D Elements
FLAC3D is a command-driven program, with the flexibility of the scripting language, FISH, added to it. Access to the command structure of the program and the ability to
manipulate it with FISH is at the heart of the modeling power of FLAC3D.
This section provides a description of all the program elements that are accessible via its commands and which, in turn, are also used by FISH. The various elements of
FLAC3D can be considered, informally, to comprise the areas below.
1. Program Operations - program-level operations that control current program execution and flow. These are found in the "Program" section. This section
also includes the FISH functions and facilities that are built into FISH (math functions, container functions, io functions, etc.) and are not specific to
FLAC3D or the other Itasca software products that use FISH.
2. Model Operations - high-level commands that affect the current model state, such as saving or restoring a FLAC3D model.
3. Project Operations - commands that affect the project state. These are not affected by the model new or model restore commands.
4. FLAC3D Model Objects - at heart, a FLAC3D model is composed of zones and structural elements. These logics, and associated commands/FISH
functions are described in their own sections.
5. General Model Objects - a large range of additional objects and model constructs (discrete fracture networks, tables, histories, user-defined data, etc.) are
also available in FLAC3D. These may be thought of as "general" because they are either ancillary or auxiliary to the core FLAC3D model. Also, they may
be found in other Itasca numerical modeling programs. Familiarity with their use in FLAC3D will usually confer an easy transition to their use in the other
Itasca software (3DEC, PFC2D, PFC3D) where they are found. Each individual object in this group is described in its own section.
Index of Elements
l Conventions
l Command Constructs
l Building-Blocks
l Data
l Discrete Fracture Network (DFN)
l Domain
l Extrude
l FISH
l Geometry
l Group
l History
l Model
l Plot
l Program
l Project
l Range
l Table
l Structural Elements
l Trace
l Zone
Was this topic helpful? Let us know...FLAC3D 6.0 © 2017, Itasca Consulting Group, Inc. Updated: Apr 17, 2019.
Conventions
FLAC3D operates within sets of conventions (e.g., stress, sign, systems of units, etc.). These conventions are outlined in this section.
l Sign Conventions
¡ Stress Sign Conventions
l Stress/Strain Invariants
l System of Units
Sign Conventions
The following sign conventions are used in FLAC3D, and must be kept in mind when entering input or evaluating results.
DIRECT STRESS — Positive stresses indicate tension; negative stresses indicate compression.
SHEAR STRESS — With reference to Figure 1, a positive shear stress points in the positive direction of the coordinate axis of the second subscript if it acts on a surface with
an outward normal in the positive direction. Conversely, if the outward normal of the surface is in the negative direction, then the positive shear stress points in the negative
direction of the coordinate axis of the second subscript. The shear stresses shown in Figure 1 are all positive. The stress tensor is symmetric (i.e., complementary shear
stresses are equal).
file:///C:/Users/sebas/AppData/Local/Temp/~hhE914.htm 10/07/2019
Figure 1: Sign convention for positive stress components.
DIRECT STRAIN — Positive strain indicates extension; negative strain indicates compression.
SHEAR STRAIN — Shear strain follows the convention of shear stress (see above).
PRESSURE — A positive pressure will act normal to, and in a direction toward, the surface of a body (i.e., push). A negative pressure will act normal to, and in a direction
away from, the surface of a body (i.e., pull). The next figure illustrates this convention:
Figure 2: Mechanical pressure: (a) positive; (b) negative
PORE PRESSURE — Fluid pore pressure is positive in compression. Negative pore pressure indicates fluid tension.
DIP, DIP DIRECTION — In FLAC3D, the global xyz-axes form a right-handed system. When dip and dip direction are specified, FLAC3D assumes the following: +y points
North (0 degrees azimuth); +x points East (+90 degrees azimuth); and +z points up. Dip direction is measured positive clockwise in the horizontal plane from North, which is
at 0 degrees azimuth. Dip is measured positive down from the horizontal plane.
VECTOR QUANTITIES — The x-, y- and z-components of vector quantities such as forces, displacements, and velocities are positive when pointing in the directions of the
x-, y- and z-axes.
Stress Sign Conventions

There are multiple commonly-used methods of referring to the three principal stress values. Consequently, this is an area that is particularly subject to engendering confusion.
It is important to remember at all times that in FLAC3D, positive stresses indicate tension; negative stresses indicate compression.
The table below summarizes some terminologies used to denote stress and how they relate to one another.
Table 1: Principal Stress Conventions

in Negative (-) Positive (+) Intermediate ( )
FLAC3D (σ1 ≤ σ2 ≤ σ3 by default ) minimum maximum intermediate
general usage major minor intermediate
symbols σ1 σ3 σ2
Stress/Strain Invariants
In FLAC3D, assuming is the deviatoric part of the stress tensor , and is the deviatoric part of the strain tensor , the stress/strain invariants in FLAC3D are defined
and summarized in Table 1.
For example, in a triaxial compression test, the cell pressure in the xy-plane is 100, the vertical compression pressure in the z-direction is 400, the stress tensor in the sample is
thus
According to equations in Table 1, we have
,
,
,
,
,
,
,
,
,
,
,
,
,
,
, and
.
Table 1: Stress/Strain Invariants

Stress Invariant Definition Strain Invariant Definition
1st stress invariant 1st strain invariant
2nd stress invariant 2nd strain invariant
3rd stress invariant 3rd strain invariant

volumetric stress volumetric strain
mean stress mean strain
1st deviatoric stress invariant 1st deviatoric strain invariant
2nd deviatoric stress invariant 2nd deviatoric strain invariant
3rd deviatoric stress invariant 3rd deviatoric strain invariant
stress Loge's angle strain Loge's angle
minimum principal stress minimum principal strain

intermediate principal stress intermediate principal strain
maximum principal stress maximum principal strain
von Mises equivalent stress von Mises equivalent strain
equivalent deviatoric stress equivalent (engineering) shear strain

octahedral stress octahedral strain
maximum shear stress maximum shear strain

stress norm strain norm
stress total measure strain total measure
System of Units
FLAC3D accepts any consistent set of engineering units. Examples of consistent sets of units for basic parameters are shown in the two tables below. The user should apply
great care when converting from one system of units to another. An excellent reference on the subject of units and conversion between the Imperial and SI systems can be
found in the Journal of Petroleum Technology (December 1977). No conversions except for quantities representing angles are performed in FLAC3D.
Angles are always entered on the command line (and in the user interface) in degrees, though they may be stored and used in radians. The exception is FISH, which (like most
programming languages) assumes all angle values are in radians.
Table 1: Systems of units — mechanical parameters

SI Imperial
Length m m m cm ft in
Density kg/m3 103 kg/m3 106 kg/m3 106 kg/m3 slugs/ft3 snails/in3
Force N KN MN Mdynes lbf lbf
Stress Pa kPa MPa bar lbf/ft2 psi
Gravity m/sec2 m/sec2 m/sec2 cm/s2 ft/sec2 in/sec2
where 1 bar = 106 dynes/cm2 = 105 N/m2 = 105 Pa;

1 atm = 1.013 bars = 14.7 psi = 2116 lbf/ft2 = 1.01325 × 105 Pa;
1 slug = 1 lbf -s2/ft = 14.59 kg;

1 snail = 1 lbf -s2/in; and
1 gravity = 9.81 m/s2 = 981 cm/s2 = 32.17 ft/s2.
Table 3: Systems of units — groundwater flow parameters

SI Imperial
Water bulk modulus Pa bar lbf/ft2 psi
Water density kg/m3 106 g/cm3 slugs/ft3 snails/in3

Permeability m3sec/kg 10-6 cm sec/g ft3 sec/slug in3 sec/snail
Intrinsic permeability m2 cm2 ft2 in2
Hydraulic conductivity m/sec cm/sec ft/sec in/sec
NOTE: FLAC3D permeability ≡ intrinsic permeability (in cm2) × 9.9 × 10-2

(in SI units) ≡ hydraulic conductivity (in cm/sec) × 1.02 × 10-6
FLAC3D permeability is the mobility coefficient (coefficient of pore pressure term in Darcy's law).
Systems of units for parameters associated with structural elements and heat transfer are given in in the sections on Structural Elements and Thermal Analysis, respectively.
Reference
Journal of Petroleum Technology. "The SI Metric System of Units and SPE's Tentative Metric Standard," pp. 1575-1616 (December 1977).
Command Constructs
When working with commands, there are number of very important sub-structures within the command tree that are frequently used and vital to the flexibility of FLAC3D.
These "command constructs" may be understood in their own right, and are described in this section.
[CS: "Undo" should maybe be given a topic here as well, or at least stubbed with a link to documentation elsewhere]
Contents of This Section
l Range
¡ The Range Phrase
¡ Logical Operations in a Range Phrase
¡ Named Ranges
¡ Range Phrase Keyword Reference
¡ FISH Functions
n range.find
n range.isin
l Group
¡ Commands
n group.create command
n group.list command
n group.rename command
n group.slot command
l Extra Variables
l Select & Hide
l Value Modifiers (Add, Multiply, Gradient, Vary)
Range
A command that does not have a range will operate on all possible target objects of the given command (e.g., zones, grid points, structural elements, etc.). A range, when
applied to a command, provides the means to restrict the operation of the command to a subset of target objects. The subset is defined by range elements, which are keywords
+ values following the range keyword in a command. The term range phrase refers to the combination of the range keyword and one or more range elements that follow. The
range phrase, when used, must always appear at the end of the command. The reference list of range elements can be accessed by clicking any range link throughout the
documentation.
The range logic is best understood as a command construct. That said, there is a model range command. The purpose of this command is to create or delete a named, user-
specified set of range elements. However, the resulting set (the "named range") is not applied to anything until it is utilized as a named-range element within a range.
Many commands accept a range phrase. A command signature that uses the range logic will always show the range phrase (<range>) as a final parameter (most often in angle
brackets to indicate it is optional). For example:
zone apply keyword ... <range>
Note
Unless a range phrase is used on a command, the action of any command in will be applied to all possible target objects of the command.
l The Range Phrase

l Logical Operations in a Range Phrase
l Named Ranges
l Range Phrase Keyword Reference
l FISH Functions
The Range Phrase

The term range phrase is a more explicitly descriptive way to refer to what is commonly referred to elsewhere in this documentation as the range. The components that make
up a range phrase (range keyword + range elements), seen in command signatures as <range>, are illustrated in the image below:
The brackets above the command indicate the command signature of the geometry copy command. The brackets below the command break down this particular instance of
the command to its components. Where a command signature indicates a <range> (brackets above), this will always start with the range keyword and contain at least one
range element (as broken down in the brackets below). A <range> might also include optional logical keywords or the extent keyword, though neither are shown in the
example above.
Where range elements are concerned, the main thing to observe is that a range element begins with an element keyword accepted by the initial range keyword (see the Range
Phrase Keyword Reference for a list of these), and normally ends when:
l all its parameters are specified, or

l when a new range element keyword is introduced, or
l if it is terminated with the not keyword (see Logical Operations in A Range Phrase for more information).
Logical Operations in a Range Phrase

A range phrase targets a set of objects by specifying one or more range elements (the keywords that follow the range keyword in the command). If multiple range elements are
specified, the final set of objects returned by the range phrase will be, by default, the intersection of the separate range elements.
The union keyword may be specified anywhere within a range phrase to return a range that is a union of the present range elements.
The not keyword may be used at the end of a particular range element to return the inverse of the objects specified by the element. The not keyword must appear at the end of
the range element specification (e.g., range position-x 0 100 not position-y 0 100 not).
When the keyword extent is used, the extent of the object (rather than the object centroid) is used to verify whether the object is within the range. This keyword is only applied
to geometric range elements (e.g., sphere).
Logical Operations & Named Ranges
Using the named-range keyword, an existing named range may be inserted into a range phrase and be treated as a range element within that range phrase. Consequently the
logical operations described above will work on a named range exactly as they do on range elements. See the next topic, Named Ranges, for further information.
Named Ranges
Creating a named range provides an easy-access method for subsequent use of the range. Range creation is performed using the model range command as follows:
model range create 'fred' position-x 5 500 id 100 200 group 'external' not
geometry group edge 'mainedges' range named-range 'fred'
This is equivalent to:
geometry group edge 'mainedges' range position-x 5 500 ...

id 100 200 group 'external' not
Note that, in the former case, the range fred could be reused without retyping all of the range elements.
Named Ranges vs. Groups
Named ranges and groups are close in effect. Either are used as range elements within a range. However, a named range is still a range, which means with each use it is
possible it will return different objects, depending the range elements that define it and the state of the model. By contrast, repeated uses of a group within a range will return
the same objects each time. The group itself must be altered to return different objects.
Range Phrase Keyword Reference

range keyword ...
Primary keywords:
union | use-hidden | selected | deselected | by | not | extent | annulus | component-id | cmodel | cylinder | dfn | aperture | distance | name | ellipse | extra | extra-list | fish |
geometry-distance | geometry-space | count | direction | inside | outside | set | group | id | id-list | interface | named-range | orientation | plane | polygon | position |
position-x | position-y | position-z | project-range | rectangle | seed | sphere | state | structure-type | surface
Create a range phrase. The range phrase (often "range" for short) is composed of one or more supplied range elements (keywords). Note the phrase may contain
multiple range elements, including multiple instances of the same range element (the group keyword, for instance). When multiple elements are present, by default
objects in the intersection of all range elements are affected.
If no range phrase is supplied with a command then all objects of the type affected by the command are affected.
Some keywords may specify behavior that modify the behavior of the whole range. These may be specified anywhere within a range, as long as they appear between
and not within range elements. They are:
union
Set the range to be a union of the range elements supplied (by default a range selects the intersection of all range elements). With this keyword in
place, if an object is selected by any of the range elements it is selected by the range, regardless of whether it is selected by any of the others.
use-hidden
Include hidden objects. By default, an object that has been hidden will never by included by a range. If this keyword is specified, hidden objects will
be considered. See Select & Hide.
selected
Include selected objects. This causes the range to only consider objects that are selected. See Select & Hide.
deselected
Include not selected objects. This causes the range to only consider objects that are not selected. See Select & Hide.
There are also several standard modifiers to range elements. These keywords must be given after the range element has been fully described, and modify how the range
element behaves. The available range element modifiers are:
by keyword
Many range elements will seek through an object hierarchy to determine if the object should be selected. For example, zone gridpoints will check if
any face they are attached to would be selected, or if any zone they are attached to will be selected. On occasion it is necessary to specify which type
of object should be considered for this purpose. Zone data types may specify zone-face, zone-gridpoint, or zone. Structural element data types may
specify structure-node, structure-link, or structure-element. Geometry data types may specify geometry-node, geometry-edge, geometry-polygon, or
geometry-set. Discrete fracture network data types may specify dfn, dfn-fracture, dfn-intersection, or dfn-intersection-set
not
Invert the range element's selection. Objects that would normally be selected are not, and vice versa. For example, to select everything except objects
with an x location between 1.0 and 2.0, use the range element position-x 1.0 2.0 not.
extent
Require the entire extent of the object to be inside the range element. This affects geometry-based range elements that select objects based on their
position (like sphere, position, etc.). If not specified, just the centroid position is required to consider the object within the range element. Not all
geometric range elements support this keyword.
The following keywords describe range elements that may be added to the range.
annulus keyword ...
Select objects within a spherical annular region. The region is defined by the center v, an inner radius of f1, and an outer radius of f2. This geometric element
supports the extent keyword.
center v
Define the center of the annulus. If not specified it defaults to the origin (0,0,0)
radius f1 f2
Define the inner (f1) and outer (f2) radius of the annulus. These values both default to 0.0 if not specified. If f1 > f2 there will be no selectable volume.
component-id i1 <i2 >
For most objects, this is the same as the id range element. It selects objects based on an ID number assigned to an object internally upon creation. For a few object
types (most notably in the structural element logic of FLAC3D), an ID number may refer to a user-defined number identifying a collection of objects. In this case
component-id range element refers to the internal unique ID number of the individual object.
cmodel s
Select zones with model names that match s. See the zone cmodel command for keyword names. Selects gridpoints or faces if they are attached to a zone with a
matching model name. All other object types are not selected.
cylinder keyword ...
Select objects in a cylinder. The cylinder (or cylindrical annulus) has a central axis starting at v1 and ending at v2 and a radius of fr1. This geometric element
supports the extent keyword.
end-1 v1
Specify the starting point of the cylinder's central axis. If not specified the default is (0,0,0).
end-2 v2
Specify the ending point of the cylinder's central axis. If not specified the default is (0,0,0).
radius fr1 <fr2 >
Specify the radius of the cylinder. If fr2 is specified, the range is a cylindrical annulus from fr1 to fr2.
dfn s keyword ...
Select objects based on their distance from the discrete fracture network with name s. Additional fracture networks can be added to the same element using the
name keyword. The extent keyword can be used with this element, and any fracture that actually intersects or is contained inside an extent is considered to have a
distance of 0.0.
aperture b
Use the aperture in the distance calculation. The fractures are expanded in the normal direction by 1/2 the aperture on each side for the distance
calculation.
distance f
Specify the distance from any fracture in the specified fractures within which objects will fall.
name s
Specify additional DFNs to include during distance testing.
ellipse
Select objects inside an elliptical cylinder. Four vectors define a planar rectangle in space, in which the ellipse is inscribed.
origin v
If this keyword is given, a truncated elliptical cone is generated with v the point of the cone and the ellipse inscribed int the rectangle given by vertices as a
surface.
vertices v1 v1 v1 v1
These vectors should describe a planar rectangle in space, in counter-clockwise winding. An elliptical cylinder extending infinitely perpendicular to this
plane is inscribed in the rectangle.
extra i f1 <keyword>
Filter based on the value in index i of the extra variables assigned to the object. The value is assumed to be of a numeric type (integer or real). If no additional
keywords are given, then values will be selected if they fall within 1.19e-7 times f1, or within 1.19e-7 if f1 is 0.0.
f2
If a second value is specified, then the element selects all values that fall between f1 and f2 inclusive.
tolerance f
If this keyword is given, then the element selects all values within a tolerance of f1. The tolerance given is f times f1, or just f if f1 is 0.0.
extra-list i i1 ...
Filter based on the value in index i of the extra variables assigned to the object. The value is assumed to be of integer type. Any number of integers may follow.
These numbers do not have to be sequential. The range element is optimized for efficient searching even if the amount of numbers supplied is large.
fish s
Invoke the user-defined range element that is implemented by the FISH function s, which must be declared as a function that takes two arguments. s will be called
for each object being queried for range inclusion. The first argument will be the position of the object, as a vector. The second argument will be a pointer to the
object itself. The object type can be determined using the FISH intrinsic type.pointer or type.pointer.name. If the object is not contained within the range,
then the value of s should be set to false within the function; if not set, the value of s defaults to true each time the function is called.
Because using this range element invokes FISH and may have side effects on the model state, it is not allowed to be included in plot windows.
geometry-distance s keyword
Select objects that fall within a certain distance of points, edges, and polygons defined in the geometry set named s. This geometric element accepts the extra
keyword. If the extent keyword is used, then objects that actually intersect elements in the geometry set are considered to be at a distance of 0.0. The following
keywords are available.
gap f
Define the maximum distance from the set for an object to be selected. If not specified, a value of 0.0 will be used.
set s
Add an additional geometry set named s to the list of those checked.
geometry-space s keyword
Select objects by their location in relation to the polygons in the geometry set named s. A direction vector is specified, and a ray is emitted from the location of
the object in that direction. The number of times that ray intersects geometry polygons is counted. Objects can be selected with a given count value.
If the polygons in a set form a topologically closed volume (or close enough for this purpose), then an odd numbered count will be inside the volume and an even
numbered count will be outside. The geometry logic will detect the creation of topologically closed volumes, and allow the use of the inside and outside keywords
on that data. If not perfectly closed, the count odd or count even can be used to approximate this.
Note that geometric data can include multiple separate polygons at the same location in space, and if present this can alter the counting process.
count keyword
Select locations based on their intersection count. There are three possible options based on count:
Select objects with this exact intersection count. This can be used to select specific regions within a complex set of surfaces, regardless
of whether they are closed or intersect.
even
Select objects with an even numbered intersection count. If polygons form a perfectly closed volume, or act like it for this purpose, this
will select objects outside the volume.
odd
Select objects with an odd numbered intersection count. If polygons form a perfectly closed volume, or act like it for this purpose, this
will select objects inside the volume.
direction v
Specifies the direction the of ray projected from the location being checked. By default this direction is (0,0,1).
inside
Selects objects inside topologically closed volumes.
outside
Selects objects outside topologically closed volumes.
set s
adds an additional geometry set named s to the list of those checked.
group s keyword
Select objects associated with the group s. Use of the group logic is described in the Group section of Command Constructs.
Both the group and the slot can be encoded into the single string s. To do this use the construction 'slotname=groupname', where the name to the left of the equals
sign will be the slot, and the name to the right will be the group.
and s
allows the addition of an additional group. The object must contain both groups (in separate slots) to be considered a part of the range. This cannot be
combined with the or keyword or the slot keyword. Note that the 'slotname=groupname' construction can be used here. Any number of and keywords may
be combined.
by keyword
For objects that participate in a hierarchy (for example, gridpoints connected to faces connected to zones), more than one object may match the group
specification. By default if any match the object is considered selected. This keyword can be used to restrict the object type to be considered for a match,
independent of the object type being selected. For example, by zone could be used to only select grid points connected to zones belonging to a certain
group, independent of whether the grid points themselves belonged to the group.
While more keywords are available, the following list are the only ones generally needed:
geometry-edge
geometry-polygon
geometry-set
structure-element
structure-node
zone
zone-face
matches i
For objects that participate in a hierarchy (for example, gridpoints connected to faces connected to zones), more than one object may match the group
specification. By default if any match the object is considered selected. This keyword can be used to require that more than one object match is necessary.
only
Indicate that the object must match the list of groups specified and no others for it to be selected. For example, if the specification was group 'fred' and
'george' only then an object that belonged to groups fred and george would be selected only if it had no additional groups assigned as well.
or s
Allow the addition of an additional group. The object will be selected if it matches any of the groups provided. This cannot be combined with the and
keyword or the only keyword. Note that the 'slotname=groupname' construction can be used here.
slot s
Specify which group slot on the object will be searched. This value will be overridden by group names that encode the slot name in their string. If no slot is
specified then the group will be checked in all slots the objects contains.
id il <iu >
Select objects with the ID numbers specified. The interval (il, iu) is inclusive — if iu is not specified, then iu is set equal to il.
id-list i1 ...
Selects objects with ID numbers that match the list of ID numbers supplied. These ID numbers do not have to be sequential. The range element is optimized for
efficient searching even if a large number of ID numbers is supplied.
interface s1 ...
Select objects associated with the interfaces with matching names. Any number of interface names may be specified, the element will return a match if the object
is associated with any of them.
This can be used to select interfaces, interface nodes, and interface elements.
It can also be used to select zones, zone faces, and zone gridpoints that are attached or connected to the interface. If the interface has been created but has not yet
been cycled with a model solve or model cycle command, then contact detection has not been performed and objects on the target side will not be selected.
named-range s
Use the named range s as an element within the current range phrase. See the command model range create.
orientation keyword
Select objects with a matching orientation, or direction in space. The orientation may be specified by dip and dip-direction, or by a normal vector.
Currently, this element can only be used with zone, zone face, or zone gridpoint objects. Zone faces are selected by the face normal vector. Zones are selected if
any of their faces are selected. And zone gridpoints are selected if any face they are connected to are selected.
dip f
Specify the orientation dip in degrees — the orientation is defined as the normal vector of the plane with this dip.
dip-direction f
Specify the orientation dip direction in degrees — the orientation is defined as the normal vector of the plane with this dip-direction.
normal v
Specify the orientation as a vector.
tolerance f
Specify the orientation tolerance. The object will be selected if its orientation falls within f degrees of the given one. The default value is 2.0 degrees.
plane keyword
Select by region surrounding an infinite plane. The plane is defined by origin and dip and dip-direction, or normal. The region surrounding the plane is defined by
either above, below, or distance. This is geometric element accepts the extra keyword.
above
half-space above the plane
below
half-space below the plane
dip-direction f
dip-direction angle [degrees], measured in the global xy-plane, clockwise from the positive y-axis
dip f
dip angle [degrees], measured in the negative z-direction from the global xy-plane
distance f
region within distance f of the plane
normal v
unit normal vector of the plane
origin v
a point on the plane
polygon keyword
Select objects inside an polygonal cylinder. A set of vectors define a planar polygon in space. The volume of selection is the polygonal cylinder created by
extruding that polygon normal to the plane surface infinitely in both directions.
origin v
If this keyword is given, a truncated polygonal cone is generated with v the point of the cone and the polygon described by the vectors in vertices.
vertices v1 ...
These vectors should describe a planar polygon in space. A polygonal cylinder extending infinitely perpendicular to this plane is selected.
position vl <keyword>
Select objects with coordinates inside the box defined by the lower-bound point, vl, and upper-bound point, vu. This geometric element accepts the extent range
element modifier.
If vu is not specified, then tolerance defines the lower-bound point as vl - (f,f,f) and the upper-bound point as vl + (f,f,f) * vl. Note that a tolerance should only be
specified if vu is not specified.
vu
Indicate that objects are selected if their location falls within the box defined by vl and vu.
tolerance f
Indicate that objects are selected if their location falls within the box defined by vl +/- (f,f,f) * :vec:`vl
position-x fl <keyword>
Select objects by the x component of their locations. If no additional keywords are given, then values will be selected if they fall within 1.19e-7 times f1, or
within 1.19e-7 if f1 is 0.0. This geometric element accepts the extent range element modifier.
f2
Specify an endpoint. If specified, the element selects all values that fall between f1 and f2 inclusive.
tolerance f
Specify a tolerance. If specified, the element selects all values within a tolerance of f1. The tolerance given is f times f1, or just f if f1 is 0.0.
position-y fl <keyword>
Select objects by the y component of their locations. If no additional keywords are given, then values will be selected if they fall within 1.19e-7 times f1, or
f2
tolerance f
position-z fl <keyword>
Select objects by the z component of their locations. If no additional keywords are given, then values will be selected if they fall within 1.19e-7 times f1, or
f2
tolerance f
project-range s
Inserts the project named range s as an element within the current range phrase. Project named ranges can be created in the user interface, and may only be used
validly in plotting commands. In other contexts it will produce an error.
rectangle keyword
Select objects inside a rectangular cylinder. A set of four vectors define a planar rectangle in space. The volume of selection is the rectangular cylinder created by
extruding that rectangle normal to the plane surface infinitely in both directions.
origin v
If this keyword is given, a truncated rectangular cone is generated with v the point of the cone and the rectangle described by the vectors in vertices.
vertices v1 ...
These vectors should describe a planar rectangle in space. A rectangular cylinder extending infinitely perpendicular to this plane is selected.
seed vsource vdir keyword
Select by seed zone face. The seed face is obtained by defining a ray starting at vsource and extending in the direction vdir. The seed face is the first visible zone
face the ray intersects. The properties of that face are used to determine the selection criteria for objects in the range, based on the keyword supplied. For
example, if the group keyword was used, and the first face struck has a group assignment fred in slot Default, then all objects that contained that group
assignment (and no others) would be selected.
cmodel
Select based on the mechanical constitutive model assigned to the zone the face belongs to.
group <slot s >
Select based on the group(s) assigned to the face. If the optional slot keyword is used to specify a slot, on the contents of that slot is matched. Use of the
group logic is described in Group.
uniform
Selects all objects.
sphere <keyword> ...
Selects objects in a spherical region. This geometric element accepts the extent range element modifier.
center v
Specifies the center of the sphere. By default this value is (0,0,0).
radius f
Specifies the radius of the sphere. By default this value is 0.0.
state s
Select objects by the state indicators of the zone constitutive model. The s is matched to any state name returned by the constitutive model. Zones reporting that
state will be selected by the element.
Zone gridpoints and zone faces will be selected if any zone they are attached to is selected.
The following keywords change how the zone state is reported, based on the separate states kept in their component tetrahedra overlays.
any
The zone is considered to have that state if any of its internal tetrahedra have that state.
average
The zone is considered to have that state only if at least 50% of the tetrahedra (by volume) have that state. This is the default.
structure-type keyword
Select structural elements of a specific type. The available type keywords are beam, cable, geogrid, liner, pile, shell, and the special keyword any, which indicates
that any element type is acceptable.
Structural nodes or links are selected if any of the elements they are connected to is selected.
surface keyword
Select zone faces if they fall on the "surface" of the model, which is defined as a face with only one zone connected to it, or a face with only one valid non-null
zone connected to it.
By default only the mechanical model is used to determine if a zone is null. The following keywords can control how a null zone is determined for this purpose.
Note that if any keyword is given, the default mechanical setting is not assumed and must be given explicitly.
fluid
The fluid model is used to determine null.
mechanical
The mechanical model is used to determine null.
or
By default, if multiple criteria are specified, then all of them must be null for the zone to be considered null as a whole. If this keyword is used, then the
zone will be considered null if any of them are null.
thermal
The thermal model is used to determine null.
FISH Functions
The type specifiers used in the FISH function signatures are given in the "FISH Type Index" section.
Range Utilities
range.find(STR)
Find a named range.
range.isin(RAN_PNT,IND/PNT/VEC)
Determine range inclusion status.
l range.find
l range.isin
range.find
Syntax
r = range.find(s)
Find a named range.
Returns: r - range pointer
range.isin
Syntax
b = range.isin(r,a)
Determine range inclusion status.
Returns: b - range inclusion status

Arguments: r - range pointer
a - index, pointer, or vector
Group
A group is a label applied to an object as means of categorization. Imagine that you have three household things consisting of a chair, a rug, and a painting. One might wish to
categorize these things by their resting location (floor, floor and wall, respectively) or by their their purpose (to sit on, to stand on and to look at, respectively). Each object can
be described by a number of attributes and, by undertaking such categorization, it is possible to ask questions about the set. For instance, we may wish to query the set of
household objects to find the things whose resting location is floor (i.e., chair and rug).
The group logic is the tool used in FLAC3D to categorize model objects. One can think of a group slot as being a meaningful name corresponding to the attribute in question
(i.e., resting_location or purpose in the example above). The group name, on the other hand, is the value the attribute takes for the object. For instance, the chair belongs to
group floor in slot resting_location, meaning its resting location is on the floor. Chair also belongs to group to_sit_on in slot purpose, meaning the purpose of the chair is to sit
on. In fact, in a model, any number of group names may be specified, and up to 128 different slot names may be used.
To shift to a geomechanical context, one might wish to undertake a staged excavation sequence where each step consists of removing parts of the model successively. Using
the group logic, one can imagine creating group slots named stage1, stage2, etc. corresponding to each stage of the excavation. Within stage1 of excavation there could be
objects belonging to groups first, second, etc. This gives the user a way to remove the first, second, etc. parts of the model in stage1, the first, second, etc. parts of the model in
stage2, and so on.
The objects are "members" of the group and will persist so until a subsequent command either removes them from the group, removes the group itself, or assigns them to a
different group in the specified slot. Contrast this with a range, which, used at different times in a model, might return different objects with location falling in a specific
range, for instance. Groups may be removed, though this does not cause their member objects to be removed or deleted from the model. Commands may assign groups based
on various criteria as a command operation proceeds.
As explained above, groups are always a combination of two components: the group slot, and the group name. For convenience, it is easy to assign objects to a group name
without specifying a slot. In such cases, the default slot assignment is used. For any "unslotted" group, the default slot assignment is the slot named Default.
There are two cardinal rules to keep in mind when working with groups.
l an object may belong to only one group within a given slot

l group-slot assignments adhere to command overwrite logic; an object assignment to a group in a given slot will be overwritten if that object is later assigned to another
group in the same slot. However, if the latter group assignment occurs in a new or different slot, overwriting does not occur.
The second rule illustrates the need for slots: they provide a way to put the same object into different groups without conflict, allowing for rather complex intersections of
named objects to be achieved.
Consider the following explicit example using scalar objects for explanatory purposes.
data scalar group "one" slot "main" range id 1,5

data scalar group "two" slot "main" range id 1,10
data scalar group "three" slot "main" range id 1,5
data scalar group "two" slot "mane" range id 6,10
Once processed, we have:
l no scalars are assigned group "one" in slot "main" (the assignment made in the first line is overwritten by the assignment in the second line)
l scalars with id 6-10 are assigned group "two" in slot "main"
l scalars with id 1-5 are assigned group "three" in slot "main"
l scalars with id 6-10 are assigned group "two" in slot "mane"
The scalars with id 6-10 are in two groups that have the same name ("two"). However, the two groups are in different slots ("main" and "mane"), so there is no conflict over
group membership nor over the group name.
One more example is presented to demonstrate how multiple group assignments can be used effectively, with an intersection, to remove an object.
data scalar create (1,0,0)

data scalar group "left-most" slot "position1" range position-x 1,5
data scalar group "right-most" slot "position2" range position-x 5,10
data scalar delete range group "left-most" and "right-most"
The first three lines create three scalars at different locations. The next two lines assign group names to the left-most and right-most sets of scalars. Finally, the central scalar
is deleted as it belongs to both the "left-most" and "right-most" slots, using the group range element.
Alternate Syntax
The typical formulation of the group name and the group slot assignment takes the form group "groupname" slot "slotname", as appears here.
data scalar group "groupname" slot "slotname" range position-x 100 2000
However, a valid alternate construction is slotname = groupname. With this construction the command above takes the form
data scalar group "slotname = groupname" range position-x 100 2000
where slotname is the slot assignment and groupname is the group name. Quotation marks are required, but spaces at the equals sign (if present) are ignored.
Data Heirarchies
Certain data structures are related to each other through a heirarchy. For example, in the geometry logic points are connected to edges, which are themselves connected to
polygons. In FLAC3D grid points are connected to faces which are connected to zones.
By default, in most cases when a data type participates in a heirarchy the group logic will automatically move up the heirarchy when checking for group matches. So if the
logic is checking that a geometry node is in the group sFred, it will find a match if that node is directly part of that group or if an edge or a polygon connected to that node is
part of that group.
The group logic will never move down the heirarchy, so it will never find a polygon as a member of group sFred unless the polygon itself is directly a member of that group.
Even if every edge and node of the polygon is a member of the group.
This affects the group range element and the .isgroup family of FISH intrinsics. The by keyword can be used in the range element to restrict this behavior.
Groups vs. Named Ranges
The group and the named range have similarities, but there is a critical difference. A range is always a set of criteria for selecting a set of objects, and it may return different
results at different times, depending on the behavior of the model and the definition of the range. Also, a named range can be applied to different types objects. A group is
always a collection of a specific set of objects of a specific type that will change only if group members are deleted or if they are overwritten to a new group in the same slot
(see above).
l Commands
Commands
Commands that operate on the list of group names and slots.
A global list of all group names (in all slots) and all slots created is maintained. It is possible view (group list) and rename (group rename) those items.
Group assignments are made with the group keyword operating on a specific data type (like zone group, geometry group, extrude edge group, etc.).
Group Commands
group create
Create a group.
group list
Display the global list of group names and slot names...
group rename
Rename a group.
group slot
Create a slot.
l group.create command
l group.list command
l group.rename command
l group.slot command
group.create command
Syntax
group create s
Create a group. The name s is given to the group. The group has no objects, however.
group.list command
Syntax
group list
Display the global list of group names and slot names that have been created.
group.rename command
Syntax
group rename sold snew
Rename a group. The group named sold is renamed to snew. All references to group sold, in all objects and slots, now instead refer to snew.
group.slot command
Syntax
group slot keyword

create s
Create a slot. The slot is named s. No objects or groups use this slot on creation. It will, however, show up on the list of available slots in the user interface.
rename sold snew
Find the slot named sold and rename it to snew. All objects and groups referring to that slot are unchanged, except they now belong to snew.
Extra Variables
Most model objects (zones, gridpoints, structural elements, etc.) have extra storage for user-defined variables to be assigned and visualized. For instance, supposed that one
wants to store the maximum and minimum stresses of each zone at one instant of time during a simulation. This information can be stored in extra variables associated with
each zone.
fish define setExtra

loop foreach local z zone.list
zone.extra(z,1) = zone.stress.min(z)
zone.extra(z,2) = zone.stress.max(z)
endloop
end
In this case the second argument to the zone.extra FISH intrinsic is the index of the corresponding extra variable. Thus multiple extra variables (up to 128) can be assigned
to each model object that has the extra variable capability. Also note that extra variables can be of any type which has a corresponding FISH type (i.e., boolean, integer, float,
string, vector, matrix, etc.).
[CS: it might be useful to just have a list here of the model objects that provide an extra variable]
Select & Hide

The select and hide concepts have been introduced to allow for more flexibility in visualization and model assignment operations. Selection/hiding can be interactive, using
the Model pane, or can be completely command driven — noting that in either case the selection or hidden status of objects is part of the model state and therefore will affect
results of subsequent commands.
When objects are hidden, commands do not operate on them — they are "invisible" to commands. The objects are still in the model, though, and cycling computations on
hidden objects (i.e., the equations of motion computations) are not affected.
Interactive selection of objects in the Model pane is a necessary precursor to performing a subsequent interactive command operations on them (grouping with the group tool (
), for instance). However, as with hiding, there are model state implications as well. With regard to the command line, a selected set of objects may be easily targeted by a
command using the selected keyword of the range logic.
See the Select and Hide topic in the Problem Solving with FLAC3D section for fuller discussion.
Value Modifiers (Add, Multiply, Gradient, Vary)

When setting values (for instance assigning a property, an initial condition, or applying a force to zones or faces) it is possible to do a simple assignment, to perform
arithmetic adjustment (add, multiply) to the existing value, and to supply a linear distribution in space (gradient, vary). Commands that set values will not necessarily supply
each type of modification. However, when these modifiers are available, they will operate in the manner described here.
Add
The add keyword is simplest. It adds the supplied value to an existing value. If the gradient or vary keywords are used, they apply to the value added.
Multiply
The multiply keyword multiplies the existing value by the factor supplied with the keyword. If the gradient or vary keywords are used, they apply to the factor.
Gradient
The gradient keyword provides a method for specifying a linear variation of the value. It takes the form:
gradient v <origin v>
Consider the following command.
zone apply force-y 1.0 gradient (2,4,3) origin (1,2,3) range pos-y 1 10
For each zone in the range range y=1 to y=10, apply a gradient to the y-force in the zones as follows. Take the base value (1.0) and add to it a value that is:
2 times the zone's x-component minus 1 plus

4 times the zone's y-component minus 2 plus
3 times the zone's z-component minus 3.
The value varies according to the relation:
When using gradient, value is supplied before the gradient keyword (that is, it is the "pre-modified" value supplied for the command); p is the position of the object; o is the
origin of the calculation, and v is the gradient factor.
The origin keyword is optional and defaults to (0,0,0).
Gradient Errors
If the vector gradient keyword is applied to a vector value (e.g., displacement 1 3 5 gradient 2 4 3), an error will occur.
Vary
The vary keyword provides a method for specifying a linear variation. This will vary a component value across the x-, y-, and z-extent of a selected range. Consider the
following command.
zone apply force-y 1.0 vary (2,4,3) range pos-y 1 10
Given the zones whose centroids lie in the range between y=1 and y=10, vary the y-force applied to the zones as follows. Take the base value (1.0) and add to it a value that
varies from 0-2 over the x-extent of the range, 0-4 over the y-extent, and 0-3 over the z-extent.
The value varies according to the relation
where l is the vector lower bound of the extent, u is the vector upper bound of the extent, v is the vary vector, and p is the vector position of the object.
Vary Errors
If the vector vary keyword is applied to a vector value (e.g., displacement 1 3 5 vary 2 4 3), an error will occur.
Building-Blocks
The building block logic is primarily accessed interactively via the Building-Block pane. This logic allows one to easily create models interactively. With each mouse click
and drag in the pane, building-block commands are emitted and recorded for future reference, allowing these interactive operations to be redone/undone (see the program
undo command for further details). In this section the commands and FISH functions allowing access to the building-block data are presented.
l Commands
l FISH Functions
Commands
Operate on building-blocks. These are grouped below as block commands, face commands, edge commands, point commands, and set commands.
Building-Blocks Block commands
building-blocks block create

Create a block or blocks.
building-blocks block delete
Delete blocks.
building-blocks block export
Export blocks.
building-blocks block group
Assign or remove a group name to blocks.
building-blocks block hide
Set the blocks to be hide or not.
building-blocks block id
Perform an operation on a block (by ID).
building-blocks block import
Import blocks from a file.
building-blocks block list
Print information about blocks.
building-blocks block make-hex-only
Split all triangular faces of wedge and tetrahedral blocks.
building-blocks block multiplier
Set the zone multiplier coefficient for final zone generation.
building-blocks block snapon
Snap a block to a geometric set.
building-blocks block transform
Perform a general geometric transformation on points of blocks.
Building-Blocks Face commands
building-blocks face cycle

Rotate (cycle) the topology of triangular faces.
building-blocks face delete
Delete faces.
building-blocks face drape
Move the points of faces onto an external geometric set.
building-blocks face group
Assign a group name to faces.
building-blocks face list
Print information about faces.
building-blocks face snapon
Snap a face to a geometric set.
building-blocks face transform
Transform a face (via its points).
Building-Blocks Edge commands
building-blocks edge add-controls

Add control points to edges.
building-blocks edge delete
Delete edges.
building-blocks edge drape
Move the points of edges onto an external geometric set.
building-blocks edge factor
Apply a sizing factor to zones on edges.
building-blocks edge group
Assign or remove a group name to edges.
building-blocks edge id
Modify the properties of an edge.
building-blocks edge list
Print information about edges.
building-blocks edge ratio
Apply a sizing ratio to zones on edges.
building-blocks edge ratio-isolate
Determine whether zone ratios or factors propagate.
building-blocks edge size
Specify the number of zones on an edge.
building-blocks edge snapon
Snap an edge to a geometric set.
building-blocks edge transform
Transform and edge (via its points).
building-blocks edge type
Specify edge curve-type.
Building-Blocks Point commands
building-blocks point delete

Delete points.
building-blocks point drape
Move points onto an external geometric set.
building-blocks point group
Assign a group name to points.
building-blocks point list
Print information about points.
building-blocks point merge
Merge two points.
building-blocks point move-to
Move points.
building-blocks point snapon
Snap points to a geometric set.
building-blocks point transform
Transform points.
Building-Blocks Set commands
building-blocks set arrest-triangle

Specify how to split a wedge block.
building-blocks set auto-tolerance
Set the auto-tolerance flag for geometric manipulations.
building-blocks set automatic-zone
Specify a automatic zoning method.
building-blocks set break-angle
Set the break angle.
building-blocks set create
Create a building block set.
building-blocks set delete
Delete a building block set.
building-blocks set export
Export current building blocks to a file.
building-blocks set geometry
Associate a geometry set with the current set.
building-blocks set import
Import a building blocks set.
building-blocks set list
Print information about a building blocks set.
building-blocks set select
Specify the current building blocks set.
building-blocks set tolerance
Set the tolerance for geometric manipulations.
building-blocks set validate-all
Check the validity of blocks.
l building-blocks block create command

l building-blocks block delete command
l building-blocks block export command
l building-blocks block group command
l building-blocks block hide command
l building-blocks block id command
l building-blocks block import command
l building-blocks block list command
l building-blocks block make-hex-only command
l building-blocks block multiplier command
l building-blocks block snapon id command
l building-blocks block transform command
l building-blocks edge add-controls command
l building-blocks edge delete command
l building-blocks edge drape command
l building-blocks edge factor command
l building-blocks edge group command
l building-blocks edge id command
l building-blocks edge list command
l building-blocks edge ratio command
l building-blocks edge ratio-isolate command

l building-blocks edge size command
l building-blocks edge snapon id command
l building-blocks edge transform command
l building-blocks edge type command
l building-blocks face cycle command
l building-blocks face delete command
l building-blocks face drape command
l building-blocks face group command
l building-blocks face list command
l building-blocks face snapon id command
l building-blocks face transform command
l building-blocks point delete command
l building-blocks point drape command
l building-blocks point group command
l building-blocks point list command
l building-blocks point merge command
l building-blocks point move-to command
l building-blocks point snapon id command
l building-blocks point transform command
l building-blocks set arrest-triangle command
l building-blocks set automatic-zone command
l building-blocks set auto-tolerance command
l building-blocks set break-angle command
l building-blocks set create command
l building-blocks set delete command
l building-blocks set export command
l building-blocks set geometry command
l building-blocks set import command
l building-blocks set list command
l building-blocks set select command
l building-blocks set tolerance command
l building-blocks set validate-all command
building-blocks block create command

Syntax
building-blocks block create keyword
Primary keywords:
from-faces | hexahedron | tetrahedron | wedge
Create a block or blocks.
from-faces <distance f > range
Create blocks attached to the faces specified by the range. All faces here must be external faces — each face is attached to one block only. New blocks will be
"extruded" from the faces along the average face normal. The extruded distance is defined by f. If f is not supplied the default distance will be related to the
maximum diagonal extent of a block among all the blocks attached to supplied faces.
hexahedron <by-points v1 v2 v3 v4 v5 v6 v7 v8 > <group s <slot s >>
Create a hexahedral block. by-points, if present, must be followed by points that define the block (a hexahedron requires eight points). The optional keywords
group and slot assign the created block to the specified group and slot.
tetrahedron <by-points v1 v2 v3 v4 > <group s <slot s >>
Create a tetrahedral block. by-points, if present, must be followed by points that define the block (a tetrahedron requires four points). The optional keywords
group and slot assign the created block to the specified group and slot.
wedge <by-points v1 v2 v3 v4 v5 v6 > <group s <slot s >>
Create a wedge block. by-points, if present, must be followed by points that define the block (a wedge requires six points). The optional keywords group and slot
assign the created block to the specified group and slot.
building-blocks block delete command

Syntax
building-blocks block delete <range>
Delete blocks. If <range> is not supplied, all blocks will be deleted.
building-blocks block export command

Syntax
building-blocks block export keyword <range>
Export blocks. If <range> is not supplied, all blocks will be exported.
to-file s
Export the blocks to a file named s.
to-set s <offset v >
Export the blocks to a building block set named s. If the optional <offset v> is supplied, all coordinates will be shifted by that vector in the destination set.
to-geometry-set s
Export the blocks to a geometric set named s. It only creates "external" faces of the supplied blocks as a set of polygons (quads or triangles).
building-blocks block group command

Syntax
building-blocks block group s <slot s > <remove> <range>
Assign or remove a group name to blocks. If remove is present, the group name will be removed from blocks in the specified range. If <range> is not supplied, all
blocks are affected.
building-blocks block hide command

Syntax
building-blocks block hide b <range>
Set the blocks to be hide or not.
building-blocks block id command

Syntax
building-blocks block id i keyword
Perform an operation on a block (by ID). The operation is performed on block ID i in the current building blocks set.
split face-id i2 v1 v2
Split a block. The splitting is defined by the splitting line on a block face with id i2. The splitting line is defined by the points v1 and v2.
When the points are on opposite edges of a face this is called an edge-to-edge split.
When the points are on opposite corners of a face this is called a diagonal split.
When the points are on a corner and opposite edge of a face this is called a corner split.
When the points are inside a face this is a central split, in which case v1 must be equal to v2 within the tolerance (see building-blocks set tolerance). In the
case of a triangular face, it will be treated as the central point of the triangle. The split will start with two cross-split lines with a central point.
The splitting of the block will propagate to the next face-attached block until blocks with already-split faces are reached.
building-blocks block import command

Syntax
building-blocks block import keyword
Import blocks from a file.
from-file name s <position|offset v >
Import blocks from the file named s. <position v>, if supplied, provides the position the imported blocks. <offset v>, if supplied, provides the translational offset
(shift) vector for the imported blocks.
building-blocks block list command

Syntax
building-blocks block list keyword <range>
Primary keywords:
edges | extra | faces | group | information | nodes | status
Print information about blocks. If <range> is not supplied, the requested information is listed for all blocks in the current building blocks set.
edges
Edge IDs for each block are listed.
extra i
FISH extra information printed. A valid index i must be supplied.
faces
Face IDs for each block are listed.
group
Group information is listed.
information
Comprehensive information is listed, including groups, extras, degeneracy, and zone multiplier.
nodes
Node IDs for each block are listed.
status
Validation status for each block is listed.
building-blocks block make-hex-only command

Syntax
building-blocks block make-hex-only
Split all triangular faces of wedge and tetrahedral blocks. The faces will be split into quads by a central point split. After this command is given only hexahedral blocks
remain in the current building blocks set.
building-blocks block multiplier command

Syntax
building-blocks block multiplier i <range>
Set the zone multiplier coefficient for final zone generation. The default value is 1. It will be applied to zone generation after all edge sizes and ratios are taken into
account. If <range> is not supplied, all blocks will be modified.
building-blocks block snapon id command

Syntax
building-blocks block snapon id i set s keyword <control-point b > <range>
Primary keywords:
edge | point | polygon
Snap a block to a geometric set. Points are translated on blocks that are in the specified <range>, if supplied. If not, all points are translated.
A translation vector is defined from the point with id i in the current building blocks set to the target point on a geometric set s.
The target point on a geometric set is specified by keyword. The <control-point b> option indicates whether control-points on an edge should move if the points
defining that edge are moved. The default is true.
edge id i <f >
The target point is on the edge in the geometric set with id i. The exact location on the edge is defined by float number parameter f. If f = 0.0 the target point is the
first (start) point of the edge, if f = 1.0 the target point is the second (end) point of the edge. The default value is f = 0.5 (center of the edge).
point id i
The target point is the point with id i of the geometric set.
polygon id i <(f1, f2 )>
The target point is on the polygon in the geometric set with id i. The exact point on the polygon is defined by two local coordinates (f1, f2) defined in such a way
that (0.0,0.0) corresponds to centroid of the polygon. By default (f1, f2) is always set initially to correspond to the centroid of the polygon.
building-blocks block transform command

Syntax
building-blocks block transform <origin v > keyword <control-point b > <range>
Primary keywords:
reflect | rotate | scale | translate
Perform a general geometric transformation on points of blocks. If <range> is not specified all blocks are transformed.
For those options that require an origin (rotate, reflect, and scale) the optional origin may be supplied to specify the origin for the operation.
The <control-point b> option indicates whether control-points on an edge should move if only one of the points of that edge is moved. The default is true. The option
has no effect with reflect keyword.
reflect keyword
Make a reflection transformation about a plane.
dip f1 dip-direction f2
Specify the mirror plane defined by dip angle f1 and dip direction f2. Angles are defined in degrees.
plane v_1 v_2 v_3
Specify the mirror plane defined by three points v_1 v_2 v_3.
rotate direction v angle f
Perform a rotation by angle f, in degrees, using rotation axes that go through the coordinate origin in the direction v.
scale v
Scale the point positions by expanding or contracting their distance from the origin by a factor of v in the x-, y-, and z-directions, respectively.
translate v
Perform a translation — adding v to each coordinate point of the blocks to be transformed.
building-blocks edge add-controls command

Syntax
building-blocks edge add-controls keyword <range>
Add control points to edges. Control points are added on all edges in the current building blocks set if <range> is not supplied.
Add exactly i control points per each edge (i must be a positive integer no greater than 20). Added control points will be evenly spaced.
use-size
Add a number of control points equal to the number of zones on each edge (see building-blocks edge size).
building-blocks edge delete command

Syntax
building-blocks edge delete <range>
Delete edges. This operation will also delete any blocks attached to the deleted edges. If <range> is not supplied, all edges (and blocks) will be deleted from the current
set.
building-blocks edge drape command

Syntax
building-blocks edge drape keyword <novalidate> <range>
Move the points of edges onto an external geometric set. The points to be moved are defined by the <range>. Movement of each point is done along the beam-line
defined by keyword until it intersects the external geometric set. The <novalidate> option skips validation of all blocks moved as part of the drape operation.
inwards v
Extend the beam-line from each point to the focus point v.
outwards v
Extend the beam-line from the focus point v to each point.
direction v
Set the beam-line as a constant direction vector v.
building-blocks edge factor command

Syntax
building-blocks edge factor f <range>
Apply a sizing factor to zones on edges. The factor is applied to edges in the current <range>, if supplied, or on all edges if not. The factor f must be between 0.001 and
1000.0 (the default is 1.0).
When zones are generated from the blocks, the factor (like a ratio, see building-blocks edge ratio) defines zone sizes of relative length along the edge block.
Factor specifies a ratio of last zone length to the first zone length along an edge.
When the factor for an edge is changed, the change is propagated to all face-connected opposite edges. If building-blocks edge ratio-isolate is set to true the
changes will not propagate from the edge; the default setting of that flag is false.
[CS: a picture here might be in order]
building-blocks edge group command

Syntax
building-blocks edge group s <slot s > <remove> <range>
Assign or remove a group name to edges. The command is applied to edges in the <range>, if supplied, or to all edges if not. If the <remove> option is used, the edges
in the range will be removed from the group s.
building-blocks edge id command

Syntax
building-blocks edge id i keyword
Primary keywords:
control-point | ratio | ratio-isolate | size | type
Modify the properties of an edge. In the current building block set the edge with ID i will be modified.
control-point keyword
Modify control points of the edge.
add v
Add a control point at the position defined by vector v. The position v must be on the edge within the tolerance (see building-blocks set tolerance).
delete i
Delete the control point defined by index i from the edge. Index i is a positive integer starting from 1.
move v index i
Move the control point defined by index i to new position defined by vector v .
rotate origin v_1 direction v_2 angle f indices i1 <i2 > <i3 > ...
Rotate control points of the edge defined by indices using an angle of rotation f (in degrees) around axis of rotation defined by the origin point v_1 and
direction vector v_2.
translate v indices i1 <i2 > <i3 > ...
Translate control points identified by indices by adding v to each position.
ratio f
Specify a ratio size parameter f for zones on the edge. The ratio parameter f is a float number that must be between 0.1 and 10.0. When zones are generated from
the blocks, the ratio defines zones relatively along the edge of the block. The size of each zone will be f of the previous zone length. The default value is 1.0
(uniform zones — same length).
Each time the ratio of an edge is changed, the changes are propagated to all face-connected opposite edges. If ratio-isolate is set to true the changes will not
propagate from the edge; the default setting for this flag is false (meaning the ratio setting propagates).
ratio-isolate b
Set a flag to isolate ratio or factor assignments on an edge. If true then ratio/factor assignments do not propagate to all face-connected opposite edges. This setting
is set to false by default.
size i
Specify the number of zones on an edge. The value of i must be positive (up to 1000). The default value is 3. When zones are generated from the building blocks
set, all blocks attached to this edge will be have i zones along the direction defined by the edge.
Each time size of an edge is changed, the changes are propagated to face-connected opposite edges.
type keyword
Specify the curve-type of the edge.
arc
Specify an arc edge. An arc may have one control point only.
spline
Specify a spline edge.
polyline
Specify a polyline edge (this is the default type).
building-blocks edge list command

Syntax
building-blocks edge list keyword <range>
Primary keywords:
extra | group | information | faces | nodes
Print information about edges. If <range> is not supplied, the requested information is listed for all edges in the current building blocks set.
extra i
FISH extra information printed. A valid index i must be supplied.
group
Group information is listed.
information
Comprehensive information is listed, including groups, extras, length of the edge, direction, zone size, zone ratio, type and number of control points.
faces
IDs for each face connected to the edge(s) are listed.
nodes
IDs for the nodes of the edge(s) are listed.
building-blocks edge ratio command

Syntax
building-blocks edge ratio f <range>
Apply a sizing ratio to zones on edges. The ratio is applied to edges in the current <range>, if supplied, or on all edges if not. The ratio f must be between 0.1 and 10.0
(the default is 1.0).
When zones are generated from the blocks, the ratio (like a factor, see building-blocks edge factor) defines zones relatively along the edge of the block. The size
of each zone will be f of the previous zone length. The default value is 1.0 (uniform zones — same length).
When the ratio for an edge is changed, the change is propagated to all face-connected opposite edges. If building-blocks edge ratio-isolate is set to true the
changes will not propagate from the edge; the default setting of that flag is false.
building-blocks edge ratio-isolate command

Syntax
building-blocks edge ratio-isolate b <range>
Determine whether zone ratios or factors propagate. Each time the zone size factor (building-blocks edge factor) or ratio (building-blocks edge ratio) of an
edge is changed, the changes are propagated to all face connected opposite edges. If building-blocks edge ratio-isolate is set to true, the changes will not
propagate from the edge. The default setting is false.
building-blocks edge size command

Syntax
building-blocks edge size i <range>
Specify the number of zones on an edge. The value of i must be positive (up to 1000). The default value is 3. When zones are generated from the building blocks set, all
blocks attached to an edge in <range> will have i zones along the direction defined by the edge. If <range> is not supplied all edges are affected.
Each time the size on an edge is changed, the changes are propagated to face-connected opposite edges.
building-blocks edge snapon id command

Syntax
building-blocks edge snapon id i set s keyword <control-point b > <range>
Primary keywords:
Snap an edge to a geometric set. Points are translated on edges that are in the specified <range>, if supplied. If not, all points are translated.
A translation vector is defined from the point with :lkwd`id` i in the current building blocks set to the target point on a geometric set s.
edge id i <f >
point id i
building-blocks edge transform command

Syntax
building-blocks edge transform <origin v_o > keyword <control-point b > <range>
Primary keywords:
Transform and edge (via its points). If <range> is not specified all edges are transformed.
The <control-point b> option indicates whether control-points on an edge should move if only one of the points of that edge is moved. The default is true. This option
reflect keyword
plane v_1 v_2 v_3
Perform rotation by angle f, in degrees, using rotation axes that goes through the coordinate origin in the direction v.
scale v
translate v
Perform a translation — adding v to each coordinate point of the blocks to be transformed.
building-blocks edge type command

Syntax
building-blocks edge type keyword <range>
Specify edge curve-type. Edge(s) in the current <range> are affected, if supplied; all edges are affected if not.
arc
Specify an arc edge. An arc can have one control point only.
spline
Specify a spline edge.
polyline
Specify a polyline edge (the is the default type).
building-blocks face cycle command
Syntax
building-blocks face cycle <range>
Rotate (cycle) the topology of triangular faces. Aspects of the face, such as the degeneracy point, edge zone sizes, and ratio, are affected when the topology is changed.
The operation is performed on faces in the <range>, if supplied, or on all faces if not. However, note only triangular faces are affected by the command. The cycle
operation will propagate through wedge or tetrahedral blocks across attached faces.
building-blocks face delete command

Syntax
building-blocks face delete <range>
Delete faces. This operation will also delete any blocks attached to the deleted faces. If <range> is not supplied, all faces (and blocks) will be deleted from the current
set.
building-blocks face drape command

Syntax
building-blocks face drape keyword <novalidate> <range>
Move the points of faces onto an external geometric set. The points to be moved are defined by the <range>. Movement of each point is done along the beam-line
defined by keyword until it intersects the external geometric set. The <novalidate> option skips validation of all blocks moved as part of the drape operation.
inwards v
outwards v
direction v
building-blocks face group command

Syntax
building-blocks face group s <slot s > <remove> <range>
Assign a group name to faces. The command is applied to faces in the current <range>, if supplied, or to all faces if not. If the <remove> option is used, the faces in the
range will be removed from the group s.
building-blocks face list command

Syntax
building-blocks face list keyword <range>
Primary keywords:
blocks | edges | extra | group | information | nodes
Print information about faces. If <range> is not supplied, the requested information is listed for all faces in the current building blocks set.
blocks
Print block IDs for each face.
edges
Print edge IDs for each face.
extra i
Print FISH extra information. A valid index i must be supplied.
group
Print group information.
information
Comprehensive information is listed, including groups, extras, area of the face, and normal vector.
nodes
Print IDs for the nodes of the face(s).
building-blocks face snapon id command

Syntax
building-blocks face snapon id i set s keyword <control-point b > <range>
Primary keywords:
Snap a face to a geometric set. Points are translated on faces that are in the specified <range>, if supplied. If not, all points are translated.
edge id i <f >
point id i
building-blocks face transform command

Syntax
building-blocks face transform <origin v_o > <control-point b > keyword <range>
Primary keywords:
Transform a face (via its points). If <range> is not specified all faces are transformed.
reflect keyword
plane v_1 v_2 v_3
Rotate by angle f, in degrees, using rotation axes that go through the coordinate origin in the direction v.
scale v
translate v
Perform a translation — adding v to each coordinate point of the face to be transformed.
building-blocks point delete command

Syntax
building-blocks point delete <range>
Delete points. This operation will also delete all blocks attached to the deleted points. If <range> is not supplied, all points (and blocks) will be deleted from the current
set.
building-blocks point drape command

Syntax
building-blocks point drape keyword <novalidate> <range>
Move points onto an external geometric set. The points to be moved are defined by the <range>. Movement of each point is done along the beam-line defined by
keyword until it intersects the external geometric set. The <novalidate> option skips validation of all blocks moved as part of the drape operation.
inwards v
outwards v
direction v
building-blocks point group command

Syntax
building-blocks point group s <slot s > <remove> <range>
Assign a group name to points. The command is applied to points in the current <range>, if supplied, or to all points if not. If the <remove> option is used, the points in
the range will be removed from the group s.
building-blocks point list command

Syntax
building-blocks point list keyword <range>
Print information about points. If <range> is not supplied, the requested information is listed for all points.
extra i
Print FISH extra information. A valid index i must be supplied.
group
information
Comprehensive information is listed, including groups and extras.
edges
Print IDs for the edges that are connected to the point(s).
building-blocks point merge command

Syntax
building-blocks point merge i1 i2
Merge two points. The two points are given by ID i1 and ID i2. Merging points will also induce merging of edges and faces, if applicable.
building-blocks point move-to command

Syntax
building-blocks point move-to keyword f <control-point b > <range>
Move points. Position components (x, y, or z) of points in the <range>, if supplied, are moved to the value f; all points are moved if no range is supplied.
The <control-point b> option indicates whether control-points on an edge should move if only one of the points of that edge is moved. The default is true.
Set the x-component of the point(s).
Set the y-component of the point(s).
Set the z-component of the point(s).
building-blocks point snapon id command

Syntax
building-blocks point snapon id i set s keyword <control-point b > <range>
Primary keywords:
Snap points to a geometric set. Points in the specified <range>, if supplied, are translated. If not, all points are translated.
edge id i <f >
point id i
building-blocks point transform command

Syntax
building-blocks point transform <origin v_o > keyword <control-point b > <range>
Primary keywords:
Transform points. If <range> is not specified all points are transformed.
reflect keyword
plane v_1 v_2 v_3
performs rotation by angle f, in degrees, using rotation axes that goes through the coordinate origin in the direction v.
scale v
translate v
Perform a translation — adding v to each coordinate point of the face to be transformed.
building-blocks set arrest-triangle command

Syntax
building-blocks set arrest-triangle b
Specify how to split a wedge block. The default for this flag is false.
When a split starts from a quadrilateral face of a wedge block (an edge-to-edge split) and the split line is aligned with opposite edge of the starting face, there are at least
two possibilities how it goes through the block. When arrest-triangle is true the wedge block is divided in two new wedge blocks and both of them share the opposite
edge. When false, the wedge block is divided into two blocks, a hexahedron and a wedge.
building-blocks set automatic-zone command

Syntax
building-blocks set automatic-zone keyword
Specify a automatic zoning method.
extent i
Specify zoning by setting i zones to be created across the largest extent of the set.
length f
Specify zoning by setting a fixed length of f for all zones generated from the set (f must be positive).
total i
Specify zoning by setting the total number of zones in the set to i.
building-blocks set auto-tolerance command

Syntax
building-blocks set auto-tolerance b
Set the auto-tolerance flag for geometric manipulations. When auto-tolerance flag is on, any geometric manipulation of building blocks/faces/edges/points will update
the tolerance with the value that is average length of all edges × . The tolerance update will happen before validation of all affected blocks.
building-blocks set break-angle command

Syntax
building-blocks set break-angle <f >
Set the break angle. The break angle f, specified in degrees, is the dihedral angle between faces. It is used to determine whether faces are adjacent when generating
proto-blocks (review Building Blocks-Based Grids for illustration). The default value is 135 degrees.
building-blocks set create command

Syntax
building-blocks set create s
Create a building block set. The set named s is created and becomes the current set.
building-blocks set delete command

Syntax
building-blocks set delete <s >
Delete a building block set. If a set name s is not supplied the current set is deleted.
building-blocks set export command

Syntax
building-blocks set export <s > <binary>
Export current building blocks to a file. If a file name s is not supplied, the name of the current set will be used. The extension of the file will be ".f3bset". The optional
switch binary specifies binary output. The default is text format.
building-blocks set geometry command

Syntax
building-blocks set geometry keyword
Associate a geometry set with the current set. Geometric sets may be added, removed, or cleared for use with the current building blocks set.
Geometric sets may be used with the "snapon" and "drape" commands available for face, edge, and point objects (and in some cases block objects; see building-
blocks block snapon or building-blocks face drape, for instance).
add s
Add a geometric set with name s to be associated with current building blocks set.
clear
Clear the list of geometric sets associated with the current building blocks set.
remove s
Remove the geometric set with name s from the list of geometric sets associated with the current building blocks set.
building-blocks set import command

Syntax
building-blocks set import keyword
Import a building blocks set.
extruder <to-set s > <v >
Import building blocks from the current set in the Extrusion Pane. If the to-set s option is used, the destination will be the building blocks set with the name s. If
not, the destination will be the current building blocks set. When <v> is supplied the coordinates of all the points of imported blocks will be shifted by that vector.
s1 <set s2> <:vec:v>
Import blocks from the file s1. The file must have one of the extensions ".f3bset", ".f3grid" or ".flac3d" (and be a valid file of that type). The destination building
blocks set is s2. If s2 is not supplied a new set is created and given a set name that derives from the file name s1. When <v> is supplied the coordinates of all the
points of imported blocks will be shifted by that vector.
Note
If a set with the same name as the imported set exists already, it will be deleted and replaced.
building-blocks set list command

Syntax
building-blocks set list <s >
Print information about a building blocks set. Information about the set named s is listed. If s is omitted, information on all building blocks sets will be printed.
building-blocks set select command

Syntax
building-blocks set select s
Specify the current building blocks set. The set with the name s becomes the current building blocks set. All commands that operate on blocks, faces, edges, and points
act on the current set only.
building-blocks set tolerance command

Syntax
building-blocks set tolerance f
Set the tolerance for geometric manipulations. For instance, if the distance between two points is less than f they will be treated as one point (merged). The tolerance
value f must be positive. Invoking the command will set off the auto-tolerance flag (see building-blocks set auto-tolerance).
If f is not supplied the default value (average length of all edges × ) is used.
building-blocks set validate-all command

Syntax
building-blocks set validate-all
Check the validity of blocks. Invalid blocks are marked.
FISH Functions
The type specifiers used in the FISH function signatures are given in the FISH Type Index section.
l Building Blocks Block Functions

l Building Blocks Face Functions
l Building Blocks Edge Functions
l Building Blocks Point Functions
l Building Blocks Set Functions
Building Blocks Block Functions
building_blocks.block.ablock(BB_BLOCK_PNT,BB_FACE_PNT)
Get an attached block.
building_blocks.block.center(BB_BLOCK_PNT)
Get the center point of a block.
building_blocks.block.check(BB_BLOCK_PNT)
Get the validity of a block.
building_blocks.block.edge(BB_BLOCK_PNT,INT)
Get a block edge.

building_blocks.block.face(BB_BLOCK_PNT,INT)
Get a block face.
building_blocks.block.multiplier(BB_BLOCK_PNT)
Get the block multiplier.
building_blocks.block.point(BB_BLOCK_PNT,INT)
Get a block point.
building_blocks.block.size(BB_BLOCK_PNT)
Get the number of block faces.
Building Blocks Face Functions
building_blocks.face.area(BB_FACE_PNT)
Get the area of a face.
building_blocks.face.center(BB_FACE_PNT)
Get the center point of a face.
building_blocks.face.check(BB_FACE_PNT)
Get the validity of the face.
building_blocks.face.edge(BB_FACE_PNT,INT)
Get an edge of a face.
building_blocks.face.flip(BB_FACE_PNT,INT)
Get edge "flipped" status.
building_blocks.face.gridsizei(BB_FACE_PNT,BB_BLOCK_PNT)
Get number of zones along the local "x" edge of...
building_blocks.face.gridsizej(BB_FACE_PNT,BB_BLOCK_PNT)
Get number of zones along the local "y" edge of...
building_blocks.face.next.face(BB_FACE_PNT,INT)
Get the next face in a list.
building_blocks.face.next.index(BB_FACE_PNT,INT)
Get the index of the next face in a list.
building_blocks.face.point(BB_FACE_PNT,INT)
Get a point of a face.
building_blocks.face.size(BB_FACE_PNT)
Get the number of face edges.
building_blocks.face.toglobal(BB_FACE_PNT,VEC)
Get the global coordinates of a point from local coordinates.
building_blocks.face.tolocal(BB_FACE_PNT,VEC)
Get the local coordinates of a point from global coordinates.
Building Blocks Edge Functions
building_blocks.edge.center(BB_EDGE_PNT)
Get the center point of an edge.
building_blocks.edge.cp.add(BB_EDGE_PNT,VEC)
Add a control point to an edge.
building_blocks.edge.cp.delete(BB_EDGE_PNT,INT)
Delete a control point on an edge.
building_blocks.edge.cp.localu(BB_EDGE_PNT,INT)
Get a local edge coordinate of a control point.
building_blocks.edge.cp.point(BB_EDGE_PNT,INT)
Get the 3D coordinates of a control point.
building_blocks.edge.cp.size(BB_EDGE_PNT)
Get the number of control points on an edge.
building_blocks.edge.curve(BB_EDGE_PNT)
Get edge curvature.
building_blocks.edge.direction(BB_EDGE_PNT)
Get edge direction.
building_blocks.edge.grid.ratio(BB_EDGE_PNT)
Get the ratio parameter of an edge.
building_blocks.edge.grid.ratio.isolate(BB_EDGE_PNT)
Get the state of the ratio-isolate flag.
building_blocks.edge.grid.size(BB_EDGE_PNT)
Get the number of zones along an edge.
building_blocks.edge.length(BB_EDGE_PNT)
Get the length of an edge.
building_blocks.edge.next.edge(BB_EDGE_PNT,INT)
Get the next edge in a list.
building_blocks.edge.next.index(BB_EDGE_PNT,INT)
Get the index of the next edge in a list.
building_blocks.edge.point(BB_EDGE_PNT,INT)
Get an edge point.
building_blocks.edge.start.face(BB_EDGE_PNT)
Get the first face in a list.
building_blocks.edge.start.index(BB_EDGE_PNT)
Get the index of the first face in a list.
building_blocks.edge.toglobal(BB_EDGE_PNT,FLT)
Get the global coordinates of a point from local coordinates.
building_blocks.edge.tolocal(BB_EDGE_PNT,VEC)
Get the local coordinate of a point from global coordinates.
building_blocks.edge.type(BB_EDGE_PNT)
Get edge type.
Building Blocks Point Functions
building_blocks.point.pos(BB_POINT_PNT)
Get point position.
building_blocks.point.start.edge(BB_POINT_PNT)
Get the first edge in a list.
building_blocks.point.start.index(BB_POINT_PNT)
Get the index of this point on the first edge...
Building Blocks Set Functions
building_blocks.set.block.create(BB_SET_PNT,STR,VEC,VEC,VEC,VEC<,VEC><,VEC><,VEC><,VEC>)
Create a block.
building_blocks.set.block.find(BB_SET_PNT,INT)
Get a block by ID.
building_blocks.set.block.list(BB_SET_PNT)
Get a block container from a set.
building_blocks.set.block.remove(BB_SET_PNT,BB_BLOCK_PNT)
Remove a block from a set.
building_blocks.set.block.size(BB_SET_PNT)
Get the number of blocks in a set.
building_blocks.set.create(STR<,INT>)
Create a building blocks set.
building_blocks.set.delete(BB_SET_PNT)
Delete a building blocks set.
building_blocks.set.edge.find(BB_SET_PNT,INT)
Get an edge by ID.
building_blocks.set.edge.list(BB_SET_PNT)
Get an edge container from a set.
building_blocks.set.edge.near(BB_SET_PNT,VEC<,FLT>)
Get the nearest edge from coordinates.
building_blocks.set.edge.size(BB_SET_PNT)
Get the number of edges.
building_blocks.set.face.find(BB_SET_PNT,INT)
Get face by ID.
building_blocks.set.face.list(BB_SET_PNT)
Get a face container from a set.
building_blocks.set.face.near(BB_SET_PNT,VEC<,FLT>)
Get the nearest face from coordinates.
building_blocks.set.face.size(BB_SET_PNT)
Get the number of faces in a set.
building_blocks.set.find(INT/STR)
Get a set by the name or by ID.
building_blocks.set.id(BB_SET_PNT)
Get the building blocks set ID.
building_blocks.set.list
Get a container of building blocks sets.
building_blocks.set.name(BB_SET_PNT)
Get the name of the building blocks set.
building_blocks.set.point.find(BB_SET_PNT,INT)
Get a point by ID.
building_blocks.set.point.list(BB_SET_PNT)
Get a point container from a set.
building_blocks.set.point.near(BB_SET_PNT,VEC<,FLT>)
Get the nearest point from coordinates.
building_blocks.set.point.size(BB_SET_PNT)
Get the number of points in a set.
l building_blocks.block.ablock
l building_blocks.block.center
l building_blocks.block.check
l building_blocks.block.edge
l building_blocks.block.face
l building_blocks.block.multiplier
l building_blocks.block.point
l building_blocks.block.size
l building_blocks.edge.center
l building_blocks.edge.cp.add
l building_blocks.edge.cp.delete
l building_blocks.edge.cp.localu
l building_blocks.edge.cp.point
l building_blocks.edge.cp.size
l building_blocks.edge.curve
l building_blocks.edge.direction
l building_blocks.edge.grid.ratio
l building_blocks.edge.grid.ratio.isolate
l building_blocks.edge.grid.size
l building_blocks.edge.length
l building_blocks.edge.next.edge
l building_blocks.edge.next.index
l building_blocks.edge.point
l building_blocks.edge.start.face
l building_blocks.edge.start.index
l building_blocks.edge.toglobal
l building_blocks.edge.tolocal
l building_blocks.edge.type
l building_blocks.face.area
l building_blocks.face.center
l building_blocks.face.check
l building_blocks.face.edge
l building_blocks.face.flip
l building_blocks.face.gridsizei
l building_blocks.face.gridsizej
l building_blocks.face.next.face
l building_blocks.face.next.index
l building_blocks.face.point
l building_blocks.face.size
l building_blocks.face.toglobal
l building_blocks.face.tolocal
l building_blocks.point.pos
l building_blocks.point.start.edge
l building_blocks.point.start.index
l building_blocks.set.block.create
l building_blocks.set.block.find
l building_blocks.set.block.list
l building_blocks.set.block.remove
l building_blocks.set.block.size
l building_blocks.set.create
l building_blocks.set.delete
l building_blocks.set.edge.find
l building_blocks.set.edge.list
l building_blocks.set.edge.near
l building_blocks.set.edge.size
l building_blocks.set.face.find
l building_blocks.set.face.list
l building_blocks.set.face.near
l building_blocks.set.face.size
l building_blocks.set.find
l building_blocks.set.id
l building_blocks.set.list
l building_blocks.set.name
l building_blocks.set.point.find
l building_blocks.set.point.list
l building_blocks.set.point.near
l building_blocks.set.point.size
building_blocks.block.ablock
Syntax
bp2 = building_blocks.block.ablock(bp1,fp)
Get an attached block. Returns a block attached to the face of the original block. If the face is external a null pointer(0) is returned. The face must belong to the original
block.
Returns: bp2 - attached block pointer

Arguments: bp1 - original block pointer
fp - face pointer
building_blocks.block.center
Syntax
v = building_blocks.block.center(bp)
Get the center point of a block. The center point returned is the arithmetic average of block point coordinates.
Returns: v - 3D vector
Arguments: bp - block pointer
building_blocks.block.check
Syntax
i = building_blocks.block.check(bp)
Get the validity of a block. Possible return values are: 0 = invalid block, 1 = valid block.
Returns: i - validity value

building_blocks.block.edge
Syntax
ep = building_blocks.block.edge(bp,i)
Get a block edge. Edge indices start with 1. The index must not be more than the number of edges for a block (6 = tetrahedron, 9 = wedge, 12 = hexahedron).
Returns: ep - edge pointer

i - edge index
building_blocks.block.face
Syntax
fp = building_blocks.block.face(bp,i)
Get a block face. Face indices start at 1. The index cannot be more than the total number of faces for a block (4 = tetrahedron, 5 = wedge, 6 = hexahedron).
Returns: fp - face pointer

i - face index
building_blocks.block.multiplier
Syntax
i = building_blocks.block.multiplier(b)
Get the block multiplier.
Returns: i - block multiplier

building_blocks.block.point
Syntax
pp = building_blocks.block.point(bp,i)
Get a block point. Point indices start at 1. The index must not be more than the number of points for a block (4 = tetrahedron, 6 = wedge, 8 = hexahedron).
Returns: pp - point pointer

i - point index
building_blocks.block.size
Syntax
i = building_blocks.block.size(bp)
Get the number of block faces. The return values are: 4 = tetrahedron, 5 = wedge, and 6 = hexahedron.
Returns: i - number of faces

building_blocks.edge.center
Syntax
v = building_blocks.edge.center(ep)
Get the center point of an edge.
Returns: v - center point of the edge (3D)

Arguments: ep - edge pointer
building_blocks.edge.cp.add
Syntax
= building_blocks.edge.cp.add(ep,v)
Add a control point to an edge. The point is added to the edge at the position v, which must be on the edge.
Returns:
v - position (3D)
building_blocks.edge.cp.delete
Syntax
= building_blocks.edge.cp.delete(ep,i)
Delete a control point on an edge. The control point index must be in the range 1 to building_blocks.edge.cp.size.
Returns:
i - control point index
building_blocks.edge.cp.localu
Syntax
f = building_blocks.edge.cp.localu(ep,i)
Get a local edge coordinate of a control point. The return value is 1D, a float number from 0.0 to 1.0. The control point index must be in the range 1 to
building_blocks.edge.cp.size.
Returns: f - local edge coordinate

building_blocks.edge.cp.point
Syntax
v = building_blocks.edge.cp.point(ep,i)
Get the 3D coordinates of a control point. The control point index must be in the range 1 to building_blocks.edge.cp.size.
Returns: v - position of the control point (3D)

building_blocks.edge.cp.size
Syntax
i = building_blocks.edge.cp.size(ep)
Get the number of control points on an edge.
Returns: i - number of control points on the edge

building_blocks.edge.curve
Syntax
i = building_blocks.edge.curve(ep)
Get edge curvature. Possible return values are: 0 = not curved (line edge), 1 = curved.
Returns: i - curvature value

building_blocks.edge.direction
Syntax
v = building_blocks.edge.direction(ep)
Get edge direction. The return value is a 3D vector from start point to the end point of the edge.
Returns: v - direction of the edge (3D vector)

building_blocks.edge.grid.ratio
Syntax
f = building_blocks.edge.grid.ratio(ep)
Get the ratio parameter of an edge. See the command building-blocks edge ratio.
Returns: f - ratio parameter

building_blocks.edge.grid.ratio.isolate
Syntax
i = building_blocks.edge.grid.ratio.isolate(ep)
Get the state of the ratio-isolate flag. See the command building-blocks edge ratio-isolate. Possible return values are: 0 = false (ratios propagate), 1 = true
(ratios do not propagate).
Returns: i - state value

building_blocks.edge.grid.size
Syntax
i = building_blocks.edge.grid.size(ep)
Get the number of zones along an edge.
Returns: i - number of zones

building_blocks.edge.length
Syntax
f = building_blocks.edge.length(ep)
Get the length of an edge. The length reported is from the start point to the end point of the edge.
Returns: f - edge length

building_blocks.edge.next.edge
Syntax
epnext = building_blocks.edge.next.edge(ep,i)
Get the next edge in a list. The list comprises edges connected to the point i on edge ep.
Returns: epnext - next edge pointer

Arguments: ep - source edge pointer
i - point index
This function and related functions (building_blocks.point.start.edge, building_blocks.point.start.edge, building_blocks.point.start.index,

building_blocks.edge.next.index) can be used together to loop through the edges connected to a point.
building_blocks.edge.next.index
Syntax
inext = building_blocks.edge.next.index(ep,i)
Get the index of the next edge in a list. The list comprises all edges connected to the point i on edge ep.
Returns: inext - next edge index

i - point index
This function and related functions (building_blocks.point.start.edge, building_blocks.point.start.edge, building_blocks.point.start.index,

building_blocks.edge.next.edge) can be used together to loop through the edges connected to a point.
building_blocks.edge.point
Syntax
pp = building_blocks.edge.point(ep,i)
Get an edge point. The point index must be 1 or 2.

i - point index
building_blocks.edge.start.face
Syntax
fp = building_blocks.edge.start.face(ep)
Get the first face in a list. The list comprises all the faces connected to the edge ep.
Returns: fp - first face pointer

This function and related functions (building_blocks.edge.start.index, building_blocks.face.next.face, building_blocks.face.next.index) can be used
together to loop through the faces connected to a point.
building_blocks.edge.start.index
Syntax
i = building_blocks.edge.start.index(ep)
Get the index of the first face in a list. The list comprises all the faces connected to the edge ep.
Returns: i - start face index

This function and related functions (building_blocks.edge.start.face, building_blocks.face.next.face, building_blocks.face.next.index) can be used
building_blocks.edge.toglobal
Syntax
v = building_blocks.edge.toglobal(ep,f)
Get the global coordinates of a point from local coordinates. Converts the local point coordinate on the edge (1D) to global coordinates (3D). The local edge coordinate
of the point will range between 0.0 and 1.0.
Returns: v - point global coordinates (3D)

f - local edge coordinate
building_blocks.edge.tolocal
Syntax
f = building_blocks.edge.tolocal(ep,v)
Get the local coordinate of a point from global coordinates. It assumed that the point is located on the edge. Return values of f will range between 0.0 and 1.0.
Returns: f - local edge point coordinate

v - point global coordinates (3D)
building_blocks.edge.type
Syntax
i = building_blocks.edge.type(ep)
Get edge type. Possible return values are: 0 = poly-line, 1 = arc, 2 = spline.
Returns: i - edge type value

building_blocks.face.area
Syntax
fa = building_blocks.face.area(fp)
Get the area of a face.
Returns: fa - area of the face

Arguments: fp - face pointer
building_blocks.face.center
Syntax
v = building_blocks.face.center(fp)
Get the center point of a face.
Returns: v - center point

building_blocks.face.check
Syntax
i = building_blocks.face.check(fp)
Get the validity of the face. Possible return values are: 0 = invalid face, 1 = valid face.
Returns: i - validity value

building_blocks.face.edge
Syntax
ep = building_blocks.face.edge(fp,i)
Get an edge of a face. Edge indices start with 1. The edge index must not be more than number of edges for a face (3 = triangle, 4 = quad).

i - face index
building_blocks.face.flip
Syntax
i = building_blocks.face.flip(fp,iface)
Get edge "flipped" status. An edge is flipped if the edge points order does not coincide with ascending order of points of the face. Face indices start at 1. The face index
must not be more than number of edges for a face (3 = triangle, 4 = quad). Possible return values are: 0 = not flipped, 1 = flipped.
Returns: i - integer
iface - face index
building_blocks.face.gridsizei
Syntax
i = building_blocks.face.gridsizei(fp,bp)
Get number of zones along the local "x" edge of a face. The return value takes into account an attached block zone multiplier. The block pointer must be attached to the
face.
Returns: i - grid size

bp - block pointer
building_blocks.face.gridsizej
Syntax
i = building_blocks.face.gridsizej(fp,bp)
Get number of zones along the local "y" edge of a face. The return value takes into account an attached block zone multiplier. The block pointer must be attached to the
face.
Returns: i - grid size

bp - block pointer
building_blocks.face.next.face
Syntax
fnext = building_blocks.face.next.face(fp,i)
Get the next face in a list. The list comprises all faces connected to the point i on face fp.
Returns: fnext - next face pointer

Arguments: fp - source face pointer
i - point index
This function and related functions (building_blocks.edge.start.face, building_blocks.edge.start.index, building_blocks.face.next.index) can be

used together to loop through the faces connected to a point.
building_blocks.face.next.index
Syntax
i1 = building_blocks.face.next.index(fp,i)
Get the index of the next face in a list. The list comprises all faces connected to the point i on face fp.
Returns: inext - next face index

Arguments: fp - original face pointer
i - point index
This function and related functions (building_blocks.edge.start.face, building_blocks.edge.start.index, building_blocks.face.next.face) can be used
building_blocks.face.point
Syntax
pp = building_blocks.face.point(fp,i)
Get a point of a face. Point indices start at 1. The point index must not be more than number of points for a face (3 = triangle, 4 = quad).

i - point index
building_blocks.face.size
Syntax
i = building_blocks.face.size(fp)
Get the number of face edges. Possible return values are: 3 = triangle, 4 = quad (it is the same as number of points).
Returns: i - number of edges

building_blocks.face.toglobal
Syntax
v = building_blocks.face.toglobal(fp,vu)
Get the global coordinates of a point from local coordinates. Converts local point coordinates on the face (2D vector) to global coordinates (3D vector).
Returns: v - point global coordinates (3D)

vu - point local face coordinates (2D)
building_blocks.face.tolocal
Syntax
vu = building_blocks.face.tolocal(fp,v)
Get the local coordinates of a point from global coordinates. It assumed that the point is located on the face.
Returns: vu - point local face coordinates (2D)

v - point global coordinates of the point (3D)
building_blocks.point.pos
Syntax
v = building_blocks.point.pos(pp)
Get point position. Returns global (3D) coordinates.
Returns: v - point position

Arguments: pp - point pointer
building_blocks.point.start.edge
Syntax
ep = building_blocks.point.start.edge(pp)
Get the first edge in a list. The list comprises edges connected to the point p.
Returns: ep - start edge pointer

Arguments: pp - point pointer
This function and related functions (building_blocks.point.start.index, building_blocks.edge.next.edge, building_blocks.edge.next.index) can be

used together to loop through the edges connected to a point.
building_blocks.point.start.index
Syntax
i = building_blocks.point.start.index(p)
Get the index of this point on the first edge in the list of edges connected to this point.
Returns: i - start edge index.

Arguments: pp - point) pointer.
This function and related functions (building_blocks.point.start.edge, building_blocks.edge.next.edge, building_blocks.edge.next.index) can be used
together to loop through the edges connected to a point.
building_blocks.set.block.create
Syntax
bp = building_blocks.set.block.create(sp,s,v1,v2,v3,v4<,v5><,v6><,v7><,v8>)
Create a block. Returns null (0) on failure. Strings that may be supplied for s are "hexahedron", "wedge" or "tetrahedron". Supply eight (hexahedron), six (wedge), or
four (tetrahedron) point coordinates (vn) as needed.
Returns: bp - block created

Arguments: sp - set pointer
s - type of block
v1 - 3D point coordinate that defines the block
building_blocks.set.block.find
Syntax
bp = building_blocks.set.block.find(sp,i)
Get a block by ID. Null pointer (0) is returned if unsuccessful.
Returns: bp - block pointer

i - block ID
building_blocks.set.block.list
Syntax
l = building_blocks.set.block.list(sp)
Get a block container from a set. The list of blocks from building blocks set sp is returned.
Returns: l - block container pointer

building_blocks.set.block.remove
Syntax
= building_blocks.set.block.remove(sp,bp)
Remove a block from a set.
Returns:
bp - block pointer
building_blocks.set.block.size
Syntax
i = building_blocks.set.block.size(sp)
Get the number of blocks in a set.
Returns: i - number of blocks

building_blocks.set.create
Syntax
sp = building_blocks.set.create(s<,i>)
Create a building blocks set. The set is given the name s and the ID i. Returns null (0) if unsuccessful.
Returns: bp - building blocks set pointer

Arguments: s - set name
i - id of the created block (optional)
building_blocks.set.delete
Syntax
spnext = building_blocks.set.delete(sp)
Delete a building blocks set. Returns a pointer to the next set in the container of building blocks sets or 0 if unsuccessful.
Returns: spnext - set pointer

building_blocks.set.edge.find
Syntax
ep = building_blocks.set.edge.find(sp,i)
Get an edge by ID. Returns a null pointer (0) if unsuccessful.

i - edge ID
building_blocks.set.edge.list
Syntax
l = building_blocks.set.edge.list(sp)
Get an edge container from a set. The list of edges from building blocks set sp is returned.
Returns: l - container of edges pointer

building_blocks.set.edge.near
Syntax
ep = building_blocks.set.edge.near(sp,v<,f>)
Get the nearest edge from coordinates.

v - point coordinates (3D)
f - search radius (optional)
building_blocks.set.edge.size
Syntax
i = building_blocks.set.edge.size(sp)
Get the number of edges. The number of edges from building blocks set sp is returned.

building_blocks.set.face.find
Syntax
fp = building_blocks.set.face.find(sp,i)
Get face by ID. Returns null pointer (0) if unsuccessful.

i - face ID
building_blocks.set.face.list
Syntax
l = building_blocks.set.face.list(sp)
Get a face container from a set. The list of faces from building blocks set sp is returned.
Returns: l - container of faces pointer

building_blocks.set.face.near
Syntax
fp = building_blocks.set.face.near(sp,v<,f>)
Get the nearest face from coordinates.

v - search coordinates (3D)
building_blocks.set.face.size
Syntax
i = building_blocks.set.face.size(sp)
Get the number of faces in a set.
Returns: i - number of faces

building_blocks.set.find
Syntax
sp = building_blocks.set.find(a)
Get a set by the name or by ID. Returns null (0) if unsuccessful.
Returns: sp - set pointer

Arguments: a - set ID or set name
building_blocks.set.id
Syntax
i = building_blocks.set.id(sp)
Get the building blocks set ID.
Returns: i - set ID
building_blocks.set.list
Syntax
lp = building_blocks.set.list()
Get a container of building blocks sets.
Returns: lp - pointer to a container of building blocks sets.

Arguments:
building_blocks.set.name
Syntax
s = building_blocks.set.name(sp)
Get the name of the building blocks set.
Returns: s - set name

building_blocks.set.point.find
Syntax
pp = building_blocks.set.point.find(sp,i)
Get a point by ID. Returns null pointer (0) if unsuccessful.

i - point ID
building_blocks.set.point.list
Syntax
l = building_blocks.set.point.list(sp)
Get a point container from a set. The list of points from building blocks set sp is returned.
Returns: l - container of points pointer

building_blocks.set.point.near
Syntax
pp = building_blocks.set.point.near(sp,v<,f>)
Get the nearest point from coordinates.

v - search coordinates (3D)
building_blocks.set.point.size
Syntax
i = building_blocks.set.point.size(sp)
Get the number of points in a set.
Returns: i - number of points

Data
User-defined label, scalar, vector, and tensor data can be input and used for comparison against model results. They can also be used to store data calculated from the model
for visualization.
Labels are an internal list of user-defined data that have a position, string, and optional end position associated with them.
Scalars are an internal list of user-defined data that have a position and a value associated with them.
Tensors are an internal list of user-defined data that have a position and a symmetric tensor associated with them.
Vectors are an internal list of user-defined data that have a position and a direction and magnitude associated with them.
Scalars, tensors and vectors may have groups and FISH extra values assigned to them.
In addition, each of these data types can be created from a file via the import keyword. File data may be in text or binary format, however, there is a specific file format for
each data type as defined below. Once user data is created, it is accessible for inquiry or transformation via FISH and can be visualized in a plot of the current model.
User-Defined Data File Formats
l Scalar text format

l Scalar binary format
l Tensor text format
l Tensor binary format

l Vector text format
l Vector binary format
l Commands
l FISH Functions
Commands
Create, modify, and delete data types for storage of user-defined data that do not have a direct effect on the model. Available data types are scalar, vector, tensor, and label.
These types can be used for visualization, tracking, and comparison with data generated by other sources.
Data Commands
data label create

Create a user-defined label at a point in space.
data label delete
Delete all labels within the specified range .
data label list
List label information.
data label modify
Modify an existing label.
data label results
Include label data in results files.
data scalar create
Create a scalar data entry.
data scalar delete
Delete scalars in the range.
data scalar export
Export scalars to the file with name s .
data scalar group
Specify scalar group names.
data scalar import
Import scalars from file s .
data scalar list
List scalar information on data in the range specified.
data scalar results
Include scalar data in results files.
data tensor create
Create a tensor data entry.
data tensor delete
Delete tensors in the range.
data tensor export
Export tensors to the file with name s .
data tensor group
Specify tensor group names.
data tensor import
Import tensors from file s .
data tensor list
List tensor information on data in the range specified.
data tensor results
Include tensor data in results files.
data vector create
Create a vector.
data vector delete
Delete vector data objets in the range.
data vector export
Export vectors to the file with name s .
data vector group
Specify vector group names.
data vector import
Import vectors from file s .
data vector list
List vector information.
data vector results
Include vector data in results files.
l data label create command

l data label delete command
l data label list command
l data label modify command
l data label results command
l data scalar create command
l data scalar delete command
l data scalar export command
l data scalar group command
l data scalar import command
l data scalar list command
l data scalar results command
l data tensor create command
l data tensor delete command
l data tensor export command
l data tensor group command

l data tensor import command
l data tensor list command
l data tensor results command
l data vector create command
l data vector delete command
l data vector export command
l data vector group command
l data vector import command
l data vector list command
l data vector results command
data label create command

Syntax
data label create keyword ...
Create a user-defined label at a point in space. These labels can be visualized with the plotting logic, identifying regions of interest.
By default, a label is an empty string at the origin with no arrow or line. The following keywords are available to assign values to the created label.
arrow b
Specifies whether the line connecting v1 to v2 ends with an arrowhead. This only applies if the end has been specified.
end v2
If the end is specified as different from v1, then the label will include a line going from v1 to v2.
name s
Assign a unique name to the label for later reference. If not specified then a name based on the internally assigned ID number is generated.
position v1
Specify the label origin position.
text s
Sets the label's text to be s. This text will be output to the screen at the location defined by v1.
data label delete command

Syntax
data label delete <name s > <range>
Delete all labels within the specified range. Optionally a single label can be deleted with the name keyword.
data label list command

Syntax
data label list <name s >
List label information. If the optional keyword name is specified, then only the information for that label is listed. Otherwise, information from all labels is listed.
data label modify command

Syntax
data label modify keyword
Modify an existing label. The keyword name must be used to identify the existing label to be modified.
arrow b
Specifies whether the line connecting v1 to v2 ends with an arrowhead. This only applies if the end has been specified.
end v2
If the end is specified as different from v1, then the label will include a line going from v1 to v2.
name s
Assign a unique name to the label for later reference. If not specified then a name based on the internally assigned ID number is generated.
position v1
Specify the label origin position.
text s
Sets the label's text to be s. This text will be output to the screen at the location defined by v1.
data label results command

Syntax
data label results active b
Include label data in results files. The default value is off.
data scalar create command

Syntax
data scalar create v <keyword> ...
Primary keywords:
extra | group | value
Create a scalar data entry. Scalars are an internal list of user-defined objects that have the position v and the value f (assigned via the value keyword) associated with
them. Scalars may also have groups and extra variables assigned to them upon creation.
Scalar fields can be visualized with the user interface. Scalars can be used to track events in the model, or to compare model results against external data.
extra i a
Optionally assign the extra variable a to index i.
group s <slot s2 >
Optionally assign the group name s to slot s2. By default, s2 = Default. Use of the group logic is described in the topic Group.
value f
Assign f to be the value associated with the scalar.
data scalar delete command

Syntax
data scalar delete <range>
Delete scalars in the range.
data scalar export command

Syntax
data scalar export s <binary> <range>
Export scalars to the file with name s. An extension of scalar will be added automatically if one is not specified. An ASCII text file is created unless the binary keyword
is specified. Any previous file is deleted. The relevant file formats are fully documented in Scalar Text File Format and Scalar Binary File Format.
data scalar group command
Syntax
data scalar group s <keyword> <range>
Specify scalar group names. Use of the group logic is described in the topic Group. If a slot assignment is not provided, the group s is assigned, by default, to the slot
named Default. The value of s may take two forms. The first is a simple string, in which case slot assignment may be made using the slot keyword. The second is the
exact form "slotname = groupname" — quotation marks required, spaces at equals sign ignored — where slotname is the slot assignment and groupname is the group
name.
remove
Remove s from all slots, or from a specific one if the slot keyword is also specified.
slot s
Assign the group name to slot s.
data scalar import command

Syntax
data scalar import s <keyword>
Import scalars from file s. The extension scalar is added automatically if one is not given.
The file format (text or binary) is determined by opening the file and looking for the appropriate header. If the proper header is not found, an error is indicated and no
data imported. If the group keyword is specified, imported scalars are assigned the specified group name. In the event of a conflict, this group assignment overrides any
in the import file. The relevant file formats are fully documented in Scalar Text File Format and Scalar Binary File Format.
group s <slot s >
Assign the group name s to the slot Default. The optional slot keyword can be used to specify the slot.
data scalar list command

Syntax
data scalar list <keyword> <range>
List scalar information on data in the range specified.
extra i
List scalar extra variables for the specified index.
group <slot s >
List scalar groups. All slots assigned will be listed, unless the slot keyword is used.
value
List the scalar values.
data scalar results command

Syntax
data scalar results active b
Include scalar data in results files. The default value is off.
data tensor create command

Syntax
data tensor create v <keyword>
Primary keywords:
extra | group | principal | value
Create a tensor data entry. Tensors are an internal list of user-defined objects that have the position v and a tensor value (assigned via the value or principal keywords)
associated with them. Tensors may also have groups and extra variables assigned to them upon creation.
Tensor fields can be visualized. Tensors can be used to track events in the model, or to compare model results against external data.
extra i a
group s <slot s2 >
Optionally assign the group name s to slot s2. By default, s2 = Default.
principal vprin vmax vint
Assign the tensor from the principal axes. Vector vprin is the principal stress magnitudes in maximum, intermediate, and minimum order. (See Stress Sign
Conventions.) Vector vmax is the direction of the maximum principal stress, and vector vint is the direction of the intermediate principal stress.
value f11 f22 f33 f12 f13 f23
Assign the values of the tensor directly in the order s11, s22, s33, s12, s13, s23.
data tensor delete command

Syntax
data tensor delete <range>
Delete tensors in the range.
data tensor export command

Syntax
data tensor export s <binary> <range>
Export tensors to the file with name s. The extension tensor will be added automatically if one is not specified. An ASCII text file is created unless the binary keyword
is specified. Any previous file is deleted. The relevant file formats are fully documented in Tensor Text File Format and Tensor Binary File Format.
data tensor group command

Syntax
data tensor group s <keyword> <range>
Primary keywords:
remove | slot
Specify tensor group names. Use of the group logic is described in the topic Group. If a slot assignment is not provided, the group s is assigned, by default, to the slot
name.
remove
slot s
data tensor import command

Syntax
data tensor import s <group s <slot s >>
Import tensors from file s. The extension tensor is added if one is not provided. The file format (text or binary) is determined by opening the file and looking for the
appropriate header. If the proper header is not found, an error is indicated and no data imported.
If the group keyword is specified, imported tensors are assigned the specified group name. This group assignment overrides any in the import file. The relevant file
formats are fully documented in Tensor Text File Format and Tensor Binary File Format.
data tensor list command

Syntax
data tensor list <keyword> <range>
Primary keywords:
extra | group | principal | value
List tensor information on data in the range specified.
extra i
List tensor extra variables for the specified index.
group <slot s >
List tensor groups.
principal
List the tensor principal components.
value
List the tensor values.
data tensor results command

Syntax
data tensor results active b
Include tensor data in results files. The default value is off.
data vector create command

Syntax
data vector create v <keyword>
Primary keywords:
dip | dip-direction | extra | group | magnitude | value
Create a vector. Vectors are an internal list of user-defined objects that have the position v and a vector value, assigned via either the value keyword or the dip, dip-
direction and magnitude keyword combination, associated with them. Vectors may also have groups and extra variables assigned to them upon creation.
Vector fields can be visualized with the user interface. Vectors can be used to track events in the model, or to compare model results against external data.
dip f
Specify the dip of the vector in degrees. Not to be used with the value keyword.
dip-direction f
Specify the dip direction of the vector in degrees. Not to be used with the value keyword.
extra i a
group s <slot s2 >
Optionally assign the group name s to slot s2. By default, s2 = Default. Use of the group logic is described in Group.
magnitude f
Specify the magnitude of the vector. Not to be used with the value keyword.
value v <magnitude f >
Assign v to be the value associated with the vector. One can optionally specify the magnitude separately with the magnitude keyword immediately following, in
which case v is used only to provide the direction.
data vector delete command

Syntax
data vector delete <range>
Delete vector data objets in the range.
data vector export command

Syntax
data vector export s <binary> <range>
Export vectors to the file with name s. An extension of vector will be added automatically if one is not specified. An ASCII text file is created unless the binary
keyword is specified. Any previous file is deleted. The relevant file formats are fully documented in Vector Text File Format and Vector Binary File Format.
data vector group command

Syntax
data vector group s <keyword> <range>
Primary keywords:
remove | slot
Specify vector group names. Use of the group logic is described in the topic Group. If a slot assignment is not provided, the group s is assigned, by default, to the slot
name.
remove
slot s
data vector import command

Syntax
data vector import s <group s <slot s >>
Import vectors from file s. An extension of vector will be added automatically if one is not specified. The file format (text or binary) is determined by
opening the file and looking for the appropriate header. If the proper header is not found, an error is indicated and no data imported.
If the group keyword is specified, imported vectors are assigned the specified group name. This group assignment overrides any in the import file. The
relevant file formats are fully documented in Vector Text File Format and Vector Binary File Format.
data vector list command

Syntax
data vector list <keyword> <range>
Primary keywords:
direction | extra | group | magnitude | value
List vector information.
direction
List the vector directions.
extra i
List vector extra variables for the specified index.
group <slot s >
List vector groups.
magnitude
List the vector magnitudes.
value
List the vector values.
data vector results command

Syntax
data vector results active b
Include vector data in results files. The default value is off.
FISH Functions
l Data Label Utilities

l Data Scalar Utilities
l Data Tensor Utilities
l Data Vector Utilities
Data Label Utilities
data.label.arrow(UDL_PNT)
Get/set arrow status.
data.label.create(VEC<,INT/STR>)
Create a label.
data.label.delete(UDL_PNT)
Delete a label.
data.label.end(UDL_PNT<,INT>)
Get/set the end position.
data.label.find(INT/STR)
Find a label.
data.label.head
Get the head of the global label list.
data.label.list
Get the global label list.
data.label.maxid
Get the maximum label ID.
data.label.name(UDL_PNT)
Get the label name.
data.label.next(UDL_PNT)
Get the next label.
data.label.num
Get the number of labels.
data.label.pos(UDL_PNT<,INT>)
Get/set the position.
data.label.text(UDL_PNT)
Get/set the label text.
data.label.typeid
Get the label type ID number.
Data Scalar Utilities
data.scalar.create(VEC)
Create a scalar.
data.scalar.delete(UDS_PNT)
Delete the scalar.
data.scalar.extra(UDS_PNT<,INT>)
Get/set a scalar extra variable.
data.scalar.find(INT)
Find a scalar.
data.scalar.group(UDS_PNT<,INT/STR>)
Get/set a scalar group.
data.scalar.group.remove(UDS_PNT,INT/STR)
Remove scalar groups.
data.scalar.head
Get the head of the global list of scalars.
data.scalar.id(UDS_PNT)
Get the scalar ID.
data.scalar.isgroup(UDS_PNT,INT/STR<,INT/STR>)
Query the existence of a group.
data.scalar.list
Get the global scalar list.
data.scalar.maxid
Get the maximum scalar ID.
data.scalar.near(VEC<,FLT>)
Find the closest scalar to a point.
data.scalar.next(UDS_PNT)
Get the next scalar.
data.scalar.num
Get the number of scalars.
data.scalar.pos(UDS_PNT<,INT>)
Get/set the scalar position.
data.scalar.typeid
Get the scalar type ID number.
data.scalar.value(UDS_PNT)
Get/set the scalar value.
Data Tensor Utilities
data.tensor.create(VEC)
Create a tensor.
data.tensor.delete(UDT_PNT)
Delete the tensor.
data.tensor.extra(UDT_PNT<,INT>)
Get/set a tensor extra variable.
data.tensor.find(INT)
Find a tensor.
data.tensor.group(UDT_PNT<,INT/STR>)
Get/set a tensor group.
data.tensor.group.remove(UDT_PNT,INT/STR)
Remove tensor groups.
data.tensor.head
Get the head of the global list of tensors.
data.tensor.id(UDT_PNT)
Get the tensor ID.
data.tensor.isgroup(UDT_PNT,INT/STR<,INT/STR>)
data.tensor.list
Get the global tensor list.
data.tensor.maxid
Get the maximum tensor ID.
data.tensor.near(VEC<,FLT>)
Find the closest tensor to a point.
data.tensor.next(UDT_PNT)
Get the next tensor.
data.tensor.num
Get the number of tensors.
data.tensor.pos(UDT_PNT<,INT>)
Get/set the tensor position.
data.tensor.typeid
Get the tensor type ID number.
data.tensor.value(UDT_PNT<,INT<,INT>>)
Get/set the tensor value.
Data Vector Utilities
data.vector.create(VEC)
Create a vector.
data.vector.ddir(UDV_PNT)(3D only)
Get/set the vector dip direction.
data.vector.delete(UDV_PNT)
Delete the vector.
data.vector.dip(UDV_PNT)
Get/set the vector dip.
data.vector.extra(UDV_PNT<,INT>)
Get/set a vector extra variable.
data.vector.find(INT)
Find a vector.
data.vector.group(UDV_PNT<,INT/STR>)
Get/set vector groups.

data.vector.group.remove(UDV_PNT,INT/STR)
Remove vector groups.
data.vector.head
Get the head of the global list of vectors.
data.vector.id(UDV_PNT)
Get the vector ID.
data.vector.isgroup(UDV_PNT,INT/STR<,INT/STR>)
data.vector.list
Get the global vector list.
data.vector.maxid
Get the maximum vector ID.
data.vector.near(VEC<,FLT>)
Find the closest vector to a point.
data.vector.next(UDV_PNT)
Get the next vector.
data.vector.num
Get the number of vectors.
data.vector.pos(UDV_PNT<,INT>)
Get/set the vector position.
data.vector.typeid
Get the vector type ID number.
data.vector.value(UDV_PNT<,INT>)
Get/set the vector value.
l data.label.arrow
l data.label.create
l data.label.delete
l data.label.end
l data.label.find
l data.label.head
l data.label.list
l data.label.maxid
l data.label.name
l data.label.next
l data.label.num
l data.label.pos
l data.label.text
l data.label.typeid
l data.scalar.create
l data.scalar.delete
l data.scalar.extra
l data.scalar.find
l data.scalar.group
l data.scalar.group.remove
l data.scalar.head
l data.scalar.id
l data.scalar.isgroup
l data.scalar.list
l data.scalar.maxid
l data.scalar.near
l data.scalar.next
l data.scalar.num
l data.scalar.pos
l data.scalar.typeid
l data.scalar.value
l data.tensor.create
l data.tensor.delete
l data.tensor.extra
l data.tensor.find
l data.tensor.group
l data.tensor.group.remove
l data.tensor.head
l data.tensor.id
l data.tensor.isgroup
l data.tensor.list
l data.tensor.maxid
l data.tensor.near
l data.tensor.next
l data.tensor.num
l data.tensor.pos
l data.tensor.typeid
l data.tensor.value
l data.vector.create
l data.vector.ddir
l data.vector.delete
l data.vector.dip
l data.vector.extra
l data.vector.find
l data.vector.group
l data.vector.group.remove
l data.vector.head
l data.vector.id
l data.vector.isgroup
l data.vector.list
l data.vector.maxid
l data.vector.near
l data.vector.next
l data.vector.num
l data.vector.pos
l data.vector.typeid
l data.vector.value
data.label.arrow
Syntax
b = data.label.arrow(lp)
data.label.arrow(lp) = b
Get/set arrow status. If b is true, then the line associated with the label (if it exists) is drawn as an arrow. Otherwise, it is drawn as a simple line.
Returns: b - label arrow status

Accepts: b - label arrow status
Arguments: lp - label pointer
data.label.create
Syntax
lp = data.label.create(v<,a>)
Create a label.
Returns: lp - label pointer

Arguments: v - label position
a - Optional integer or string name that, if not given, is assigned to the next available ID
data.label.delete
Syntax
v = data.label.delete(lp)
Delete a label.
Returns: v - void return

data.label.end
Syntax
Vector Access
v = data.label.end(lp<,i>)
data.label.end(lp<,i>) = v
Get/set the end position. If the optional end position is different from the value returned by data.label.pos, then an arrow is drawn with the label.
Returns: v - end position vector or component

Accepts: v - end position vector or component
i - optional vector component
Component Access
f = data.label.end.x(lp)
data.label.end.x(lp) = f
Get/set the x-component of the end position.
Returns: f - x-component of the end position vector

Accepts: f - x-component of the end position vector
f = data.label.end.y(lp)
data.label.end.y(lp) = f
Get/set the y-component of the end position.
Returns: f - y-component of the end position vector

Accepts: f - y-component of the end position vector
f = data.label.end.z(lp) (3D only)

data.label.end.z(lp) = f (3D only)
Get/set the z-component of the end position.
Returns: f - z-component of the end position vector

Accepts: f - z-component of the end position vector
data.label.find
Syntax
lp = data.label.find(a)
Find a label. If the label does not exist a new label is created.

Argument: a - integer or string name
data.label.head
Syntax
lp = data.label.head
Get the head of the global label list. Use the data.label.next construct to iterate through the list.
data.label.list
Syntax
lp = data.label.list
Get the global label list. Use the loop foreach construct to iterate through the list.
Returns: lp - label list
data.label.maxid
Syntax
id = data.label.maxid
Get the maximum label ID.
Returns: id - maximum label ID
data.label.name
Syntax
s = data.label.name(lp)
Get the label name.
Returns: s - label name

Accepts: lp - label pointer
data.label.next
Syntax
lpnext = data.label.next(lp)
Get the next label. Returns null if there are no more labels in the global list.
Returns: lpnext - next label pointer

data.label.num
Syntax
i = data.label.num
Get the number of labels.
Returns: i - number of labels
data.label.pos
Syntax
Vector Access
v = data.label.pos(lp<,i>)
data.label.pos(lp<,i>) = v
Get/set the position. The text and a line or arrow are drawn from this position to the end position (specified with data.label.end).
Returns: v - position vector or component

Accepts: v - position vector or component
Component Access
f = data.label.pos.x(lp)
data.label.pos.x(lp) = f
Get/set the x-component of the position.
Returns: f - x-component of the position vector

Accepts: f - x-component of the position vector
f = data.label.pos.y(lp)
data.label.pos.y(lp) = f
Get/set the y-component of the position.
Returns: f - y-component of the position vector

Accepts: f - y-component of the position vector
f = data.label.pos.z(lp) (3D only)

data.label.pos.z(lp) = f (3D only)
Get/set the z-component of the position.
Returns: f - z-component of the position vector

Accepts: f - z-component of the position vector
data.label.text
Syntax
s = data.label.text(lp)
data.label.text(lp) = s
Get/set the label text. This is optional (e.g., if set to "", no text will be drawn), and will be drawn at the label position.
Returns: s - label text

Accepts: s - label text
data.label.typeid
Syntax
i = data.label.typeid
Get the label type ID number. The type ID can be used to uniquely identify label FISH pointers and distinguish them from any other type of FISH pointer.
Returns: i - type ID value
data.scalar.create
Syntax
sp = data.scalar.create(v)
Create a scalar. The position of the scalar is v, and the scalar value is set to 0.0.
Returns: sp - scalar pointer

Arguments: v - scalar position
data.scalar.delete
Syntax
v = data.scalar.delete(sp)
Delete the scalar.

Arguments: sp - scalar pointer
data.scalar.extra
Syntax
a = data.scalar.extra(sp<,i>)
data.scalar.extra(sp<,i>) = a
Get/set a scalar extra variable.
Returns: a - extra value
Accepts: a - extra value

i - Optional extra index (if not provided, then i is taken to equal 1)
data.scalar.find
Syntax
sp = data.scalar.find(id)
Find a scalar.

Argument: id - scalar ID
data.scalar.group
Syntax
s = data.scalar.group(sp<,aslot>)
data.scalar.group(sp<,aslot>) = a
Get/set a scalar group.
Returns: s - string group name

Accepts: a - integer or string group name
aslot - Optional integer or string group slot (if not provided, then aslot is taken to equal 1)
data.scalar.group.remove
Syntax
b = data.scalar.group.remove(sp,a)
Remove scalar groups. The specified group name is removed from all group slots.
Returns: b - returns false unless at least one instance of t is removed

a - integer or string group name to remove
data.scalar.head
Syntax
sp = data.scalar.head
Get the head of the global list of scalars. Use data.scalar.next to iterate through the list.
data.scalar.id
Syntax
i = data.scalar.id(sp)
Get the scalar ID.
Returns: i - scalar ID
data.scalar.isgroup
Syntax
b = data.scalar.isgroup(sp,a<,aslot>)
Query the existence of a group. If aslot is not specified, then all slots are queried.
Returns: b - Boolean indicating group status

a - integer or string group name
aslot - optional integer or string slot
data.scalar.list
Syntax
l = data.scalar.list
Get the global scalar list. Use the loop foreach construct to iterate through the list.
Returns: l - scalar list
data.scalar.maxid
Syntax
id = data.scalar.maxid
Get the maximum scalar ID.
Returns: id - maximum scalar ID
data.scalar.near
Syntax
sp = data.scalar.near(v<,f>)
Find the closest scalar to a point. If f is specified, then the search radius is limited.

Arguments: v - position
f - optional search radius
data.scalar.next
Syntax
spnext = data.scalar.next(sp)
Get the next scalar. Returns null if there are no more scalars.
Returns: spnext - next scalar pointer

data.scalar.num
Syntax
i = data.scalar.num
Get the number of scalars.
Returns: i - number
data.scalar.pos
Syntax
Vector Access
v = data.scalar.pos(sp<,i>)
data.scalar.pos(sp<,i>) = v
Get/set the scalar position.
Returns: v - scalar position vector or component

Accepts: v - scalar position vector or component
Arguments: sp - user scalar pointer
Component Access
f = data.scalar.pos.x(sp)
data.scalar.pos.x(sp) = f
Get/set the x-component of the scalar position.
Returns: f - x-component of the scalar position vector

Accepts: f - x-component of the scalar position vector
f = data.scalar.pos.y(sp)
data.scalar.pos.y(sp) = f
Get/set the y-component of the scalar position.
Returns: f - y-component of the scalar position vector

Accepts: f - y-component of the scalar position vector
f = data.scalar.pos.z(sp) (3D only)

data.scalar.pos.z(sp) = f (3D only)
Get/set the z-component of the scalar position.
Returns: f - z-component of the scalar position vector

Accepts: f - z-component of the scalar position vector
data.scalar.typeid
Syntax
i = data.scalar.typeid
Get the scalar type ID number. The type ID can be used to uniquely identify scalar FISH pointers and distinguish them from any other type of FISH pointer.
data.scalar.value
Syntax
f = data.scalar.value(sp)
data.scalar.value(sp) = f
Get/set the scalar value.
Returns: f - scalar value

Returns: f - scalar value
data.tensor.create
Syntax
tp = data.tensor.create(v)
Create a tensor. The position of the tensor is v, and all components of the tensor value are set to 0.0.
Returns: tp - tensor pointer

Arguments: v - tensor position
data.tensor.delete
Syntax
v = data.tensor.delete(tp)
Delete the tensor.

Arguments: tp - tensor pointer
data.tensor.extra
Syntax
a = data.tensor.extra(tp<,i>)
data.tensor.extra(tp<,i>) = a
Get/set a tensor extra variable.

data.tensor.find
Syntax
tp = data.tensor.find(id)
Find a tensor.

Argument: id - tensor ID
data.tensor.group
Syntax
a = data.tensor.group(tp<,a1>)
data.tensor.group(tp<,a1>) = a
Get/set a tensor group.
Returns: a - group name

Accepts: a - integer or string group name
ia1 - Optional integer or string group slot (if not provided, then a1 is taken to equal 1)
data.tensor.group.remove
Syntax
i = data.tensor.group.remove(tp,a)
Remove tensor groups. The specified group name is removed from all group slots.
Returns: b - returns false unless at least one instance of t is removed

data.tensor.head
Syntax
tp = data.tensor.head
Get the head of the global list of tensors. Use data.tensor.next to iterate through the list.
data.tensor.id
Syntax
i = data.tensor.id(tp)
Get the tensor ID.
Returns: i - tensor ID
data.tensor.isgroup
Syntax
b = data.tensor.isgroup(tp,a<,a1>)
Query the existence of a group. If ts is not specified then all slots are queried.

a1 - optional integer or string slot
data.tensor.list
Syntax
l = data.tensor.list
Get the global tensor list. Use the loop foreach construct to iterate through the list.
Returns: l - tensor list
data.tensor.maxid
Syntax
id = data.tensor.maxid
Get the maximum tensor ID.
Returns: id - maximum tensor ID
data.tensor.near
Syntax
tp = data.tensor.near(v<,f>)
Find the closest tensor to a point. If f is specified, then the search radius is limited.

data.tensor.next
Syntax
tpnext = data.tensor.next(tp)
Get the next tensor. Returns null if there are no more scalars.
Returns: tpnext - next tensor pointer

data.tensor.num
Syntax
i = data.tensor.num
Get the number of tensors.
Returns: i - number
data.tensor.pos
Syntax
Vector Access
v = data.tensor.pos(tp<,i>)
data.tensor.pos(tp<,i>) = v
Get/set the tensor position.
Returns: v - tensor position vector or component

Accepts: v - tensor position vector or component
Arguments: tp - user tensor pointer
Component Access
f = data.tensor.pos.x(tp)
data.tensor.pos.x(tp) = f
Get/set the x-component of the tensor position.
Returns: f - x-component of the tensor position vector

Accepts: f - x-component of the tensor position vector
f = data.tensor.pos.y(tp)
data.tensor.pos.y(tp) = f
Get/set the y-component of the tensor position.
Returns: f - y-component of the tensor position vector

Accepts: f - y-component of the tensor position vector
f = data.tensor.pos.z(tp) (3D only)

data.tensor.pos.z(tp) = f (3D only)
Get/set the z-component of the tensor position.
Returns: f - z-component of the tensor position vector

Accepts: f - z-component of the tensor position vector
data.tensor.typeid
Syntax
i = data.tensor.typeid
Get the tensor type ID number. The type ID can be used to uniquely identify tensor FISH pointers and distinguish them from any other type of FISH pointer.
data.tensor.value
Syntax
Tensor Access
f = data.tensor.value(tp<,i1<,i2>>)
data.tensor.value(tp<,i1<,i2>>) = f
Get/set the tensor value.
Returns: f - tensor value

Accepts: f - tensor value
i1 - Optional tensor index that, if given without i2, ranges from 1 to 7, accessing the xx, yy, zz, xy, xz, and yz tensor values.
i2 - Optional tensor notation that must be given with i1. In this case, i1 corresponds to the first index of the tensor position and i2 to the second in the
row/column format. For instance, i1 = 1 and i2 = 3 returns the xz tensor value.
Value Access
f = data.tensor.value.xx(tp)
data.tensor.value.xx(tp) = f
Get/set the xx-value of the tensor value.
Returns: f - xx-value of the tensor

Accepts: f - xx-value of the tensor
f = data.tensor.value.xy(tp)
data.tensor.value.xy(tp) = f
Get/set the xy-value of the tensor value.
Returns: f - xy-value of the tensor

Accepts: f - xy-value of the tensor
f = data.tensor.value.xz(tp)
data.tensor.value.xz(tp) = f
Get/set the xz-value of the tensor value.
Returns: f - xz-value of the tensor

Accepts: f - xz-value of the tensor
f = data.tensor.value.yy(tp)
data.tensor.value.yy(tp) = f
Get/set the yy-value of the tensor value.
Returns: f - yy-value of the tensor

Accepts: f - yy-value of the tensor
f = data.tensor.value.yz(tp)
data.tensor.value.yz(tp) = f
Get/set the yz-value of the tensor value.
Returns: f - yz-value of the tensor

Accepts: f - yz-value of the tensor
f = data.tensor.value.zz(tp)
data.tensor.value.zz(tp) = f
Get/set the zz-value of the tensor value.
Returns: f - zz-value of the tensor

Accepts: f - zz-value of the tensor
data.vector.create
Syntax
vp = data.vector.create(v)
Create a vector. The position of the vector is v, and the vector value is set to {(0.0,0.0) in 2D; (0.0,0.0,0.0) in 3D}.
Returns: vp - vector pointer

Arguments: v - vector position
data.vector.ddir
Syntax
f = data.vector.ddir(vp) (3D only)

data.vector.ddir(vp) = f (3D only)
Get/set the vector dip direction. This can be modified without modifying the dip or the magnitude of the vector.
Returns: f - dip direction in radians

Accepts: f - dip direction in radians
Arguments: vp - vector pointer
data.vector.delete
Syntax
v = data.vector.delete(vp)
Delete the vector.

data.vector.dip
Syntax
f = data.vector.dip(vp)
data.vector.dip(vp) = f
Get/set the vector dip. This can be modified without modifying the dip direction or the magnitude of the vector.
Returns: f - dip in radians

Accepts: f - dip in radians
data.vector.extra
Syntax
a = data.vector.extra(vp<,i>)
data.vector.extra(vp<,i>) = a
Get/set a vector extra variable.

data.vector.find
Syntax
vp = data.vector.find(id)
Find a vector.

Argument: id - vector ID
data.vector.group
Syntax
a = data.vector.group(vp<,a1>)
data.vector.group(vp<,a1>) = a
Get/set vector groups.
Returns: a - group name or index

Accepts: a - group name or index
a1 - Optional integer or string group slot (if not provided, then a1 is taken to equal 1)
data.vector.group.remove
Syntax
b = data.vector.group.remove(vp,a)
Remove vector groups. The specified group name is removed from all group slots.
Returns: b - returns false unless at least one instance of a is removed

data.vector.head
Syntax
vp = data.vector.head
Get the head of the global list of vectors. Use data.vector.next to iterate through the list.
data.vector.id
Syntax
i = data.vector.id(vp)
Get the vector ID.
Returns: i - vector ID
data.vector.isgroup
Syntax
b = data.vector.isgroup(vp,a<,a1>)
Query the existence of a group. If ts is not specified then all slots are queried.

a1 - optional integer or string slot
data.vector.list
Syntax
l = data.vector.list
Get the global vector list. Use the loop foreach construct to iterate through the list.
Returns: l - vector list
data.vector.maxid
Syntax
id = data.vector.maxid
Get the maximum vector ID.
Returns: id - maximum vector ID
data.vector.near
Syntax
vp = data.vector.near(v<,f>)
Find the closest vector to a point. If f is specified, then the search radius is limited.

data.vector.next
Syntax
vpnext = data.vector.next(vp)
Get the next vector. Returns null if no more vectors exist in the global list.
Returns: vpnext - next vector pointer

data.vector.num
Syntax
i = data.vector.num
Get the number of vectors.
Returns: i - number
data.vector.pos
Syntax
Vector Access
v = data.vector.pos(vp<,i>)
data.vector.pos(vp<,i>) = v
Get/set the vector position.
Returns: v - vector position vector or component

Accepts: v - vector position vector or component
Component Access
f = data.vector.pos.x(vp)
data.vector.pos.x(vp) = f
Get/set the x-component of the vector position.
Returns: f - x-component of the vector position vector

Accepts: f - x-component of the vector position vector
f = data.vector.pos.y(vp)
data.vector.pos.y(vp) = f
Get/set the y-component of the vector position.
Returns: f - y-component of the vector position vector

Accepts: f - y-component of the vector position vector
f = data.vector.pos.z(vp) (3D only)

data.vector.pos.z(vp) = f (3D only)
Get/set the z-component of the vector position.
Returns: f - z-component of the vector position vector

Accepts: f - z-component of the vector position vector
data.vector.typeid
Syntax
i = data.vector.typeid
Get the vector type ID number. The type ID can be used to uniquely identify vector FISH pointers and distinguish them from any other type of FISH pointer.
data.vector.value
Syntax
Vector Access
v = data.vector.value(vp<,i>)
data.vector.value(vp<,i>) = v
Get/set the vector value.
Returns: v - vector value or component

Accepts: v - vector value or component
Component Access
f = data.vector.value.x(vp)
data.vector.value.x(vp) = f
Get/set the |x|-component of the vector value.
Returns: f - |x|-component of the vector value

Accepts: f - |x|-component of the vector value
f = data.vector.value.y(vp)
data.vector.value.y(vp) = f
Get/set the |y|-component of the vector value.
Returns: f - |y|-component of the vector value

Accepts: f - |y|-component of the vector value
f = data.vector.value.z(vp) (3D only)

data.vector.value.z(vp) = f (3D only)
Get/set the |z|-component of the vector value.
Returns: f - |z|-component of the vector value

Accepts: f - |z|-component of the vector value
Discrete Fracture Network (DFN)

With the DFN module, the fracture population embedded inside a rock mass is viewed as a set of discrete finite sized fractures. By default, the discrete fractures are {line
segments in 2D; planar disks in 3D}.
The DFN module provides an efficient tool to generate and manipulate fractures. The main features are:
l import/export of fractures from Itasca and Fracman files
l addition of deterministic fractures and generation of stochastic fractures

l intersections between fractures, intersections between fractures and outcrop/tunnel surfaces and borehole lines, scanline map calculation
l computation of clusters and connectivity properties
l fracture simplification methods
l definition of mechanical properties for fractures and assignment of these properties to model components
l visualization of fractures, outcrop/tunnel trace maps, stereonets
l FISH access providing the ability for custom creation, analyses and manipulations
Based on these features, the following applications are possible:
l creation of site-descriptive sets of fractures
l calibration of fracture models based on 2D/1D data
l derivation of DFN statistical properties
l structural analysis of fractures in relation to the resulting mechanical properties
l easy creation of numerical models of fractured rocks for mechanical analyses
l Overview
¡ Base Model Components
¡ Generating Stochastic Fracture Sets or DFNs
l Commands
¡ fracture aperture command
¡ fracture attribute command
¡ fracture cluster command
¡ fracture combine command
¡ fracture compute command
¡ fracture connectivity command
¡ fracture contact-model command
¡ fracture copy command
¡ fracture create command
¡ fracture delete command
¡ fracture dfn-extra command
¡ fracture dfn-group command
¡ fracture export command
¡ fracture extra command
¡ fracture generate command
¡ fracture group command
¡ fracture import command
¡ fracture initialize command
¡ fracture intersections automatic-update command
¡ fracture intersections compute command
¡ fracture intersections delete command
¡ fracture intersections scanline command
¡ fracture list command
¡ fracture property command
¡ fracture prune command
¡ fracture set-property command
¡ fracture template create command
¡ fracture template delete command
¡ fracture template modify-default command
¡ fracture verify-file command
l FISH Functions
¡ dfn.contactmap
¡ dfn.contactmap.all
¡ dfn.create
¡ dfn.delete
¡ dfn.dominance
¡ dfn.extra
¡ dfn.find
¡ fracture.aperture
¡ fracture.area
¡ fracture.centerdensity
¡ fracture.contactmap
¡ fracture.contactmap.all
¡ fracture.copy
¡ fracture.create
¡ fracture.ddir
¡ fracture.delete
¡ fracture.density
¡ fracture.dfn
¡ fracture.diameter
¡ fracture.dip
¡ fracture.extra
¡ fracture.find
¡ fracture.genpos
¡ fracture.gensize
¡ fracture.geomp10
¡ fracture.geomp20
¡ fracture.geomp21
¡ fracture.geomtrace
¡ fracture.gintersect
¡ fracture.group
¡ fracture.group.remove
¡ fracture.id
¡ fracture.inbox
¡ fracture.interarray
¡ fracture.intersect
¡ fracture.isdisk
¡ fracture.isgroup
¡ fracture.isprop
¡ fracture.len
¡ fracture.list
¡ fracture.maxid
¡ fracture.near
¡ fracture.normal
¡ fracture.num
¡ fracture.p10
¡ fracture.percolation
¡ fracture.pointnear
¡ fracture.pos
¡ fracture.prop
¡ fracture.typeid
¡ fracture.vertexarray
¡ dfn.fracturelist
¡ dfn.fracturenum
¡ dfn.group
¡ dfn.group.remove
¡ dfn.id
¡ fracture.intersect.end1
¡ fracture.intersect.end2
¡ fracture.intersect.find
¡ fracture.intersect.len
¡ fracture.intersect.list
¡ fracture.intersect.maxid
¡ fracture.intersect.npolylinept
¡ fracture.intersect.num
¡ fracture.intersect.polylinept
¡ fracture.intersect.pos1
¡ fracture.intersect.pos2
¡ fracture.intersect.set
¡ fracture.intersect.typeid
¡ dfn.isgroup
¡ dfn.list
¡ dfn.maxid
¡ dfn.name
¡ dfn.num
¡ dfn.prop
¡ fracture.intersect.set.delete
¡ fracture.intersect.set.find
¡ fracture.intersect.set.id
¡ fracture.intersect.set.interlist
¡ fracture.intersect.set.internum
¡ fracture.intersect.set.list
¡ fracture.intersect.set.maxid
¡ fracture.intersect.set.name
¡ fracture.intersect.set.num
¡ fracture.intersect.set.path
¡ fracture.intersect.set.typeid
¡ dfn.template
¡ fracture.template.ddirmax
¡ fracture.template.ddirmin
¡ fracture.template.dipmax
¡ fracture.template.dipmin
¡ fracture.template.find
¡ fracture.template.id
¡ fracture.template.list
¡ fracture.template.maxid
¡ fracture.template.name
¡ fracture.template.norientparam
¡ fracture.template.nposparam
¡ fracture.template.nsizeparam
¡ fracture.template.num
¡ fracture.template.orientparam
¡ fracture.template.orienttype
¡ fracture.template.posparam
¡ fracture.template.postype
¡ fracture.template.sizemax
¡ fracture.template.sizemin
¡ fracture.template.sizeparam
¡ fracture.template.sizetype
¡ fracture.template.typeid
¡ dfn.typeid
¡ fracture.vertex.find
¡ fracture.vertex.list
¡ fracture.vertex.maxid
¡ fracture.vertex.num
¡ fracture.vertex.pos
¡ fracture.vertex.typeid
Overview
Base Model Components

The base model components of the DFN logic are fractures and intersections. The following sections depict these objects in detail before a discussion of methods to create sets
of fractures, termed DFNs.
Fractures
A fracture is modeled as a discrete, planar and finite sized element. By default in 3D, fractures are disk-shaped but can also be planar, convex polygons. In that case, vertex
objects refer to the vertices of the planar, convex polygon. In 2D, fractures are modeled by line segments, and vertex objects refer to the line segment extremities.
Deterministic fractures, with known sizes and orientations, are created with the fracture create command or with the fracture.create FISH intrinsic. Fractures can exist
only within the model domain (see the model domain command for further information). The figure below shows a collection of disk shaped fractures created with the
fracture create command.
Figure 1: Deterministic fractures.
Intersections
An intersection object is the result of an intersection between a fracture and either a line, a planar polygon, a convex set of planar polygons or another fracture. Intersection
objects are modeled by {a point in 2D; a segment or a collection of adjacent segments in 3D}. The figure below shows the intersections, computed via the fracture
intersections compute command, between the deterministic fractures shown above. Fracture intersections are grouped into intersection sets for ease of processing. For
instance, one may determine the intersections between fractures and also the intersections between fractures and a model of a borehole; these may be stored in separate
intersection sets for later processing.
Figure 2: Intersections between deterministic fractures.
Generating Stochastic Fracture Sets or DFNs
A DFN is a set of fractures. In the figures above, there is a single DFN that is composed of four user specified fractures. Multiple DFNs, or sets of fractures, can exist
simultaneously, though any fracture can only belong to a single DFN. The figure below shows two DFNs composed of deterministic fractures, one composed of horizontal
fractures and one composed of vertical fractures. Splitting fractures into separate DFNs may be useful for computations involving different sets of fractures with different
characteristics (i.e., in this example, horizontal versus vertical fracture sets). Stochastic fractures are generated in separate DFNs, as described below.
Figure 3: Two DFNs, or fracture sets, composed of horizontal and vertical fractures.
Stochastic Descriptions of Fractures - the Fracture Template
It is often the case that, in a rock mass, one cannot directly determine the sizes, orientations and frequencies of the fractures pervading the rock mass. Instead, geological
mapping and/or geophysical techniques are used to estimate the characteristics of the fractures. After inspecting field data, one may determine bounds on the fracture sizes,
positions, and orientations. A fracture template holds these statistical parameters and is used to generate stochastic fractures with the fracture generate command.
Specifically, the fracture template contains a description of the size, position and orientation distributions of the fractures; it is created with the fracture template create
command. Thus a fracture template is a stochastic representation of a set of fractures and can be used to generate any number of specific realizations of fractures.
Stochastic Modeling Approach
The modeling approach used to generate fractures is stochastic: the geometrical characteristics of fractures, usually obtained from field data, are constrained through
independent statistical distributions (i.e., type of distribution and associated parameters) of their geometrical properties. This information is stored in a fracture template. The
geometrical characteristics currently supported by fracture templates are the fracture size (diameter), orientation and position distribution. From one fracture template, any
number of different realizations of fractures can be generated, depending on the random seed.
Fracture Size Density Distribution
The fracture size density distribution defines the number of fractures per unit of volume, , whose size is in the range . It combines a fracture size probability
distribution function and a density term. For a power law distribution, the relationship is
where is the scaling exponent (since the power law exponent is always negative, equal to - , the scaling exponent is positive) and is the density term of the model. The
distribution is between and . These are the the lower and upper bounds of the fracture sizes, respectively. Note that since the distribution is not necessarily bounded
toward its upper bound, can be infinite. precisely fixes, at any scale, the ratio between smaller and larger fracture sizes. Is it usually in the range . When plotted on a
log-log plot, appears as a straight line (see Figure 4) whose apparent slope is - .
Figure 4: Power-law distribution in a log-log diagram.
The power law model encompasses end member models, such as the model of constant size if , or models with infinite fractures when . When increases, the
proportion of small fractures increases relative to large fractures (Figure 5).
Figure 5: 2D outcrops from 3D DFNs generated within a cube of with , and (see Table 1) with, from left to right and from top to bottom,
, , and .
The term fixes the total fracture density by range of fracture size. The total fracture density (see below) is additionally dependent on the range of fracture sizes considered.
The total number of fractures with sizes in the range , in a volume of characteristic size , is then defined as (e.g., ).
If the domain is cubic, is simply the side of the cube. The number of fractures with sizes between and is given by
The cumulative fracture size density distribution that defines the number of fractures whose size is larger than a given value is defined by
One sees that if the scaling exponent is large enough (e.g., ), a corresponding fracture population is dominated by the smallest fractures. In other words, decreases
quickly with if . The power law model is not the only size distribution available in fracture templates. Gauss, uniform and bootstrapped (from file) distributions are also
available. The user can also define a custom distribution with FISH.
Densities
The most common definition for the fracture density is related to the total surface (mass) of fracture per unit volume. In 3D, the fracture mass density is the total fracture
surface area per unit volume ( or ). In 2D, it is the total fracture length per unit area ( ). In 1D, it is the fracture frequency ( or ): the number of fracture intercepts
by unit length of the scanline. The fracture density may also be defined as a fracture center density: the number of fracture centers per unit volume ( or ). These
definitions are shown in Table 1. In order to simplify modeling with the DFN module, the required density (i.e., input of the fracture generation) is defined from either the
mass density, center density or the fracture frequency, each of them relying on estimates from a sample. For any given initial density, the spatial distribution of fracture
positions arises from a Poisson process, leading to a uniformity of fracture positions throughout the volume.
Table 1: DFN density definitions.

Name Unit Meaning Link to fracture size distribution
mass density ( or ) Cumulated surface of fracture per
unit volume
mass density on outcrop ( Cumulated length of fracture per unit . is the fracture trace line observed on a 2D
) surface outcrop.
fracture frequency ( or Number (N) of fractures per unit . depends on the respective orientation of the 1D
) length scanline or borehole and the DFN orientation distribution. In the case of
uniform orientation (no preferential direction), .
center density ( or ) Number of fracture centers per unit
volume
fracture spacing Inverse of fracture frequency
average distance between fractures
along a 1D line
percolation parameter Cumulated excluded volume around
fractures per unit volume
Fracture density is a scale-averaging property, meaning that fracture density estimates and associated distributions depend on the location and scale of the observation region.
They can reflect local variability, when the observation scale tends to zero, or define bulk or macroscopic properties when the measurement scale tends to . The parameters
, , , , of the fracture size density distribution, fully define the fracture bulk density. However, field data of observed fracture densities are taken at finite size samples
such as borehole sections, scanlines, or outcrop maps, and thus are related to their sample support. They potentially differ locally from the bulk fracture density. In addition,
they are related to a limited range of fracture sizes, due to resolution effects at small sizes, and censoring and truncation at larger sizes.
Commands
Operate on discrete fracture networks (DFNs). A DFN is a collection of line segments (planar, convex polygons, and/or disks) in 2D (3D). Each element in a DFN is called a
fracture. Fractures hold lists of properties and can also hold extra variables and belong to groups. The properties may be of any type and can be assigned as needed. DFNs, as
sets of fractures, can be generated via DFN templates that are sets of statistical parameters describing the distribution of fractures. Intersections between fractures can be
calculated and queried for fracture connectivity analyses.
Note
l All DFN fractures must be created inside the model domain, as specified by the model domain command.
l Fracture properties and extra variables are converted to floating point numbers or integers when imported from a property file, although they are exported in their actual
format. Thus, one may save/restore general properties or extra variables of fractures in a model state (SAV) file, but may not import these values from a property file.
An Itasca DFN data file format is specified in "DFN-Related File Formats," along with a property file format to assign properties to the fractures.
DFN Commands
fracture aperture
Assign apertures to fractures.
fracture attribute
Modify fracture attributes.
fracture cluster
Compute fracture clusters.
fracture combine
Simplify fractures.
fracture compute
Compute fracture statistics.
fracture connectivity
Calculate fracture connectivity with a specified structure.
fracture contact-model
Assign contact models via fractures.
fracture copy
Copy fractures.
fracture create
Create a deterministic fracture.
fracture delete
Delete fractures.
fracture dfn-extra
Set DFN extra variables.
fracture dfn-group
Specify DFN group names.
fracture export
Export fractures to file.
fracture extra
Set fracture extra variables.
fracture generate
Generate fractures from a statistical description.
fracture group
Specify fracture group names.
fracture import
Import fractures.
fracture initialize
fracture intersections automatic-update
Set the intersection automatic-updating state.
fracture intersections compute
Compute intersections.
fracture intersections delete
Delete intersections.
fracture intersections scanline
Create intersections corresponding to scanline mapping.
fracture list
List the fracture attributes.
fracture property
Assign fracture surface properties.
fracture prune
Prune isolated fractures.
fracture set-property
Assign properties in objects that intersect fractures.
fracture template create
Create a fracture generation template.
fracture template delete
Delete fracture generation templates.
fracture template modify-default
Modify the default fracture generation template.
fracture verify-file
Verify a DFN file.
l fracture aperture command

l fracture attribute command
l fracture cluster command

l fracture combine command
l fracture compute command
l fracture connectivity command
l fracture contact-model command
l fracture copy command
l fracture create command
l fracture delete command
l fracture dfn-extra command
l fracture dfn-group command
l fracture export command
l fracture extra command
l fracture generate command
l fracture group command
l fracture import command
l fracture initialize command
l fracture intersections automatic-update command
l fracture intersections compute command
l fracture intersections delete command
l fracture intersections scanline command
l fracture list command
l fracture property command
l fracture prune command
l fracture set-property command
l fracture template create command
l fracture template delete command
l fracture template modify-default command
l fracture verify-file command
fracture aperture command

Syntax
fracture aperture keyword <range>
Primary keywords:
constant | dfn | fish | gauss | limits | log-normal | power-law | uniform
Assign apertures to fractures. Apertures can be used during contact model assignment (with the fracture contact-model command), for connectivity distance
calculations (with the fracture connectivity command) and with the DFN range element.
constant f
Constant aperture with f>0.
dfn s
Limit aperture assignment to the DFN with provided name.
fish s a1...an
Apertures are assigned via the user-defined FISH function s with arguments . This function is called for each fracture and must return a floating point value
corresponding to the fracture aperture.
gauss fm fs
Draw apertures randomly from a Gaussian distribution with mean fm and standard deviation fs.
limits fmin fmax
Apertures fall within the range [fmin, fmax], where fmax is greater than or equal to fmin. By default, fmin = 0 and fmax = +∞.
log-normal fm fs
Draw apertures randomly from a log-normal distribution with mean fm and standard deviation fs.
power-law f
Draw apertures randomly from a negative power-law distribution with exponent f.
uniform
Draw apertures randomly from a uniform distribution within the given limits as defined by the limit keyword.
Usage Example
The following example illustrates how the fracture aperture command can be used to assign apertures drawn from a number of distributions.
model new
model random 10000
model domain extent -5 5

;Generate fractures using the default template
fracture generate fracture-count 1000
;Set the apertures
fracture aperture log-normal 0.1 10
return
See Also: fracture attribute | fracture connectivity | fracture contact-model
fracture attribute command

Syntax
fracture attribute keyword <range>
Primary keywords:
aperture | area | dip-direction | diameter | dip | length | position | position-x | position-y | position-z
Modify fracture attributes. This command is a synonym for the fracture initialize command.
Note
l Modification of the fracture geometry will fail if the resulting fracture would not fall entirely within the model domain.
l Fracture attributes are characteristics of the fractures, such as position or size. These are distinct from fracture properties (assigned with the fracture property
command), which are surface properties of the fractures that are used to fill contact model properties with the fracture contact-model command.
aperture f
Fracture aperture where f ≥ 0.
area f (3D only)
Fracture area where f > 0.
dip-direction f (3D only)
Dip direction in degrees, as measured in a clockwise fashion from the positive y-axis, where f is in the range [0,360].
diameter f (3D only)
Diameter of disk fractures where f > 0.
dip f
Dip angle in degrees, where f is in the range {[0,180] in 2D; [0,90] in 3D}. In 2D, dip is the clockwise angle measured from the positive x-axis. In 3D, dip is the
angle from the dip direction projected on the xy-plane to the fracture surface measured in the negative z-direction.
length f (2D only)
Total fracture length where f > 0.
position v
Fracture position vector.
position-x f
Fracture position (x-component).
position-y f
Fracture position (y-component).
position-z f (3D only)
Fracture position (z-component).
Usage Example
The following example illustrates how the fracture attribute command can be used to rotate all fractures (3D). At the end, all fractures with center in the layer
have the same orientation.
model new
model random 10000
model domain extent -5 5 -5 5 -5 5
;Modify the default template
fracture template modify-default size-limits 0.5 5
fracture generate tolerance-box -4 4 -4 4 -4 4 fracture-count 1000
; Change some fracture attibutes
fracture attribute aperture 1 dip 25 dip-direction 270 range position-z -2 2
return
See Also: fracture initialize | fracture property
fracture cluster command

Syntax
fracture cluster keyword
Primary keywords:
group-slot | intersection-set
Compute fracture clusters. Clusters are defined as sets of fractures connected via intersections. These sets of fracture are indexed, and group names are assigned based
on the indices. Intersections are created via the fracture intersections compute command. If either no intersection set is specified or the specified intersection set
does not exist, a new intersection set is created and all intersections between fractures are delineated; the resulting intersection set is used as the basis for the cluster
calculation.
group-slot s
Assign group names in slot s. Use of the group logic is described in the Group topic. The group name is based on the intersection set name. The group name is set
to cnameXX, where cname is the intersection set name and XX is the cluster index. By default, s = Default.
intersection-set s
Specify the intersection set name used for cluster calculation. If no intersection set is specified a new intersection set is created with name name intersectionsXX,
where XX is the next available intersection set ID. All intersections are subsequently computed.
Usage Example
The following example in 3D illustrates how the fracture cluster command can be used to calculate the clusters of fractures and assign groups for visualization purposes.
In this example, fractures are generated at the percolation threshold (i.e., when one of the clusters connects all the system boundaries). Then, clusters are calculated and
assigned to groups with name allXX, with XX the cluster index. Note that fractures assigned the group all0 are isolated in that they do not intersect with any other fractures.
model new
model random 10000
fracture generate generation-box -8 8 -8 8 -8 8 connectivity-threshold box -5 5 -5 5 -5 5
;Compute intersections
fracture intersection compute intersection-set 'all'
;Calculate clusters based on the intersections
fracture cluster intersection-set 'all' group-slot 'cluster'
return
See Also: fracture connectivity | fracture intersections compute | fracture prune
fracture combine command

Syntax
fracture combine keyword <range>
Primary keywords:
angle | collapse | distance | merge
Simplify fractures. Fractures are sorted by decreasing size and, starting with the largest fracture (termed the reference fracture), the algorithm determines smaller
fractures in which the following 2 criteria are met:
l The difference between the reference fracture and fracture orientations is smaller than a given angle (provided by the angle keyword).
l The distance between fractures (as determined by the distance between the smallest fracture center and the largest fracture plane) is less than a specified distance
(provided by the distance keyword).
Note
l Using the merge keyword can significantly change the fracture density. Use this keyword with caution.
l All intersections are deleted when the fracture combine command is used.
When these criteria are met, smaller fractures are rotated to have the same orientation as the reference fracture. The algorithm continues by switching the reference
fracture to the next largest fracture that has not been previously rotated. If the merge keyword is given, the fractures that are coplanar are translated onto the reference
fracture plane if they would overlap. If a fracture falls completely within a larger fracture, it is removed; otherwise, the surface of the largest fracture is increased so that
it is equal to the sum of the surface of the two merged fractures.
angle f
Angle criterion for fracture proximity identification with f ≥ 0.
collapse
Collapse rotated fractures onto the reference fracture plane. Fractures are not merged.
distance f
Distance criterion for fracture proximity identification with f ≥ 0.
merge
Merge fractures that would overlap the reference fractures if they were collapsed onto the reference fracture plane. If a fracture falls completely within a larger
fracture, it is removed.
Usage Example
The following example illustrates how the fracture combine command can be used to reduce the number of fractures in a fracture set with close orientations (3D). After
having generated a DFN, it proceeds in two steps:
l first, fractures with the closest orientation (solid angle between them smaller than 20°) are merged;
l second, fractures with a more flexible orientation criterion (solid angle between them smaller than 50°) are projected on the same plane but not merged.
The initial DFN is thus "simplified," and there are no small angles between fractures, which can help for further mesh.
The example in 3D:
model new
model random 10000
;Create a template
fracture template create 'example' orientation fisher 50 150 10
;Generate fractures using the template
fracture generate template 'example' fracture-count 400
;Combine fractures based on angle and distance, merging
fracture combine angle 20 distance 0.5 merge
;Combine fractures based on angle and distance, collapse
fracture combine angle 50 distance 0.5 collapse
return
fracture compute command

Syntax
fracture compute keyword <range>
Primary keywords:
average-trace-length | center-density | mass-density | p10 | trace-center-density | trace-mass-density | percolation
Compute fracture statistics. Various density measures of fractures, filtered by range, can be computed.
average-trace-length s (3D only)
Return the average trace length, where traces are the intersections between the fractures and the planar geometry set with name s.
center-density
Return the fracture center density (i.e, P20 in 2D and P30 in 3D).
mass-density
Return the fracture mass density (i.e., P21 in 2D and P32 in 3D).
p10 keyword
Return the P10 along the line defined by begin and end, or along the geometry edges defined with the geometry keyword.
geometry s
P10 is measured along the edges of the geometry set with name s. Cannot be given with the begin or end keywords.
begin v
Define the starting point of the reference line where P10 is measured. Cannot be given with the geometry keyword.
end v
Define the ending point of the reference line where P10 is measured. Cannot be given with the geometry keyword.
trace-center-density s (3D only)
Return the trace center density (i.e., P20), where traces are the intersections between fractures and the planar geometry set with name s.
trace-mass-density s (3D only)
Return the trace mass density (i.e., P21), where traces are the intersections between the fractures and the planar geometry set with name s.
percolation
Return the percolation parameter.
Usage Example
The following example illustrates how the fracture compute command can be used to print fracture statistics (3D).
model new
model random 10000
;Create a line for p10 calculation
geometry set 'p10line'
geometry edge create by-position (-5,0,0) (5,0,0)
;List some information
fracture compute mass-density
fracture compute center-density
;List the p10 for both the line and by specifying the line ends
fracture compute p10 begin (-5,0,0) end (5,0,0)
fracture compute p10 geometry 'p10line'
See Also: fracture verify-file | fracture export | fracture import
fracture connectivity command

Syntax
fracture connectivity keyword <range>
Primary keywords:
aperture | cubic | distance | extra-index | starting-fracture | starting-geometry | intersection-set
Calculate fracture connectivity with a specified structure. The initial structure can either be a fracture or a geometry set. By default, integer connectivity levels are
computed for each fracture (i.e., a connectivity level of n means that the fracture is connected to the structure through n fracture intersections), and extras are assigned
based on the distance. This behavior can be modified with the aperture, cubic and distance keywords. If either no intersection set is specified or the specified
intersection set does not exist, a new intersection set is created and all intersections between fractures are delineated; the resulting intersection set is used as the basis for
the connectivity calculation.
aperture
Connectivity is assigned to the extra variable in a index specified with the extra-index keyword. Connectivity is the distance (as defined in the description of the
distance keyword) divided by the fracture aperture.
cubic
Connectivity is assigned to the extra variable in a index specified with the extra-index keyword. Connectivity is the distance (as defined in the description of the
distance keyword) divided by the cube of the fracture aperture (i.e., similar to the transmissivity).
distance
Connectivity is assigned to the extra variable in an index specified with the extra-index keyword. Connectivity is given as the physical distance from the structure
to the fracture, calculated as the path through the centers of intersections.
extra-index i
The connectivity is calculated, and this keyword specifies the extra index for assignment. The extra index 1 is used if this keyword is not specified.
starting-fracture i
The starting structure is set to the fracture with ID i. This keyword cannot be specified with the starting-geometry keyword.
starting-geometry s
The starting structure is set to the geometry set with name s. This keyword cannot be specified with the starting-fracture keyword.
intersection-set s
Specify the intersection set name used for connectivity calculation. If no intersection set is specified a new intersection set is created with name intersectionsXX,
where XX is the next available intersection set ID.
Usage Example
The following example illustrates how the fracture connectivity command can compute the connectivity level from a borehole, and the connectivity distance from a
fracture. It first calculates the connectivity level from the borehole previously defined, and saves the level in extra 1. Fractures with a connectivity level of 0 are directly
connected to the borehole, fractures with a level of 1 are connected to the level 0 fractures, etc. Fractures with a negative connectivity level (-1) are disconnected. Then, it
computes the distance of all fractures to the fracture with ID 1 and saves it in extra 2. This distance can be used later for analysis purposes or to simplify the DFN (e.g., by
removing fractures that are too far from a given structure).
model new
model random 10000
;Create a borehole geometry
geometry set 'borehole'
fracture generate percolation 5
;Calculate connectivity starting with the borehole
fracture connectivity starting-geometry 'borehole' extra-index 1
;Calculate connectivity starting with fracture 1
fracture connectivity starting-fracture 1 extra-index 2 distance
return
See Also: fracture cluster | fracture intersections compute
fracture contact-model command

Syntax
fracture contact-model keyword <rangeof dfns>
Primary keywords:
activate | deactivate | distance | install | model | use-aperture
Assign contact models via fractures. The command only applies to PFC. In order for the contact model specified with the model keyword to use the fracture geometry,
the contact model must have the property "dip" corresponding to the fracture dip (and "ddir" corresponding to the fracture dip direction, in 3D). The properties assigned
to the fractures with the fracture property command are supplied to the contact model. These properties are fixed, in the sense that they will not be inherited from
the contacting pieces or previous contacts, and must be specified by the user directly to change their values. Use the contact-model inheritance logic to specify those
contact-model properties not specified in the fractures.
It is possible for multiple fractures to intersect a contact. In order to uniquely identify the appropriate contact model, a dominance hierarchy is imposed on the DFNs and
fractures. If multiple fractures intersect a contact, the fractures from the DFN with the lowest dominance value are scrutinized. Of these fractures, the fracture with the
lowest dominance value is identified as the appropriate fracture for contact model/property assignment. The DFN dominance is specified with the fracture create,
fracture generate and fracture import commands.
The list of mechanical contact models is given in the PFC Help, in the Contact Models section. In the documentation for each contact model, a Properties table exists.
These include: the linear, linear contact bond, linear parallel bond, hertz, hysteretic, smooth joint, and the flat joint property tables.
activate
Activate contact model assignment when new contacts that intersect a fracture in the specified range are created.
deactivate
Deactivate contact model assignment when new contacts that intersect a fracture in the specified range are created. This applies to all previously activated
instances, regardless of the supplied range.
distance f
The distance from the closest point on a fracture to the contact line within which to identify contacts for contact model assignment is set to f. The default value is
0.0. The fracture apertures supersede f if the use-aperture keyword is specified.
install
Install the specified contact model at all existing contacts that intersect a fracture in the range. New contacts that intersect fractures will not be automatically
assigned the specified contact model unless the activate keyword is also specified.
model s
Name the contact model to be used (e.g., linear, smoothjoint, etc.).
use-aperture
Use the aperture of each fracture as the distance criteria to identify the contacts for contact model assignment. The apertures supersede the distance provided with
the distance keyword.
Usage Example
The following example illustrates how the fracture contact-model command can be used to install the smoothjoint contact model in all contacts intersecting fractures. We
first create a cubic assembly of balls and install a default contact model with the cmat command. Then, we generate fractures and assign the properties kn, ks and cohesion to
each fracture. The smoothjoint contact model is assigned to each contact intersecting a fracture.
model new
program warning off
model random 10001
cmat default model linearpbond property kn 1e5
ball generate cubic
ball attribute density 2500.0 damp 0.7
; create contacts and assign the linearpbond contact model
clean
dfn generate nfrac 1000
fracture aperture log-normal 0.1 10

dfn property sj_kn 1e5 sj_ks 1e-4 sj_coh 0
; install smoothjoint
fracture contact-model model smoothjoint install useaperture
return
See Also: fracture property
fracture copy command

Syntax
fracture copy keyword <range>
Primary keywords:
from-dfn | to-dfn
Copy fractures. Fractures falling in the specified range are copied from the DFN specified with the from-dfn keyword to the DFN specified with the to-dfn keyword. If
the later DFN does not exist it is created.
from-dfn s
Specify the DFN name from which to copy fractures. If no DFN is specified then fractures from all DFNs may be copied if they fall within the specified range.
to-dfn s
Specify the DFN name to which fractures will be copied. If no DFN is specified then a new DFN is created name copyOfDfnXX, where XX is the ID of the DFN
from which the fractures have been copied.
Usage Example
The following example in 3D illustrates how the fracture copy command can be used to split a DFN into two: one with the smallest fractures, and one with the largest
fractures.
model new
model random 10000
; range definition
fish define mylarge(dummy,frac)
mylarge=0
if fracture.area(frac)>4
mylarge = 1
endif
end
fracture generate dfn 'first' fracture-count 400
;Copy fractures into a new DFN
fracture copy from-dfn 'first' to-dfn 'second' range fish @mylarge
;Delete the large fractures from the first DFN
fracture delete dfn 'first' range fish @mylarge
return
See Also: fracture delete
fracture create command

Syntax
fracture create <keyword>
Primary keywords:
dfn | dfn-dominance | dip | dip-direction | dominance | group | intersection-set | position | size | skip-errors
Create a deterministic fracture.
Note
l A model domain must be specified prior to fracture addition.

l Fractures will be clipped at the model domain boundary if they extend beyond the model domain.
If the specified DFN specified by the dfn keyword does not exist a new DFN is created. If a DFN is not specified then a new DFN is created with the next available ID
and name dfnXX, where XX is the DFN ID. This command creates a {line segment fracture in 2D; disk fracture in 3D}. The command contrasts with the fracture
generate command, which generates fractures based on a stochastic description of a fracture.
dfn s
Add the fracture to the DFN with name s.
dfn-dominance i
If a new DFN is created, then its dominance is set to i, where i is greater than 1. The dominance is used during contact model assignment, when a contact
intersects multiple fractures from different DFNs. The fractures from the DFN with the lowest DFN dominance will be further scrutinized by their individual
dominance values to assign the appropriate contact model properties. If not specified, then the next available dominance is used. See the fracture contact-
model command for further details.
dip f
Dip angle of the fracture in degrees, where f is in the range {[0,180] in 2D; [0,90] in 3D}. In 2D, dip is the clockwise angle measured from the positive x-axis. In
3D, dip is the angle from the dip direction projected on the xy-plane to the fracture surface measured in the negative z-direction. By default, f = 0.
dip-direction f (3D only)
Dip direction of the fracture in degrees, as measured in a clockwise fashion from the positive y-axis where f is in the range [0,360]. By default, f is 0.0.
dominance i
Specify the fracture dominance where i is greater than 1. If not specified, then the next available fracture dominance value is used. Should a contact intersect
numerous fractures from a single DFN, then the fracture with the lowest dominance is used to assign the appropriate contact model and properties. See the
fracture contact-model command for further details.
group s <slot slot >
Assign the group name s to the fracture and optionally set the slot to slot.
intersection-set s
Fracture intersections with the newly created fracture are calculated and added to the intersection set with name s.
position v
Position of the fracture center. The fracture position must fall within the model domain unless the skip-errors keyword is specified. By default, the position is the
origin.
size f
Size of the fracture. By default, this is 1. The size is the {fracture length in 2D; disk diameter in 3D}.
skip-errors
Indicate that the command will return a warning instead of an error if the fracture creation fails. When this keyword is given, the fracture position is not required
to fall within the model domain.
Usage Example
The following example illustrates how the fracture create command can be used to create a single fracture in a new DFN (3D).
model new
;Create a deterministic fracture
fracture create ...
position (1.,1.,1.) ...
dip 45.0 ...
dip-direction 230.0 ...
size 1.0 ...
group '5' ...
dfn 'newDFN'
return
See Also: fracture attribute | fracture generate | fracture property
fracture delete command

Syntax
fracture delete <dfn <s > ><range>
Delete fractures. If the optional dfn keyword is given then deletion is restricted to the specified DFN. Empty DFNs are deleted. If the dfn keyword is given without
specifying a string name then the range is applied to DFNs, removing entire DFNs (i.e., all fractures in the DFNs are deleted).
Usage Example
The following example illustrates how the fracture delete command can be used to remove the largest fractures from a fracture.
model new
model random 10000
;Range definition
mylarge=0
mylarge = 1
endif
end
;Generate fractures with the default template
fracture generate dfn 'first' fracture-count 400

;Generate more fractures with the default template
fracture generate dfn 'second' fracture-count 200
;Delete all fractures in the second DFN using the by keyword in the range
fracture delete range name 'second' by dfn
;Delete large fractures
fracture delete range fish @mylarge
return
fracture dfn-extra command

Syntax
fracture dfn-extra i a<range>
Set DFN extra variables. The extra variable a can be of any type, and is associated with the index i as if stored in an array.
fracture dfn-group command

Syntax
fracture dfn-group s keyword <range>
Primary keywords:
remove | slot
Specify DFN group names. Use of the group logic is described in the Group topic. By default, s is assigned to the default slot Default. Use the remove keyword to
remove s from all slots.
remove
Remove s from all slots.
slot slot
Set group slot slot to s. By default, slot Default is used.
fracture export command

Syntax
fracture export keyword <range>
Primary keywords:
file | intersect-with-plane | property-file | template-file
Export fractures to file. By default, fractures are exported in the Itasca DFN data file format (see DFN-Related File Formats) and the '.dat' extension is added to the file
name if an extension is absent. FISHLab and FracMan formats are also supported. The associated fracture generation template (if unique) can be exported in a fracture
generation template file, and fracture properties can be exported in a property file (see DFN-Related File Formats). These files can be imported with the fracture
import command.
file s keyword
Fractures are exported to the file with name s. If no extension is provided, then the appropriate extension is added.
format keyword
Specify the format to be output. By default the Itasca format is used.
itasca
The itasca format is as specified in DFN-Related File Formats.
fishlab (3D ONLY)
The fishlab format is the flowplane format used in FISHLab with the '.flab' file extension.
fracman (3D ONLY)
The fracman format follows the FracMan ASCII output format with the '.fab' file extension.
intersect-with-plane <keyword> (3D only)
Specify that a 2D set of fracture traces be output corresponding with the intersection of a plane. Area intersections are not delineated. The resulting 2D DFN must
be opened in a 2D Itasca program (i.e., PFC2D). The Itasca DFN data file format is used (see DFN-Related File Formats).
Note
The output intersections are centered at the location specified with the origin keyword. The x-components of the intersections are in the direction of strike of the
plane, and the y-components of the intersections are in the down-dip direction of the plane.
dip f
Specify the dip of the intersection plane.
dip-direction f
Specify the dip direction of the intersection plane.
origin v
Specify the Origin of the intersection plane.
property-file s
Fracture property sets are exported to the file with name s. If no property file is exported, the corresponding property set numbers of all fractures in the exported
files containing fractures are set to 1. The property file format is specified in DFN-Related File Formats.
template-file s
The corresponding fracture generation template (if unique) is exported to the file with name s, and the '.idt' file extension is appended to the file name if no
extension is given. The template file format is specified in DFN-Related File Formats. Note that a template file will not be exported when the intersect keyword is
used.
Usage Example
The following example illustrates how the fracture export command can be used: first, to generate a DFN from a single template but with two different property sets;
second, to export the DFN geometry, properties and template. 3 Files are generated:
l example.dat with the fracture geometries;

l example_prop.dat with the fracture properties; and
l example_temp.idt with the template description used to generate the fracture.
model new
model random 10000
;Range definition
mylarge=0
mylarge = 1
endif
end
;Create a fracture template
fracture template create 'ex_temp' size power-law 3 size-limit 0.5 100
fracture generate dfn 'example' template 'ex_temp' fracture-count 500
;Assign properties
fracture property 'jcohesion' 50 'jkn' 50e9 'jks' 5e9 range fish @mylarge
fracture property 'jcohesion' 20 'jkn' 10e9 'jks' 1e9 range fish @mylarge not
;Export the fractures, properties and templates to files
fracture export file 'example.dat' property-file 'example_prop.dat' template-file 'example_temp'
return
The following example applies only in 3D, and illustrates how the fracture export command can be used to export a 2D cut of a 3D DFN for further analyses in a 2D code.
Here, example.dat will contain the traces of the 3D DFN on the plane centered on (1,0,0) with a dip of 90° and a dip direction of 50°.
model new

;Range definition
mylarge=0
mylarge = 1
endif
end
;Create a fracture generation template
fracture template create 'ex_temp' size power-law 3 size-limits 0.5 100
;Generate fractures with the template
fracture generate dfn 'example' template 'ex_temp' fracture-count 500
;Assign properties
fracture property 'jcohesion' 50 'jkn' 50e9 'jks' 5e9 range fish @mylarge
fracture property 'jcohesion' 20 'jkn' 10e9 'jks' 1e9 range fish @mylarge not
;Export intersections with the plane
fracture export file 'example' property-file 'example_prop' intersect-with-plane dip 90 dip-direction 50 origin (1,0,0)
return
See Also: fracture import | fracture property | fracture template create
fracture extra command
Syntax
fracture extra i a<range>
Set fracture extra variables. The extra variable a can be of any type, and is associated with the index i as if stored in an array.
Usage Example
The following example in 3D illustrates how the fracture extra command can be used to assign 2 to the extra in slot 1 for large fractures and 1 to the extra in slot 1 for
small fractures.
model new
model random 10000
;Range definition
mylarge=0
mylarge = 1
endif
end
fracture generate dfn 'example' fracture-count 500
;Assign extra parameters to fractures
fracture extra 1 'big' range fish @mylarge
fracture extra 1 'small' range fish @mylarge not
;Assign extra parameter to a DFN
fracture dfn-extra 1 'my-dfn'
return
fracture generate command

Syntax
fracture generate keyword
Primary keywords:
connectivity-threshold | dfn | dfn-dominance | fish-stop | fracture-count | generation-box | mass-density | p10 | percolation | template | tolerance-box
Generate fractures from a statistical description. A model domain must be specified prior to generation. {Line segment fractures in 2D; disk-shaped fractures in 3D} are
generated. If no fracture generation template (i.e., the statistical description defined with the fracture template create command) is specified, the default fracture
generation template is used. The default fracture template parameters can be changed with the fracture template modify-default command. The DFN may be
linked to the fracture generation template, provided that the modify keyword is not given and that the template is not the default. Fractures are generated until a
specified stopping criterion is met. These conditions include:
l a target fracture number (fracture-count);

l a target P10 (p10);
l a target density (P21 in 2D; P32 in 3D) (mass-density);
l a target percolation volume (percolation);
l DFN at the connectivity threshold (connectivity-threshold); and
l user-defined criteria (fish-stop).
Note
The specified DFN must either not exist or be empty. If a DFN is not specified then a DFN is created with the next available ID, and the DFN name is dfnXX, where
XX is the ID.
In addition, a user-defined FISH function can be called after each fracture is generated to modify the fracture, to skip it, or to add/calculate specific quantities (modify).
Fracture characteristics can then be modified with the fracture attribute command, and properties assigned with the fracture property command.
The fracture dominance, used for contact-model assignment (see the fracture contact-model command), is assigned in the order of fracture generation.
connectivity-threshold
Generation terminates at the connectivity threshold (i.e., the instant one can traverse all dimensions of a spatial region via fracture intersections).
box fxl fxu fyl fyu fzl fzu (z-components are 3D only)
Generation terminates the instant one can traverse fracture intersections from each edge of the specified box to each other edge.
geometry s1 <s2 >
Generation terminates when the DFN is connected to all {edges in 2D; polygons in 3D} of the geometry set s1. If s2 is given, generation terminates when
the DFN connects at least one {edge in 2D; polygon in 3D} of the geometry set s1 to at least one {edge in 2D; polygon in 3D} of the geometry set s2.
dfn s
Specify the DFN name. The DFN must either be empty or not exist.
dfn-dominance i
The dominance of the DFN is set to i. The DFN dominance is used during contact-model assignment when a contact intersects multiple fractures from different
DFNs. The fractures from the DFN with the lowest DFN dominance will be further scrutinized by their dominance values, to assign the appropriate contact model
properties.
fish-stop s a1...an
Generation is terminated if the FISH function s, with arguments , returns a nonzero integer.
fracture-count i
Generation terminates when the number of fractures generated is i.
generation-box fxmin fxmax fymin fymax fzmin fzmax (z-components are 3D only)
Generate fractures with positions (i.e., centers) within this rectangular generation region. By default, the generation-box is set to the model domain extent.
mass-density f
Generation terminates when the fracture density {P21 in 2D; P32 in 3D} in the tolerance-box reaches or exceeds f for the first time.
Note
Using a modification function prevents the linkage of the DFN to the underlying DFN template.
modify s a1...an
The FISH function s is called after each fracture is generated. The first argument of s is filled with the fracture pointer; this FISH function must take at least one
argument. Additional arguments can be specified as . The FISH function can be used to access and/or change the fracture parameters. If the function returns
the "remove" string, the fracture is deleted and removed from the generation process.
p10 f keyword
Generation terminates when P10 measured along either a specified scanline (using the begin and end) or a number of scanlines (using the geometry keyword) for
the first time.
begin v
Specify the location of the beginning of the scanline. Cannot be given with the geometry keyword.
end v
Specify the location of the ending of the scanline. Cannot be given with the geometry keyword.
geometry s
Specify that the scanlines come from the edges in a geometry set. Generation terminates when the average P10 measured along the set of scanlines defined
by the geometry set edges reaches or exceeds f for the first time. Cannot be used with the begin and end keyword.
percolation fval
Generation terminates when the fracture percolation volume in tolbox reaches or exceeds fval for the first time.
template s
Fractures are generated according to the specified template. If no fracture generation template is provided, then the default fracture generation template is used.
tolerance-box fxmin fxmax fymin fymax fzmin fzmax (z-components are 3D only)
The tolerance box is used to truncate fractures. This box may be larger or smaller than the generation box, but cannot exceed the model domain extent. It is used
for density or percolation calculations if one of these conditions represents the specified termination criteria. The generation box (generation-box) (or the model
domain, if the generation box exceeds it) is used if the tolerance box is not specified.
Usage Example
The following example illustrates how the fracture generate command can be used to generate a layered fracture network where fracture density is calibrated with
different data. All fractures obey the same statistical laws (i.e., sizes drawn in a power-law distribution with an exponent of 3 truncate between 0.5 and 100), uniform
orientations and uniform positions. Fracture positions are generated in a larger volume than the considered layer, to avoid finite-size effects.
In the first layer, the generation is stopped when the fracture density is equal to 1. In the second layer, it is stopped when the fracture frequency along the given line is equal to
0.5. Finally, in the third layer, it is stopped when the 2D density of fracture traces on the given outcrop is equal to 0.5.
model new
model random 10000
;Create a geometry set 'that' represents an ourcrop
geometry set 'outcrop'
geometry polygon create by-positions (-5,-5,3) (-5,5,3) (5,5,3) (5,-5,3)
;Define a stopping function

fish define stop
stop = 0
outcrop = geom.set.find('outcrop')
if fracture.geomp21(outcrop,dfn.find('example3'))>0.5
stop = 1
endif
end

fracture template create 'ex_temp' size power-law 3 size-limit 0.5 100
;Generate fracture using the template - stop at a specified mass density
fracture generate dfn 'example1' template 'ex_temp' generation-box -8 8 -8 8 -8 1 tolerance-box -5 5 -5 5 -5 -2 mass-density 1
;Generate fracture using the template - stop at a specified p10
fracture generate dfn 'example2' template 'ex_temp' generation-box -8 8 -8 8 -5 5 tolerance-box -5 5 -5 5 -2 2 p10 0.5 begin (-5,0,0) end (5
;Generate fracture using the template - stop based on the FISH criteria
fracture generate dfn 'example3' template 'ex_temp' generation-box -8 8 -8 8 -1 8 tolerance-box -5 5 -5 5 2 5 fish-stop @stop
return
The following example illustrates how the fracture generate command can be used to generate a DFN at the connectivity threshold without fractures intersecting a given
borehole (3D). During the generation, fractures intersecting the borehole are removed by the use of the modify keyword and the remove_fracture FISH function. This kind of
generation can be used after having deterministically added fractures intersecting the borehole.
model new
model random 10000
model domain extent -5.01 5.01
;Create a geometry set 'that' represents an ourcrop
geometry set 'borehole'
geometry edge create by-position (0,0,-4) (0,0,4)
;Define a stopping function
fish define remove_fracture(frac)
remove_fracture = '0'
borehole = geom.set.find('borehole')
if fracture.gintersect(frac,borehole)>0
remove_fracture = 'remove'
endif
end

fracture template create 'ex_temp' size power-law 3 size-limits 0.5 100
;Generate fractures using the template - generate to the connectivity threshold
fracture generate dfn 'example' template 'ex_temp' generation-box -8 8 -8 8 -8 8 connectivity-threshold box -5 5 -5 5 -5 5 modify remove_fracture
return
See Also: fracture create | fracture attribute | fracture property | fracture template create
fracture group command

Syntax
fracture group s keyword <range>
Primary keywords:
remove | slot
Specify fracture group names. Use of the group logic is described in Group. By default, s is assigned to the default slot Default. Use the remove keyword to remove s
from all slots.
remove
Remove s from all slots.
slot slot
Assign group s to the slot named slot. By default, slot Default is used.
Usage Example
The following example in 3D illustrates how the fracture group command can be used to split fractures into two groups: large and small.
model new
model random 10000
;Define the range
mylarge=0
mylarge = 1
endif
end
;Assign groups to fractures
fracture group 'large' slot 'size' range fish @mylarge
fracture group 'small' slot 'size' range fish @mylarge not
;Assign a group 'to' the DFN
fracture dfn-group 'my_dfn'
return
fracture import command

Syntax
fracture import keyword
Primary keywords:
center | clean | dfn | dfn-dominance | dominance | from-file | from-geometry | make-disk | make-planar | offset | property-file | skip-errors | template-file | truncate
Import fractures.
Note
l A model domain must be specified prior to importation, and all fractures must fall completely within the model domain unless the skip-errors or truncate
keywords are given.
l The main characteristics of the DFN (e.g., center, spatial extent, etc.) can be investigated prior to loading with the fracture compute command.
Fractures can either be imported from a file (see the file keyword ) or a geometry set (see the geometry keyword). Fractures cannot be imported into existing DFNs. If a
DFN is not specified then one is created with the next available ID and automatically named based either on the file name specified or the geometry set name. In
addition to the fractures geometries, the DFN can be associated with a fracture generation template via a fracture generation template file (see template, fracture
template create and fracture export for further details). Fracture properties can also be assigned via a property file (see property-file and fracture export for
further details).
center
The DFN will be "centered," wherein the average location of the fracture centers is aligned with the origin. This location is taken for all fractures prior to
modification (e.g., truncation or omission).
clean
Specify that the geometry set, from which fractures have been imported, is to be deleted after successful importation. This keyword only applies when the from-
geometry keyword has been specified.
dfn s
Specify the DFN name to be created. If a name is not specified then the DFN name is derived from the import file name or geometry set name specified.
dfn-dominance i
The DFN dominance is set to i where i ≥ 1. The dominance is used during contact model assignment when a contact intersects multiple fractures from different
DFNs. The fractures from the DFN with the lowest DFN dominance will be further scrutinized by their individual dominance values to assign the appropriate
contact model properties. If not specified, then the next available dominance is used. See the fracture contact-model command for further details.
dominance keyword
Specify the mode to set the fracture dominance. Should a contact intersect numerous fractures from a single DFN, then the fracture with the lowest dominance is
used to assign the appropriate contact model properties. The default behavior is ordered. See the fracture contact-model command for further details.
ordered
The fracture dominance in assigned based on the order of importation, where the dominance values increase as importation continues.
random
Specify that the fracture dominance is set in a random fashion, independent of the order of fracture importation.
from-file s1 <format keyword>
Import fractures from file s1. The format can optionally be specified with the format keyword. If no format is specified, then the file extension of the name
specified with the file keyword is used to determine the file format. A '.dat' file extension is assumed to be in the itasca format, a '.flab' file extension is assumed
to be in the fishlab format, and a '.fab' file extension is assumed to be in the fracman format.
itasca
The itasca format is as specified in DFN-Related File Formats, and is the default format.
fishlab (3D ONLY)
The fishlab format is the flowplane format used in FISHLab.
fracman (3D ONLY)
The fracman format follows the FracMan ASCII output format.
from-geometry s
Import fractures from the geometry set s. In 2D, the geometry edges are queried and turned into fractures. In 3D, this command attempts to import fractures as
both planar polygons and disks. Planar polygon importation scans the geometry polygons. Disk importation occurs by scanning all geometry points and
investigating the extra variables. If there are 3 extra variables that are doubles in extra slots 1, 2 and 3, then the point is deemed to represent a disk where the extra
variables are the radius, dip (in degrees) and dip direction (in degrees), respectively.
make-disk i (3D only)
Fractures with i vertices or more are made into disks with radii equal to the average distance from the centroid to the vertices and dip/dip direction, as specified.
make-planar (3D only)
Planarity is forced for all fractures that are not disks. The fracture normal is as defined in the data file, and the fracture position is set to the average position of the
vertices. The vertices are adjusted so that they fall on the plane.
offset v
Offset all fracture locations by v.
property-file s
Indicate that the properties of fractures are set via a property file. See DFN-Related File Formats for a definition of the property file format. This cannot be used
with the geometry keyword.
skip-errors
Indicate that the importation will continue in spite of fractures lying outside the model domain. The offending fractures will not be imported.
template-file s
Indicate that the provided DFN has been generated according to the fracture generation template defined in the file s. The template file format is specified in
DFN-Related File Formats. This cannot be used with the geometry keyword.
truncate
Indicate that fractures intersecting the model domain boundary are truncated (i.e., disk fractures in 3D can be converted to polygonal fractures).
Usage Example
The following example illustrates how the fracture import command can be used to import a DFN linked with a template and two property sets (files generated with the
example in the fracture export command). The DFN here is truncated in a smaller domain than the domain of generation.
model new
;Import fractures from a file
fracture import from-file 'example.dat' format itasca property-file 'example_prop.dat' template-file 'example_temp' dfn 'dfn_import' truncate
return
The following example illustrates how the fracture import command can be used to create a DFN of disks by using geometries (3D). First, geometrical nodes are created
and extras are associated to them (extra 1 is size, extra 2 is dip and extra 3 is dip direction). These nodes are transformed into disk-shaped fractures with the fracture
import command. The truncate keyword is used to truncate the new fractures at the system limits.
model new

;Create geometry with extra variables corresponding to disks
;First us radius, then dip, then dip direction
geometry set 'disks'
geometry node create (-4,-4,-4) extra 1 1.0 extra 2 90.0 extra 3 270.0
geometry node create (1,1,1) extra 1 2.5 extra 2 75.0 extra 3 210.0
;Import these fractures from the geometry set
fracture import from-geometry 'disks' dominance ordered dfn 'from_geometry' truncate
return
The following example illustrates how the fracture import command can be used to create a DFN of polygons by using geometries, and automatically calculate
intersections. The polygons are directly created with the geometry logic, and transformed into fractures with the fracture import command. The clean keyword is used to
delete the geometry once fractures are created.
model new

;Create geometry as polygons
geometry set 'polygons'
geometry polygon create by-positions (-4,-4,-4) (-4,4,-4) (4,4,-4) (4,-4,-4)
geometry polygon create by-positions (-4,4,-4) (-4,4,4) (4,4,4) (4,4,-4)
;Import polygons as fractures
fracture import from-geometry 'polygons' clean dominance ordered dfn 'from_geometry' truncate
return
See Also: fracture attribute | fracture export | fracture property
fracture initialize command

Syntax
fracture initialize keyword <range>
Synonym for the fracture attribute command.
Usage Example
The following example illustrates how the fracture attribute command can be used to rotate all fractures (3D). At the end, all fractures with center in the layer zin [-2;2]
have the same orientation.
model new
model random 10000
;Modify the default template
fracture template modify-default size-limits 0.5 5
fracture generate tolerance-box -4 4 -4 4 -4 4 fracture-count 1000
; Change some fracture attibutes
fracture attribute aperture 1 dip 25 dip-direction 270 range position-z -2 2
return
See Also: fracture attribute
fracture intersections automatic-update command

Syntax
fracture intersections automatic-update b
Set the intersection automatic-updating state. By default, when new fractures are added or removed, the previously calculated intersections and clusters are not updated
automatically. By enabling this behavior, these data structures remain valid and up-to-date. This keyword cannot be given with any other keywords.
fracture intersections compute command

Syntax
fracture intersections compute keyword <range>
Primary keywords:
clean | group-slot | intersection-set | skip-errors | with-geometry
Compute intersections. Intersections can exist between fractures, and between fractures and geometry sets. The supported geometry types are {edges in 2D;
polygons/edges in 3D}. Neither concave, planar polygons nor nonplanar polygons are supported in 3D. The geometry keyword can be provided to produce intersections
between fractures and geometry sets. Intersections are stored in an intersection set specified with the intersection-set keyword. The specified intersection set must not
already exist. Intersections can be visualized and queried in FISH. In addition, intersections are used to delineate fracture clusters (see the fracture cluster
command) and fracture connectivity (see the fracture connectivity command).
Intersections with geometry objects can result in polyline intersections in 3D. For instance, a fracture may intersect a cylindrical geometry representing a borehole at
many locations. Those individual fracture/polygon intersections that meet at geometry edges are merged into polyline intersections.
clean
Specify that the geometry set is to be deleted after the intersection operation has succeeded.
group-slot s
The optional keyword indicates that the intersection set name is placed in group slot s of all fractures found to be in the intersection.
intersection-set s
Specify the intersection set. If delineating intersections and no intersection set is specified then the intersection name is set to intersectionsXX, where XX is the
next available intersection set ID.
skip-errors (3D only)
Indicate that the determination of intersections will continue in spite of geometry objects being nonplanar, concave or not simple polygons. The offending
fractures are skipped.
with-geometry s <range>
Delineate the intersections between fractures and the geometry set with name s. An optional range of {edges in 2D; polygons in 3D} can be specified following
the geometry keyword to filter the geometry object. The dfn.intersect.end2 FISH intrinsic returns a pointer to the geometry set in this case.
Usage Example
The following example illustrates how the fracture intersections compute command can be used to compute intersections between fractures.
model new
model random 10000
model domain extent -5 5 -5 5

fracture intersections compute intersection-set 'all'
return
The following example illustrates how the fracture intersections compute command can be used to compute intersections between fractures and a tunnel modeled with
three polygons (3D).
model new
model random 10000
;Create the geometry of a simple tunnel
geometry set 'tunnel'
geometry polygon create by-positions (-4,-4,-4) (-4,-4,1) (-4,4,1) (-4,4,-4)
geometry polygon create by-positions (4,-4,-4) (4,-4,1) (4,4,1) (4,4,-4)
;Compute intersections with the tunnel
fracture intersection compute with-geometry 'tunnel' intersection-set 'frac_tunnel'
return
fracture cluster | fracture connectivity
fracture intersections delete command

Syntax
fracture intersections delete <keyword> <range>
Primary keywords:
intersection-set
Delete intersections. An intersection set can be specified with intersection-set keyword. If no intersection set is specified then all intersections are deleted. Empty
intersection sets are also deleted.
intersection-set s
Specify the intersection set to delete.
fracture intersections scanline command

Syntax
fracture intersections scanline keyword <range> (3D only)
Primary keywords:
intersection-set | lines | surface
Create intersections corresponding to scanline mapping. Scanline mapping occurs on a planar surface that is specified with the surface keyword. The measurement
surface must be a planar, convex polygon. All fracture intersections with this surface that also intersect one of a set of the specified scanlines (see the scanlines
keyword) are added to the specified intersection set.
intersection-set s
Set the name of the resulting intersection set containing the scanline traces. The specified intersection set must not already exist.
lines s
The edges in the geometry set s are taken as the set of scanlines. All fracture intersections with this surface that also intersect a scanline are kept in the specified
intersection set.
surface s
The geometry set s is taken to define the measurement plane.
Usage Example
The following example illustrates how the fracture intersections scanline command can be used to compute the scanline on the plane named "plane" along the line
named "line" and save the mapped traces in an intersection set.
model new
model random 10000
;Define the scanline plane
geometry set 'plane'

geometry set 'line'
;Calculate scanline traces (e.g., fracture intersections with the plane)
fracture intersections scanline intersection-set 'scan' lines 'line' surface 'plane'
return
fracture list command

Syntax
fracture list keyword <range>
Primary keywords:
attribute | extra | group | intersection | position | property
List the fracture attributes. By default, the DFNs are listed along with their associated templates (if any) and fracture count.
Note
Use the model precision command to change the precision of listed floating point values.
attribute <s >
List fracture attributes. If no s is given, then the available attributes are listed. If s is specified, then the value of that attribute is listed for each fracture.
extra i
List the fracture extra variables at index i.
group s
List the fracture group names at slot s.
intersection
List fracture intersections.
position
List the positions (center) of all fractures.
property <s >
List fracture properties. If no s is given, then the available properties are listed for each fracture. If s is specified, then the value of that property is listed for each
fracture.
Fracture properties can be used with the fracture contact-model command to set contact model properties.
fracture property command

Syntax
fracture property s a<s1 a1...> <range>
Assign fracture surface properties. The value a is assigned to the surface property with name s. The properties may be used with the fracture contact-model
command to set contact model properties.
Note
Fracture properties are surface properties of the fractures that are used to fill contact model properties with the fracture contact-model command. These are distinct
from fracture attributes (modified with the fracture attribute command), which are characteristics of fractures such as position or size.
The list of mechanical contact models is given in the PFC Help, in the Contact Models section. In the documentation for each contact model, a Properties table exists.
These include: the linear, linear contact bond, linear parallel bond, hertz, hysteretic, smooth joint, and the flat joint property tables.
Usage Example
The following example illustrates how the fracture property command can be used to assign different properties to fractures with a dip smaller and larger than 45°. If the
property names are consistent with properties of a contact model, it can be installed afterwards directly with the given properties.
model new
model random 10000
;Range definition
fish define angle(dummy,frac)
angle=0
if fracture.dip(frac)>45
angle = 1
endif
end
fracture generate dfn 'example' fracture-count 500
;Assign properties
fracture property 'jcohesion' 0.5 'sj_kn' 100e9 'sj_ks' 10e9 range fish @angle
fracture property 'jcohesion' 0.5 'sj_kn' 10e9 'sj_ks' 1e9 range fish @angle not
return
See Also fracture attribute | fracture contact-model
fracture prune command

Syntax
fracture prune keyword
Primary keywords:
critical-number | intersection-set
Prune isolated fractures. The intersection set that forms the basis for this operation is specified with the intersection-set keyword. Clusters of fractures with size less than
or equal to the number of fractures specified with the critical-number keyword are deleted. The intersection set must exist. If clusters have not been computed, they are
computed before pruning isolated fractures.
critical-number i
Critical number of fractures in a cluster to mark it for removal (i = 1, by default).
intersection-set s
Specify the intersection set name as the basis of the pruning operation.
Usage Example
The following example illustrates how the fracture prune command can be used to remove from a DFN all fractures that are in clusters with no more than two fractures. If
the size is set to 1, only isolated fractures (i.e., fractures connected to no other fracture) are removed.
model new
model random 10000
fracture intersection compute intersection-set 'all'
;Compute clusters
fracture cluster intersection-set 'all' group-slot 'cluster'
;Prune (i.e., delete) fractures that are nearly isolated
fracture prune intersection-set 'all' critical-number 2
return
See Also: fracture cluster | fracture connectivity | fracture intersections compute
fracture set-property command

Syntax
fracture set-property keyword ...
Primary keywords:
dfn | fracture | zone
Assign properties in objects that intersect fractures.
Note
Property names must match exactly; no keyword-type matching is used.
For each object, the fracture that intersects it with the lowest dominance is selected. Any property contained in that fracture is matched against the properties accepted
by the object. See the fracture property command for how to assign properties to fractures. In addition, if the properties joint-normal-x, joint-normal-y, joint-
normal-z are discovered, then those properties are assigned based on the fracture orientation. The properties joint-dip and joint-dip-direction are checked if the previous
ones are not found.
dfn <range>
Scan all fracture networks in the range. By default, all fracture networks are scanned.
fracture <range>
Use the range as a filter on all fractures within each fracture network. By default, all fractures in each fracture network are checked.
zone <range>
Assign properties to the mechanical constitutive models of all zones in the range. This is the only type of object available at this time, sot the zone keyword must
be given.
fracture template create command

Syntax
fracture template create s keyword
Primary keywords:
dip-direction-limits | dip-limits | orientation | position | size | size-limits
Create a fracture generation template. The name of the template is s. A fracture generation template is a set of statistical parameters used to generate fractures with the
fracture generate command. These parameters are the size distribution, the position distribution and the orientation distribution. Once fractures have been generated,
an association may exist between the fracture generation template and the generated fractures. Fracture generation templates can also be output to a file to be imported
and reused (see the fracture export and fracture import commands).
By default, a fracture generation template has the following properties: uniform fracture positions, uniform orientations (dip between 0 and 180 degrees in 2D; dip
between 0 and 90 degrees, dip direction between 0 and 360 degrees in 3D) and sizes obeying a negative power-law distribution with exponent 4 and with minimum
(maximum) size 1.0 (∞), respectively.
A default fracture generation template is always present and its state is saved and restored with the model state. This default fracture generation template is used as the
basis to generation fractures (i.e., with the fracture generate command) when no template is specified. See the fracture template modify-default command for
details on how to modify the default fracture generation template.
dip-direction-limits fmin fmax (3D only)
Specify that the fracture dip directions must fall in the range [fmin, fmax] degrees. By default, fmin = 0 and fmax = 360.
dip-limits fmin fmax
Specify that the fracture dips must fall in the range [fmin, fmax] degrees. By default, {fmin = 0 and fmax = 180, in 2D; fmin = 0 and fmax =90, in 3D}.
orientation s a1...an
Define the generation rule for fracture orientations with the parameters . The following options for s are supported:
l bootstrapped: The dip {and dip direction, in 3D} are bootstrapped from a file. One parameter must be given: the file name holding the discrete distribution
of values. This file obeys the bootstrapped distribution file format given in DFN-Related File Formats.
l dips (3D only): The dip and dip direction are bootstrapped from a DIPS file. One parameter must be given: the file name holding the discrete distribution of
values. This file obeys the DIPS file format given in DFN-Related File Formats.
l fish: The fish keyword is used to get values from a user-defined FISH function. The function name is given using , and the function arguments (any
number) are given after the function name. The function must return a {float, in 2D; 2 dimensional vector, in 3D}.
l fisher (3D only): The dip and dip direction are drawn from a Fisher distribution. Three additional parameters are required: dip, dip direction and .
l gauss: The dip {and dip direction, in 3D} are drawn from Gaussian distributions. In 2D, two additional parameters are required, specifying the mean and
standard deviation of the dip distribution. In 3D, four additional parameters are required: mean and standard deviation for the dip distribution, followed by
mean and standard deviation for the dip-direction distribution.
l uniform: The dip {and dip direction, in 3D} are drawn from a uniform distribution. No additional parameters can be given.
Note
In 2D, dip is the clockwise angle measured from the positive x-axis in degrees. In 3D, dip is the angle from the dip direction projected on the xy-plane to the
fracture surface measured in the negative z-direction. Dip direction in 3D is measured in a clockwise fashion from the positive y-axis.
position s a1...an
Define the generation rule for fracture position with parameters . The supported options for s are uniform, gauss, bootstrapped and fish. The meaning of
these keywords is the same as for the orientation keyword except that the position is a {2D vector in 2D; 3D vector in 3D}. Consequently, if bootstrapped is
specified, the file must contain the required number of values, and if fish is specified, the FISH function must return a vector of correct dimension. Additionally,
the mean and standard deviations must be vectors if the gauss keyword is specified.
size s a1...an
Define the distribution of fracture sizes. The fracture size is defined as the {fracture length, in 2D; disk diameter, in 3D}. The supported options for s are uniform,
gauss, power-law, bootstrapped and fish. The power-law specifier defines a negative power-law distribution which requires one parameter that is the exponent of
the distribution with > 0. The remaining s options are as specified in the orientation description, except that the return value is a floating point value. Thus, only
two arguments follow the gauss specifier: the bootstrapped file must follow a one-dimensional format; and the fish function must return a single value.
size-limits fmin fmax
Fracture size limits must fall within the range [fmin, fmax]. By default, fmin = 1.0 and fmax = +∞. Fracture size is defined as the {length, in 2D; diameter, in
3D}.
Usage Example
The following example illustrates how the fracture template create command can be used to build a simple template and generate one realization. Here, the template
defines a power-law distribution for fracture sizes with an exponent of 3.5 uniform positions and a fisher distribution for orientations.
model new
model random 10000
fracture template create 'example' orientation fisher 60 250 100 position uniform size power-law 3.5 size-limits 0.5 10
fracture generate template 'example' dfn 'realization_1' fracture-count 300
;Create more fractures using this template
fracture generate template 'example' dfn 'realization_2' mass-density 1
return
The following example illustrates how the fracture template create command can be used to build a tuned template and generate one realization. Here, fracture
orientations and sizes are drawn from user-defined distributions. The orientation distribution is defined by the fish function d2uniform and the size distribution by the fish
function lognormallaw.
model new
model random 10000
;Define a log-normal distribution for fracture sizes
fish define log_normallaw(mean,sigma)
w=2.0
v1=0.0
v2=0.0
z1=1
loop while w>=1
v1 = 2.0*math.random.uniform-1.0
w = v1*v1+v2*v2
endloop
w=math.sqrt((-2.0*math.log(w))/w)
z1=v1*w;
val=mean+z1*sigma
log_normallaw = math.exp(val)
end
;Define the 2D normal distribution for dip and dip direction
fish define d2uniform(maxdip,maxdipd)
local dip = math.random.uniform*maxdip
local dipd = math.random.uniform*maxdipd
d2uniform=vector(dip,dipd)
end
;Create a fracture template using these FISH functions
fracture template create 'example' orientation fish d2uniform(90,360) size fish log_normallaw(0,2)
;Generate fractures using this template
fracture generate template 'example' mass-density 0.5
return
The same example in 2D:
model new
model domain extent -5 5 -5 5

; define the log-normal distribution for fracture sizes
fish define lognormallaw(mean,sigma)
w=2.0
v1=0.0
v2=0.0
z1=1
loop while w>=1
w = v1*v1+v2*v2
endloop
w=math.sqrt((-2.0*math.log(w))/w)
z1=v1*w;
val=mean+z1*sigma
lognormallaw = math.exp(val)
end
; define the 2D normal distribution for dip and dip direction
fish define d2uniform(maxdip)
local dip = math.random.uniform*maxdip
d2uniform=dip
end
; define the template
fracture template create 'example' orientation fish d2uniform(90) size fish @lognormallaw(0,2)
; generate one realization
fracture generate template 'example' mass-density 2
return
See Also: fracture export | fracture generate | fracture import
fracture template delete command

Syntax
fracture template delete <range>
Delete fracture generation templates. A fracture generation template is a set of statistical parameters used to generate fractures with the fracture generate command.
These parameters are the size distribution, the position distribution and the orientation distribution. Once fractures have been generated, an association may exist
between the fracture generation template and the generated fractures.
Note
The default fracture generation template cannot be deleted.
fracture template modify-default command

Syntax
fracture template modify-default keyword
Primary keywords:
dip-direction-limits | dip-limits | orientation | position | size | size-limits
Modify the default fracture generation template. A fracture generation template is a set of statistical parameters used to generate fractures with the fracture generate
command. If no fracture generation template is specified, the default template is used. Upon a model new, the default fracture generation template is given the
following properties: 1) uniform fracture positions; 2) uniform fracture orientations (dip between 0 and 180 degrees in 2D; dip between 0 and 90 degrees, dip direction
between 0 and 360 degrees in 3D); 3) fracture sizes obeying a negative power-law distribution with exponent 4; and 4) minimum fracture size is size 1.0 and maximum
fracture size is ∞. The default fracture generation template is saved with the model state and a DFN cannot be linked to the default template. The following keywords
may be applied:
dip-direction-limits fmin fmax (3D only)
Specify that the fracture dip directions must fall in the range [fmin, fmax] degrees. By default, fmin = 0 and fmax = 360.
dip-limits fmin fmax
Specify that the fracture dips must fall in the range [fmin, fmax] degrees. By default, {fmin = 0 and fmax = 180, in 2D; fmin = 0 and fmax =90, in 3D}.
orientation s a1...an
Define the generation rule for fracture orientations with the parameters . The following options for s are supported:
l bootstrapped: The dip {and dip direction, in 3D} are bootstrapped from a file. One parameter must be given: the file name holding the discrete distribution
of values. This file obeys the bootstrapped distribution file format given in DFN-Related File Formats.
l dips (3D only): The dip and dip direction are bootstrapped from a DIPS file. One parameter must be given: the file name holding the discrete distribution of
values. This file obeys the DIPS file format given in DFN-Related File Formats.
l fish: The fish keyword is used to get values from a user-defined FISH function. The function name is given using , and the function arguments (any
number) are given after the function name. The function must return a {float, in 2D; 2 dimensional vector, in 3D}.
l fisher (3D only): The dip and dip direction are drawn from a Fisher distribution. Three additional parameters are required: dip, dip direction and .
l gauss: The dip {and dip direction, in 3D} are drawn from Gaussian distributions. In 2D, two additional parameters are required, specifying the mean and
standard deviation of the dip distribution. In 3D, four additional parameters are required: mean and standard deviation for the dip distribution, followed by
mean and standard deviation for the dip-direction distribution.
l uniform: The dip {and dip direction, in 3D} are drawn from a uniform distribution. No additional parameters can be given.
Note
In 2D, dip is the clockwise angle measured from the positive x-axis in degrees. In 3D, dip is the angle from the dip direction projected on the xy-plane to the
fracture surface measured in the negative z-direction. Dip direction in 3D is measured in a clockwise fashion from the positive y-axis.
position s a1...an
Define the generation rule for fracture position with parameters . The supported options for s are uniform, gauss, bootstrapped and fish. The meaning of these
keywords is the same as for the orientation keyword except that the position is a {2D vector in 2D; 3D vector in 3D}. Consequently, if bootstrapped is specified,
the file must contain the required number of values, and if fish is specified, the FISH function must return a vector of correct dimension. Additionally, the mean
and standard deviations must be vectors if the gauss keyword is specified.
size s a1...an
Define the distribution of fracture sizes. The fracture size is defined as the {fracture length, in 2D; disk diameter, in 3D}. The supported options for s are uniform,
gauss, power-law, bootstrapped and fish. The power-law specifier defines a negative power-law distribution which requires one parameter that is the exponent of
the distribution with > 0. The remaining s options are as specified in the orientation description, except that the return value is a floating point value. Thus, only
two arguments follow the gauss specifier: the bootstrapped file must follow a one-dimensional format; and the fish function must return a single value.
size-limits fmin fmax
Fracture size limits must fall within the range [fmin, fmax]. By default, fmin = 1.0 and fmax = +∞. Fracture size is defined as the {length, in 2D; diameter, in
3D}.
fracture verify-file command

Syntax
fracture verify-file keyword
Primary keywords:
file | format | property-file
Verify a DFN file. Before importing fractures from a DFN file, one should use the fracture verify-file command to check the validity/characteristics of the
fractures represented in the file. The following quantities are displayed:
l error information while reading the DFN file;

l the number of fractures in the file;
l the minimum/maximum spatial range of the fractures;
l the minimum/average/maximum fracture {length in 2D; area in 3D}; and
l the DFN center.
This tool can be very useful when identifying invalid fractures, as well as the appropriate offset/scaling to be used with the imported fractures.
file s
Specify the DFN file to verify.
format keyword
Specify the file format. If no format is specified, then the file extension of the name specified with the file keyword is used to determine the file format. A '.dat'
file extension is assumed to be in the itasca format, a '.flab' file extension is assumed to be in the fishlab format, and a '.fab' file extension is assumed to be in the
fracman format.
itasca
The itasca format is as specified in DFN-Related File Formats, and is the default format.
fishlab (3D ONLY)
The fishlab format is the flowplane format used in FISHLab.
fracman
The fracman format follows the FracMan ASCII output format.
property-file s
Indicate the property file to be queried. See DFN-Related File Formats for a definition of the property file format.
Usage Example
The following example illustrates how the fracture verify-file command is used to pre-parse a DFN file. It will print useful fracture statistics from the DFN file,
including:
l the number of properties,

l the number of fractures,
l the size of the containing domain in x, y and z directions,
l the range of fracture areas, that can be converted into equivalent diameters, and
l the fracture center.
Files are generated with the example of the fracture export command.
model new
;Verify fractures in a file - see the associated information in the console
fracture verify-file 'example.dat' format itasca property-file 'example_prop.dat'
return
See Also: fracture export | fracture import
FISH Functions
l DFN Utilities
l Fracture Template Utilities
l Fracture Fracture Utilities
l Fracture Vertex Utilities
l Fracture Intersection Set Utilities
l Fracture Intersection Utilities
DFN Utilities
dfn.contactmap(D_PNT<,INT>)
Get active contacts associated with a DFN.
dfn.contactmap.all(D_PNT<,INT>)
Get all contacts associated with a DFN.
dfn.create(<INT><,STR>)
Create a DFN.
dfn.delete(D_PNT)
Delete a DFN.
dfn.dominance(D_PNT)
Get/set the DFN dominance.
dfn.extra(D_PNT<,INT>)
Get/set a DFN extra variable.
dfn.find(INT/STR)
Find a DFN.
dfn.fracturelist(D_PNT)
Get the fracture list of the DFN.
dfn.fracturenum(D_PNT)
Get the number of fractures.
dfn.group(D_PNT<,STR>)
Get/set DFN groups.
dfn.group.remove(D_PNT,STR)
Remove DFN groups.
dfn.id(D_PNT)
Get the DFN ID.
dfn.isgroup(D_PNT,STR<,STR>)
Indicate DFN group status.
dfn.list
Get the global DFN list.
dfn.maxid
Get the maximum DFN ID.
dfn.name(D_PNT)
Get the DFN name.
dfn.num
Get the number of DFNs.
dfn.prop(D_PNT,STR)
Set a property of all fractures in a DFN.
dfn.template(D_PNT)
Get the fracture template.
dfn.typeid
Get the DFN type number.
Fracture Template Utilities
fracture.template.ddirmax(DT_PNT)(3D only)
Get/set the maximum dip direction.
fracture.template.ddirmin(DT_PNT)(3D only)
Get/set the minimum dip direction.
fracture.template.dipmax(DT_PNT)
Get/set the maximum dip.
fracture.template.dipmin(DT_PNT)
Get/set the minimum dip.
fracture.template.find(INT/STR)
Find a DFN template.
fracture.template.id(DT_PNT)
Get the DFN template ID.
fracture.template.list
Get the DFN template list.
fracture.template.maxid
Get the maximum DFN template ID.
fracture.template.name(DT_PNT)
Get the DFN template name.
fracture.template.norientparam(DT_PNT)
Get the number of orientation parameters.
fracture.template.nposparam(DT_PNT)
Get the number of position parameters.
fracture.template.nsizeparam(DT_PNT)
Get the number of size parameters.
fracture.template.num
Get the number of DFN templates.
fracture.template.orientparam(DT_PNT,INT)
Get/set an orientation parameter.
fracture.template.orienttype(DT_PNT)
Get/set the DFN template orientation type name.
fracture.template.posparam(DT_PNT,INT)
Get/set a position parameter.
fracture.template.postype(DT_PNT)
Get/set the DFN template position type name.
fracture.template.sizemax(DT_PNT)
Get/set the maximum size.
fracture.template.sizemin(DT_PNT)
Get/set the minimum size.
fracture.template.sizeparam(DT_PNT,INT)
Get/set a size parameter.
fracture.template.sizetype(DT_PNT)
Get/set the DFN template size type name.
fracture.template.typeid
Get the DFN template type number.
Fracture Utilities
fracture.aperture(FR_PNT)
Get/set the fracture aperture.
fracture.area(FR_PNT)(3D only)
Get/set the fracture area.
fracture.contactmap(FR_PNT<,INT>)
Get active contacts associated with a fracture.
fracture.contactmap.all(FR_PNT<,INT>)
Get all contacts associated with a fracture.
fracture.copy(FR_PNT<,D_PNT,INT>)
Copy a fracture.
fracture.create(D_PNT,ARR_PNT<,INT>)
Create a fracture.
fracture.ddir(FR_PNT)(3D only)
Get/set the fracture dip direction.
fracture.delete(FR_PNT)
Delete a fracture.
fracture.dfn(FR_PNT)
Get the fracture's DFN.
fracture.diameter(FR_PNT)(3D only)
Get/set the fracture diameter.
fracture.dip(FR_PNT)
Get/set the fracture dip.
fracture.extra(FR_PNT<,INT>)
Get/set a fracture extra variable.
fracture.find(INT)
Find a fracture.
fracture.genpos(FR_PNT<,INT>)
Get the fracture generation position.
fracture.gensize(FR_PNT)
Get the fracture generation {length in 2D; diameter in 3D}.
fracture.gintersect(FR_PNT,GSET_PNT)
Get the fracture/geometry intersection status.
fracture.group(FR_PNT<,INT>)
Get/set fracture groups.
fracture.group.remove(FR_PNT,STR)
Remove fracture groups.
fracture.id(FR_PNT)
Get the fracture ID.
fracture.interarray(FR_PNT<,D_PNT>)
Get an array of fracture intersections.
fracture.intersect(FR_PNT,FR_PNT)
Get the fracture/fracture intersection status.
fracture.isdisk(FR_PNT)(3D only)
Get the fracture disk status.
fracture.isgroup(FR_PNT,STR<,INT>)
Indicate fracture group status.
fracture.isprop(FR_PNT,STR)
Query the existence of a property.
fracture.len(FR_PNT)(2D only)
Get/set the fracture length.
fracture.list
Get the global fracture list.
fracture.maxid
Get the maximum fracture ID.
fracture.normal(FR_PNT<,INT>)
Get/set the fracture normal.
fracture.num
Get the total number of fractures.
fracture.pointnear(FR_PNT,VEC)
Get the closest point on a fracture.
fracture.pos(FR_PNT<,INT>)
Get/set the fracture position.
fracture.prop(FR_PNT,STR)
Get/set a fracture property.
fracture.typeid
Get the fracture type number.
fracture.vertexarray(FR_PNT)
Get an array of fracture vertices.
Fracture Vertex Utilities
fracture.vertex.find(INT)
Find a fracture vertex.
fracture.vertex.list
Get the fracture vertex list.
fracture.vertex.maxid
Get the maximum fracture vertex ID.
fracture.vertex.num
Get the number of fracture vertices.
fracture.vertex.pos(FV_PNT<,INT>)
Get the fracture vertex position.
fracture.vertex.typeid
Get the fracture vertex type number.
Fracture Intersection Set Utilities
fracture.intersect.set.delete(FIS_PNT)
Delete a fracture intersection set.
fracture.intersect.set.find(INT/STR)
Find a fracture intersection set.
fracture.intersect.set.id(FIS_PNT)
Get the fracture intersection set ID.
fracture.intersect.set.interlist(FIS_PNT)
Get the fracture intersection list.
fracture.intersect.set.internum(FIS_PNT)
Get the number of intersections in the set.
fracture.intersect.set.list
Get the fracture intersection set list.
fracture.intersect.set.maxid
Get the maximum fracture intersection set ID.
fracture.intersect.set.name(FIS_PNT)
Get the fracture intersection set name.
fracture.intersect.set.num
Get the number of fracture intersection sets.
fracture.intersect.set.path(FIS_PNT,FR_PNT,FR_PNT)
Get the path between fractures.
fracture.intersect.set.typeid
Get the fracture intersection set type number.
Fracture Intersection Utilities
fracture.intersect.end1(FI_PNT)
Get the first fracture in an intersection.
fracture.intersect.end2(FI_PNT)
Get the second intersecting object.
fracture.intersect.find(INT)
Find a fracture intersection.
fracture.intersect.len(FI_PNT)(3D only)
Get the intersection length.
fracture.intersect.list
Get the fracture intersection list.
fracture.intersect.maxid
Get the maximum fracture intersection ID.
fracture.intersect.npolylinept(FI_PNT)(3D only)
Get the number of polyline points in an intersection.
fracture.intersect.num
Get the number of fracture intersections.
fracture.intersect.polylinept(FI_PNT)(3D only)
Get a polyline point position in an intersection.
fracture.intersect.pos1(FI_PNT<,INT>)
Get the first fracture intersection end position.
fracture.intersect.pos2(FI_PNT<,INT>)(3D only)
Get the second fracture intersection end position.
fracture.intersect.set(FI_PNT)
Get the intersection set.
fracture.intersect.typeid
Get the fracture intersection type number.
l dfn.contactmap
l dfn.contactmap.all
l dfn.create
l dfn.delete
l dfn.dominance
l dfn.extra
l dfn.find
l fracture.aperture
l fracture.area
l fracture.centerdensity
l fracture.contactmap
l fracture.contactmap.all
l fracture.copy
l fracture.create
l fracture.ddir
l fracture.delete
l fracture.density
l fracture.dfn
l fracture.diameter
l fracture.dip
l fracture.extra
l fracture.find
l fracture.genpos
l fracture.gensize
l fracture.geomp10
l fracture.geomp20
l fracture.geomp21
l fracture.geomtrace
l fracture.gintersect
l fracture.group
l fracture.group.remove
l fracture.id
l fracture.inbox
l fracture.interarray
l fracture.intersect
l fracture.isdisk
l fracture.isgroup
l fracture.isprop
l fracture.len
l fracture.list
l fracture.maxid
l fracture.near
l fracture.normal
l fracture.num
l fracture.p10
l fracture.percolation
l fracture.pointnear
l fracture.pos
l fracture.prop
l fracture.typeid
l fracture.vertexarray
l dfn.fracturelist
l dfn.fracturenum
l dfn.group
l dfn.group.remove
l dfn.id
l fracture.intersect.end1
l fracture.intersect.end2
l fracture.intersect.find
l fracture.intersect.len
l fracture.intersect.list
l fracture.intersect.maxid
l fracture.intersect.npolylinept
l fracture.intersect.num
l fracture.intersect.polylinept
l fracture.intersect.pos1
l fracture.intersect.pos2
l fracture.intersect.set
l fracture.intersect.typeid
l dfn.isgroup
l dfn.list
l dfn.maxid
l dfn.name
l dfn.num
l dfn.prop
l fracture.intersect.set.delete
l fracture.intersect.set.find
l fracture.intersect.set.id
l fracture.intersect.set.interlist
l fracture.intersect.set.internum
l fracture.intersect.set.list
l fracture.intersect.set.maxid
l fracture.intersect.set.name
l fracture.intersect.set.num
l fracture.intersect.set.path
l fracture.intersect.set.typeid
l dfn.template
l fracture.template.ddirmax
l fracture.template.ddirmin
l fracture.template.dipmax
l fracture.template.dipmin
l fracture.template.find
l fracture.template.id
l fracture.template.list
l fracture.template.maxid
l fracture.template.name
l fracture.template.norientparam
l fracture.template.nposparam
l fracture.template.nsizeparam
l fracture.template.num
l fracture.template.orientparam
l fracture.template.orienttype
l fracture.template.posparam
l fracture.template.postype
l fracture.template.sizemax
l fracture.template.sizemin
l fracture.template.sizeparam
l fracture.template.sizetype
l fracture.template.typeid
l dfn.typeid
l fracture.vertex.find
l fracture.vertex.list
l fracture.vertex.maxid
l fracture.vertex.num
l fracture.vertex.pos
l fracture.vertex.typeid
dfn.contactmap
Syntax
m = dfn.contactmap(dfn<,itype>)
Get active contacts associated with a DFN.
Returns: m - map of contacts
Note
Iterate over a FISH map using the loop foreach construct.

Arguments: dfn - DFN pointer
itype - optional contact type ID used to filter the returned contacts
dfn.contactmap.all
Syntax
m = dfn.contactmap.all(dfn<,itype>)
Get all contacts associated with a DFN. Inactive contacts are included.
Note
Iterate over a FISH map using the loop foreach construct.

dfn.create
Syntax
dfn = dfn.create(<id><,s>)
Create a DFN. The DFN is empty, and its dominance value is set to the next available dominance (see the fracture contact-model command and the
dfn.dominance FISH intrinsic for further details regarding the DFN dominance). If no id or s is specified, then the next available ID is chosen and the name is set to
dfnXX, where XX is the ID.
Returns: dfn - DFN pointer

Arguments: id - Optional ID that, if not given, is assigned to the next available ID.
s - optional name
dfn.delete
Syntax
void = dfn.delete(dfn)
Delete a DFN. All fractures and corresponding intersections are deleted.
Returns: void - void value

dfn.dominance
Syntax
idom = dfn.dominance(dfn)
dfn.dominance(dfn) = idom
Get/set the DFN dominance. See the fracture contact-model command for further details.
Returns: idom - DFN dominance

Accepts: idom - DFN dominance
dfn.extra
Syntax
a = dfn.extra(dfn<,i>)
dfn.extra(dfn<,i>) = a
Get/set a DFN extra variable.

i - Optional extra index. If not provided, then i is taken to equal 1.
dfn.find
Syntax
pd = dfn.find(ad)
Find a DFN.
Note
Either the DFN ID or the DFN name can be specified.
Returns: pd - DFN pointer

Arguments: ad - DFN ID or the DFN name
fracture.aperture
Syntax
fap = fracture.aperture(frac)
fracture.aperture(frac) = fap
Get/set the fracture aperture.
Returns: fap - fracture aperture where fap ≥ 0

Accepts: fap - fracture aperture where fap ≥ 0
Arguments: frac - fracture pointer
fracture.area
Syntax
farea = fracture.area(frac) (3D only)

fracture.area(frac) = farea (3D only)
Get/set the fracture area.
Returns: farea - fracture area with farea > 0
Accepts: farea - fracture area farea > 0

fracture.centerdensity
Syntax
fracture.contactmap
Syntax
m = fracture.contactmap(frac<,itype>)
Get active contacts associated with a fracture. Iterate over a FISH map using the loop foreach construct.
Returns: cmap - map of contacts

fracture.contactmap.all
Syntax
m = fracture.contactmap.all(frac<,itype>)
Get all contacts associated with a fracture. Inactive contacts are included. Iterate over a FISH map using the loop foreach construct.

fracture.copy
Syntax
clone = fracture.copy(toclone<,dfn,id>)
Copy a fracture.
Returns: clone - pointer to newly created fracture

Arguments: toclone - pointer to fracture to be cloned
dfn - Optional pointer to the DFN where the cloned fracture is to be placed. If dfn is not specified, then a copy is placed in the same DFN to which clone
belongs.
id - The optional ID for the newly created fracture, if not specified, is set to the next available ID.
fracture.create
Syntax
frac = fracture.create(dfn,arr<,id>)
Create a fracture. The fracture is added to dfn.
Returns: frac - fracture pointer

arr - FISH array of the fracture parameters. arr must be a one-dimensional FISH array whose first element is a string specifying the type of fracture and
the subsequent elements are the fracture parameters.
In 2D, either the dip or vertices strings can be given. If the dip format is specified, the second element of the array is the position of the fracture center,
the third element is the fracture length, and the fourth element is the dip (in degrees from the positive x-direction following the clockwise measuring
convention). If the vertices format is specified in 2D, then the second element of the array is the number of vertices (must be two), and the third and
fourth elements are vectors specifying the ends of the fracture.
In 3D, either the disk or vertices strings can be given. If the disk format is specified, the second element of the array is the position of the fracture center,
the third element is the fracture diameter, the fourth element is the dip in degrees (where 0 ≤ dip ≤ 90), and the fifth element is the dip direction in degrees
(where 0 ≤ dip direction ≤ 360). If the vertices format is specified in 3D, then the second element in the array is the number of vertices (must be greater
than three) and each subsequent element is the position of one of the fracture vertices. These can be given in any order.
Note
l The proposed fracture must fall entirely within the model domain.
l The fracture dominance is set to the next available value. See the fracture contact-model command for further details.
id - The optional fracture ID. If not specified, the fracture ID is set to the next available ID.
fracture.ddir
Syntax
fddir = fracture.ddir(frac) (3D only)

fracture.ddir(frac) = fddir (3D only)
Get/set the fracture dip direction.
Note
Admissible values for fracture dip direction (in degrees) are 0 ≤ fddir ≤ 360.
Returns: fddir - fracture dip direction in degrees

Accepts: fddir - fracture dip direction in degrees
fracture.delete
Syntax
void = fracture.delete(frac)
Delete a fracture. All intersections that refer to this fracture are also deleted.

fracture.density
Syntax
fracture.dfn
Syntax
dfn = fracture.dfn(frac)
Get the fracture's DFN.
Returns: dfn - DFN pointer

fracture.diameter
Syntax
fdia = fracture.diameter(frac) (3D only)

fracture.diameter(frac) = fdia (3D only)
Get/set the fracture diameter.
Note
The fracture must be disk-shaped (see fracture.isdisk). The modified fracture must fit within the model domain.
Accepts: fdia - fracture diameter where fdia > 0

Returns: fdia - fracture diameter where fdia > 0
fracture.dip
Syntax
fdip = fracture.dip(frac)
fracture.dip(frac) = fdip
Get/set the fracture dip.
Note
Admissible values for fracture dip (in degrees) are { 0 ≤ fdip ≤ 180 in 2D; 0 ≤ fdip ≤ 90 in 3D}.
Returns: fdip - fracture dip in degrees

Accepts: fdip - fracture dip in degrees
fracture.extra
Syntax
a = fracture.extra(f<,i>)
fracture.extra(f<,i>) = a
Get/set a fracture extra variable.

Arguments: f - fracture pointer
i - Optional extra index. If not provided, then i is taken to equal 1.
fracture.find
Syntax
fp = fracture.find(id)
Find a fracture.
Returns: fp - fracture pointer

Arguments: id - fracture ID
fracture.genpos
Syntax
Vector Access
pos = fracture.genpos(frac<,icomp>)
Get the fracture generation position.
Returns: pos - generation position vector or component

icomp - optional vector component
Component Access
fpos = fracture.genpos.x(frac)
Get the x-component of the fracture generation position.
Returns: fpos - x-component of the generation position

fpos = fracture.genpos.y(frac)
Get the y-component of the fracture generation position.
Returns: fpos - y-component of the generation position

fpos = fracture.genpos.z(frac) (3D only)
Get the z-component of the fracture generation position.
Returns: fpos - z-component of the generation position

fracture.gensize
Syntax
f = fracture.gensize(frac)
Get the fracture generation {length in 2D; diameter in 3D}. This corresponds with the fracture size prior to clipping at the tolerance extent.
Returns: f - fracture generation size

fracture.geomp10
Syntax
fracture.geomp20
Syntax
fracture.geomp21
Syntax
fracture.geomtrace
Syntax
fracture.gintersect
Syntax
bintersect = fracture.gintersect(frac,gset)
Get the fracture/geometry intersection status.
Note
Intersections need not be calculated.
Returns: bintersect - fracture intersection status

gset - geometry set pointer
fracture.group
Syntax
s = fracture.group(f<,i>)
fracture.group(f<,i>) = s
Get/set fracture groups.
Accepts: s - group name

Returns: s - group name
i - Optional group slot. If not provided, then i is taken to equal 1.
fracture.group.remove
Syntax
i = fracture.group.remove(frac,s)
Remove fracture groups. The specified group name is removed from all group slots.
Returns: i - first slot in which s was found, or 0 if not found

s - group name
fracture.id
Syntax
id = fracture.id(frac)
Get the fracture ID.
Returns: id - fracture ID
fracture.inbox
Syntax
fracture.interarray
Syntax
iarray = fracture.interarray(frac<,dfn>)
Get an array of fracture intersections. Iterate over a FISH array using the loop and array.size constructs.
Returns: iarray - array of fracture intersections

dfn - Optional DFN pointer. If specified, then only intersections with fractures belonging to dfn are returned.
fracture.intersect
Syntax
bintersect = fracture.intersect(frac1,frac2)
Get the fracture/fracture intersection status.
Note
Intersections need not be calculated.
Returns: bintersect - fracture intersection status

Arguments: frac1 - fracture pointer
frac2 - fracture pointer
fracture.isdisk
Syntax
bdisk = fracture.isdisk(frac) (3D only)
Get the fracture disk status.
Returns: bdisk - fracture disk status

fracture.isgroup
Syntax
b = fracture.isgroup(frac,s<,islot>)
Indicate fracture group status.

s - group name
islot - optional slot that defaults to 1
fracture.isprop
Syntax
b = fracture.isprop(f,s)
Query the existence of a property.
Returns: b - Boolean indicating property status

s - property name
fracture.len
Syntax
flen = fracture.len(frac) (2D only)

fracture.len(frac) = flen (2D only)
Get/set the fracture length.
Returns: flen - fracture length with flen > 0

Accepts: flen - fracture length with flen > 0
fracture.list
Syntax
l = fracture.list
Get the global fracture list. Use the loop foreach construct to iterate through the list.
Returns: l - fracture list
See Also: dfn.fracturelist
fracture.maxid
Syntax
id = fracture.maxid
Get the maximum fracture ID.
Returns: id - maximum fracture ID
fracture.near
Syntax
fracture.normal
Syntax
Vector Access
norm = fracture.normal(frac<,icomp>)
fracture.normal(frac<,icomp>) = norm
Get/set the fracture normal.
Note
The fracture must fall completely within the model domain.

l
The sign of the normal is inverted if the {y-component in 2D; z-component, in 3D} is less than 0.
l
l The provided normal is normalized (i.e., norm / | norm |).
Returns: norm - normal vector or component

Accepts: norm - normal vector or component
Component Access
fnorm = fracture.normal.x(frac)
fracture.normal.x(frac) = fnorm
Get/set the x-component of the fracture normal.
Note

l
The sign of the normal is inverted if the {y-component in 2D; z-component in 3D} is less than 0.
l
l The provided normal is normalized.
Returns: fnorm - x-component of the fracture normal

Accepts: fnorm - x-component of the fracture normal
fnorm = fracture.normal.y(frac)
fracture.normal.y(frac) = fnorm
Get/set the y-component of the fracture normal.
Note
lThe fracture must fall completely within the model domain.

lThe sign of the normal is inverted if the {y-component in 2D; z-component in 3D} is less than 0.
Returns: fnorm - y-component of the fracture normal

Accepts: fnorm - y-component of the fracture normal
fnorm = fracture.normal.z(frac) (3D only)

fracture.normal.z(frac) = fnorm
Get/set the z-component of the fracture normal.
Note
lThe fracture must fall completely within the model domain.

lThe sign of the normal is inverted if the y-component (z-component; in 3D) is less than 0.
Returns: fnorm - z-component of the fracture normal

Accepts: fnorm - z-component of the fracture normal
fracture.num
Syntax
inum = fracture.num
Get the total number of fractures.
Returns: inum - number of fractures
See Also: dfn.fracturenum
fracture.p10
Syntax
fracture.percolation
Syntax
fracture.pointnear
Syntax
vrcp = fracture.pointnear(frac,vpos)
Get the closest point on a fracture.
Returns: vrcp - closest point on the fracture to vpos

vpos - position vector for closest point calculation
fracture.pos
Syntax
Vector Access
pos = fracture.pos(frac<,icomp>)
fracture.pos(frac<,icomp>) = pos
Get/set the fracture position.
Note
Returns: pos - position vector or component

Accepts: pos - position vector or component
Component Access
fpos = fracture.pos.x(frac)
fracture.pos.x(frac) = fpos
Get/set the x-component of the fracture position.
Note
Returns: fpos - x-component of the position

Accepts: fpos - x-component of the position
fpos = fracture.pos.y(frac)
fracture.pos.y(frac) = fpos
Get/set the y-component of the fracture position.
Note
Returns: fpos - y-component of the position

Accepts: fpos - y-component of the position
fpos = fracture.pos.z(frac) (3D only)

fracture.pos.z(frac) = fpos
Get/set the z-component of the fracture position.
Note
Returns: fpos - z-component of the position

Accepts: fpos - z-component of the position
fracture.prop
Syntax
aprop = fracture.prop(frac,s)
fracture.prop(frac,s) = aprop
Get/set a fracture property.
Returns: aprop - property value

Accepts: aprop - property value
s - property name
fracture.typeid
Syntax
i = fracture.typeid
Get the fracture type number. The type ID can be used to uniquely identify fracture FISH pointers and distinguish them from any other type of FISH pointer.
fracture.vertexarray
Syntax
varray = fracture.vertexarray(frac)
Get an array of fracture vertices. Iterate over a FISH array using the loop and array.size constructs.
Returns: varray - array of vertices

dfn.fracturelist
Syntax
l = dfn.fracturelist(dfn)
Get the fracture list of the DFN. Use the loop foreach construct to iterate through the list.
Returns: l - DFN fracture list

See also
fracture.list
dfn.fracturenum
Syntax
inum = dfn.fracturenum(dfn)
Get the number of fractures.
Returns: inum - number of fractures

See also
dfn.fracturenum
dfn.group
Syntax
s = dfn.group(dfn<,slot>)
dfn.group(dfn<,slot>) = s
Get/set DFN groups. Use of the group logic is described in the Group topic.

Arguments: f - DFN pointer
slot - optional group slot. If not provided, then slot is taken to equal Default.
dfn.group.remove
Syntax
i = dfn.group.remove(dfn,s)
Remove DFN groups. The specified group name is removed from all group slots.
Returns: i - first slot in which s was found, or 0 if not found

s - group name
dfn.id
Syntax
id = dfn.id(dfn)
Get the DFN ID.
Returns: id - DFN ID
fracture.intersect.end1
Syntax
end = fracture.intersect.end1(inter)
Get the first fracture in an intersection.
Returns: end - fracture pointer

Arguments: inter - fracture intersection pointer
fracture.intersect.end2
Syntax
end = fracture.intersect.end2(inter)
Get the second intersecting object. If the intersection is with a geometry object, then a geometry set pointer is returned.
Returns: end - fracture or geometry set pointer

fracture.intersect.find
Syntax
fint = fracture.intersect.find(id)
Find a fracture intersection.
Returns: fint - fracture intersection pointer

Arguments: id - fracture intersection ID
fracture.intersect.len
Syntax
flen = fracture.intersect.len(inter) (3D only)
Get the intersection length.
Returns: flen - intersection length

fracture.intersect.list
Syntax
l = fracture.intersect.list
Get the fracture intersection list. Use the loop foreach construct to iterate through the list.
Returns: l - fracture intersection list
fracture.intersect.maxid
Syntax
id = fracture.intersect.maxid
Get the maximum fracture intersection ID.
Returns: id - maximum fracture intersection ID
fracture.intersect.npolylinept
Syntax
inum = fracture.intersect.npolylinept(inter) (3D only)
Get the number of polyline points in an intersection. Polyline intersections may result when intersections between fractures and geometry sets are delineated. See the
fracture intersections compute command for further details.
Returns: inum - number of polyline points

fracture.intersect.num
Syntax
inum = fracture.intersect.num
Get the number of fracture intersections.
Returns: inum - number of fracture intersections
fracture.intersect.polylinept
Syntax
vpos = fracture.intersect.polylinept(inter) (3D only)
Get a polyline point position in an intersection. Polyline intersections may result when intersections between fractures and geometry sets are delineated. See the
fracture intersections compute command for further details.
Returns: vpos - position vector or component

fracture.intersect.pos1
Syntax
Vector Access
pos = fracture.intersect.pos1(inter<,icomp>)
Get the first fracture intersection end position.

Component Access
fpos = fracture.intersect.pos1.x(inter)
Get the x-component of the first fracture intersection end position.

fpos = fracture.intersect.pos1.y(inter)
Get the y-component of the first fracture intersection end position.

fpos = fracture.intersect.pos1.z(inter) (3D only)
Get the z-component of the first fracture intersection end position.

fracture.intersect.pos2
Syntax
Vector Access
pos = fracture.intersect.pos2(inter<,icomp>) (3D only)
Get the second fracture intersection end position.

Component Access
fpos = fracture.intersect.pos2.x(inter) (3D only)
Get the x-component of the second fracture intersection end position.

fpos = fracture.intersect.pos2.y(inter) (3D only)
Get the y-component of the second fracture intersection end position.

fpos = fracture.intersect.pos2.z(inter) (3D only)
Get the z-component of the second fracture intersection end position.

fracture.intersect.set
Syntax
set = fracture.intersect.set(inter)
Get the intersection set.
Returns: set - intersection set
fracture.intersect.typeid
Syntax
itype = fracture.intersect.typeid
Get the fracture intersection type number. The type ID can be used to uniquely identify fracture intersection FISH pointers and distinguish them from any other type of
FISH pointer.
Returns: itype - type ID value
dfn.isgroup
Syntax
b = dfn.isgroup(dfn,s<,slot>)
Indicate DFN group status.

s - group name
slot - optional slot that defaults to "Default"
dfn.list
Syntax
l = dfn.list
Get the global DFN list. Use the loop foreach construct to iterate through the list.
Returns: l - DFN list
dfn.maxid
Syntax
id = dfn.maxid
Get the maximum DFN ID.
Returns: id - maximum DFN ID
dfn.name
Syntax
s = dfn.name(dfn)
Get the DFN name.
Returns: s - DFN name

dfn.num
Syntax
inum = dfn.num
Get the number of DFNs.
Returns: inum - number of DFNs
dfn.prop
Syntax
dfn.prop(dfn,s) = a
Set a property of all fractures in a DFN. The property s is created if it does not exist.
Properties are name-value pairs that are used to fill contact model properties. The list of mechanical contact models is given in the Contact Models section of the PFC
Help. CS snip here used in PFC: ":ref:-contact_models-" section. In the documentation for each contact model, a Properties table exists. These include: the linear,
linear contact bond, linear parallel bond, hertz, hysteretic, smooth joint, and the flat joint property tables.
Accepts: a - property value

s - property name
fracture.intersect.set.delete
Syntax
void = fracture.intersect.set.delete(set)
Delete a fracture intersection set. All intersections in this set are deleted.

Arguments: set - fracture intersection set pointer
fracture.intersect.set.find
Syntax
sp = fracture.intersect.set.find(i)
Find a fracture intersection set.
Returns: sp - fracture intersection set pointer

Arguments: i - fracture intersection set ID or name
fracture.intersect.set.id
Syntax
id = fracture.intersect.set.id(set)
Get the fracture intersection set ID.
Returns: id - fracture intersection set ID

fracture.intersect.set.interlist
Syntax
l = fracture.intersect.set.interlist(set)
Get the fracture intersection list. Use the loop foreach construct to iterate through the list.
Returns: l - fracture intersection list
fracture.intersect.set.internum
Syntax
inb = fracture.intersect.set.internum(set)
Get the number of intersections in the set.
Returns: inb - intersection number

fracture.intersect.set.list
Syntax
l = fracture.intersect.set.list
Get the fracture intersection set list. Use the loop foreach construct to iterate through the list.
Returns: l - fracture intersection set list
fracture.intersect.set.maxid
Syntax
id = fracture.intersect.set.maxid
Get the maximum fracture intersection set ID.
Returns: id - maximum fracture intersection set ID
fracture.intersect.set.name
Syntax
s = fracture.intersect.set.name(set)
Get the fracture intersection set name.
Returns: s - fracture intersection set name

fracture.intersect.set.num
Syntax
inum = fracture.intersect.set.num
Get the number of fracture intersection sets.
Returns: inum - number of intersection sets
fracture.intersect.set.path
Syntax
path = fracture.intersect.set.path(set,frac1,frac2)
Get the path between fractures. The fractures connecting frac1 to frac2 are held in the array. Iterate over a FISH array using the loop and array.size constructs.
Returns: path - array of fractures

frac1 - fracture pointer of path beginning
frac2 - fracture pointer of path termination
fracture.intersect.set.typeid
Syntax
itype = fracture.intersect.set.typeid
Get the fracture intersection set type number. The type ID can be used to uniquely identify fracture intersection set FISH pointers and distinguish them from any other
type of FISH pointer.
dfn.template
Syntax
template = dfn.template(dfn)
Get the fracture template. This is the template used to generate this DFN. If any fractures have been modified after generation, the return value will be 0.
Returns: template - DFN template pointer

fracture.template.ddirmax
Syntax
fdipd = fracture.template.ddirmax(template) (3D only)

fracture.template.ddirmax(template) = fdipd (3D only)
Get/set the maximum dip direction.
Note
lAdmissible values for fracture dip (in degrees) are 0 ≤ fdipd ≤ 360.
lSet access is not available for templates that have been used for generation.
Returns: fdipd - maximum dip direction in degrees
Accepts: fdipd - maximum dip direction in degrees
Arguments: template - DFN template pointer
fracture.template.ddirmin
Syntax
fdipd = fracture.template.ddirmin(template) (3D only)

fracture.template.ddirmin(template) = fdipd (3D only)
Get/set the minimum dip direction.
Note
lAdmissible values for fracture dip (in degrees) are 0 ≤ fdipd ≤ 360.
Returns: fdipd - minimum dip direction in degrees
Accepts: fdipd - minimum dip direction in degrees
fracture.template.dipmax
Syntax
fdip = fracture.template.dipmax(template)
fracture.template.dipmax(template) = fdip
Get/set the maximum dip.
Note
lAdmissible values for fracture dip (in degrees) are {0 ≤ fdip ≤ 180 in 2D; 0 ≤ fdip ≤ 90 in 3D}.
Accepts: fdip - maximum dip in degrees
Returns: fdip - maximum dip in degrees
fracture.template.dipmin
Syntax
fdip = fracture.template.dipmin(template)
fracture.template.dipmin(template) = fdip
Get/set the minimum dip.
Note
lAdmissible values for fracture dip (in degrees) are {0 ≤ fdip ≤ 180 in 2D; 0 ≤ fdip ≤ 90 in 3D}.
Returns: fdip - minimum dip in degrees
Accepts: fdip - minimum dip in degrees
fracture.template.find
Syntax
pt = fracture.template.find(at)
Find a DFN template.
Note
Either the DFN template ID or name can be specified.
Returns: pt - DFN template pointer

Arguments: at - DFN template ID or name
fracture.template.id
Syntax
id = fracture.template.id(template)
Get the DFN template ID.
Returns: id - DFN template ID

fracture.template.list
Syntax
l = fracture.template.list
Get the DFN template list. Use the loop foreach construct to iterate through the list.
Returns: l - DFN template list
fracture.template.maxid
Syntax
id = fracture.template.maxid
Get the maximum DFN template ID.
Returns: id - maximum DFN template ID
fracture.template.name
Syntax
s = fracture.template.name(template)
Get the DFN template name.
Returns: s - DFN template name

fracture.template.norientparam
Syntax
inum = fracture.template.norientparam(template)
Get the number of orientation parameters. The parameters can be set with the fracture.template.orientparam intrinsic. See the fracture template create
command for further details.
Returns: inum - number of orientation parameters

fracture.template.nposparam
Syntax
inum = fracture.template.nposparam(template)
Get the number of position parameters. The parameters can be set with the fracture.template.posparam intrinsic. See the fracture template create command
for further details.
Returns: inum - number of position parameters

fracture.template.nsizeparam
Syntax
inum = fracture.template.nsizeparam(template)
Get the number of size parameters. The parameters can be set with the fracture.template.sizeparam intrinsic. See the fracture template create command for
further details.
Returns: inum - number of size parameters

fracture.template.num
Syntax
inum = fracture.template.num
Get the number of DFN templates.
Returns: inum - number of DFN templates
fracture.template.orientparam
Syntax
a = fracture.template.orientparam(template,i)
fracture.template.orientparam(template,i) = a
Get/set an orientation parameter. The number of parameters can be assessed with the fracture.template.norientparam intrinsic. See the fracture template
create command for further details.
Note
Set access is not available for templates that have been used for generation.
Returns: a - an orientation parameter

Accepts: a - an orientation parameter
i - index of the orientation parameter
fracture.template.orienttype
Syntax
s = fracture.template.orienttype(template)
fracture.template.orienttype(template) = s
Get/set the DFN template orientation type name. Acceptable values are uniform, gauss, powerlaw, bootstrapped, fish, fisher (3D only), and dips (3D only). See the
fracture template create command for further details.
Note
Returns: s - DFN template orientation type name

Accepts: s - DFN template orientation type name
fracture.template.posparam
Syntax
a = fracture.template.posparam(template,i)
fracture.template.posparam(template,i) = a
Get/set a position parameter. The number of parameters can be assessed with the fracture.template.nposparam intrinsic. See the fracture template create
Note
Returns: a - a position parameter

Accepts: a - a position parameter
i - index of the position parameter
fracture.template.postype
Syntax
s = fracture.template.postype(template)
fracture.template.postype(template) = s
Get/set the DFN template position type name. Acceptable values are uniform, gauss, bootstrapped, and fish. See the fracture template create command for further
details.
Note
Accepts: s - DFN template position type name

Returns: s - DFN template position type name
fracture.template.sizemax
Syntax
fsize = fracture.template.sizemax(template)
fracture.template.sizemax(template) = fsize
Get/set the maximum size. The fracture size is defined as the {fracture length in 2D; disk diameter in 3D}.
Note
Returns: fsize - maximum size

Accepts: fsize - maximum size
fracture.template.sizemin
Syntax
fsize = fracture.template.sizemin(template)
fracture.template.sizemin(template) = fsize
Get/set the minimum size. The fracture size is defined as the {fracture length in 2D; disk diameter in 3D}.
Note
Returns: fsize - minimum size

Accepts: fsize - minimum size
fracture.template.sizeparam
Syntax
a = fracture.template.sizeparam(template,i)
fracture.template.sizeparam(template,i) = a
Get/set a size parameter. The number of parameters can be assessed with the fracture.template.nsizeparam intrinsic. See the fracture template create
Note
Returns: a - a size parameter

Accepts: a - a size parameter
i - index of the size parameter
fracture.template.sizetype
Syntax
s = fracture.template.sizetype(template)
fracture.template.sizetype(template) = s
Get/set the DFN template size type name. Acceptable values are uniform, gauss, powerlaw, bootstrapped, and fish. See the fracture template create command for
further details.
Note
Returns: s - DFN template size type name

Accepts: s - DFN template size type name
fracture.template.typeid
Syntax
itype = fracture.template.typeid
Get the DFN template type number. The type ID can be used to uniquely identify DFN template FISH pointers and distinguish them from any other type of FISH
pointer.
dfn.typeid
Syntax
itype = dfn.typeid
Get the DFN type number. The type ID can be used to uniquely identify DFN FISH pointers and distinguish them from any other type of FISH pointer.
fracture.vertex.find
Syntax
vert = fracture.vertex.find(id)
Find a fracture vertex.
Returns: vert - fracture vertex pointer

Arguments: id - fracture vertex ID
fracture.vertex.list
Syntax
l = fracture.vertex.list
Get the fracture vertex list. Use the loop foreach construct to iterate through the list.
Returns: l - fracture vertex list
fracture.vertex.maxid
Syntax
id = fracture.vertex.maxid
Get the maximum fracture vertex ID.
Returns: id - maximum fracture vertex ID
fracture.vertex.num
Syntax
inum = fracture.vertex.num
Get the number of fracture vertices.
Returns: inum - number of fracture vertices
fracture.vertex.pos
Syntax
Vector Access
pos = fracture.vertex.pos(vert<,icomp>)
Get the fracture vertex position.

Arguments: vert - fracture vertex pointer
Component Access
fpos = fracture.vertex.pos.x(vert)
Get the x-component of the fracture vertex position.
Returns: fpos - x-component of the vertex position

fpos = fracture.vertex.pos.y(vert)
Get the y-component of the fracture vertex position.
Returns: fpos - y-component of the vertex position

fpos = fracture.vertex.pos.z(vert) (3D only)
Get the z-component of the fracture vertex position.
Returns: fpos - z-component of the vertex position

fracture.vertex.typeid
Syntax
itype = fracture.vertex.typeid
Get the fracture vertex type number. The type ID can be used to uniquely identify fracture vertex FISH pointers and distinguish them from any other type of FISH
pointer.
Domain
The domain is an axis-aligned bounding box. Model components that utilize contact detection exist within the domain. Model components that do not exist in the model
domain include zones, gridpoints, structural elements, structural element nodes, geometry data, user-defined data (i.e., scalars, vectors and tensors). The domain is fixed: it
does not grow automatically as model components expand or disperse, though its size may be re-specified with the domain extent command. Domain boundaries can have
four conditions: destroy, stop, reflect, and periodic. As model components interact with the domain boundary, one of these conditions is applied. The default condition is the
stop condition.
Enclosing a model within a domain — rather than allowing a model to float freely in infinite space — greatly enhances efficiency in searching and contact detection. This in
turn improves performance of simulations.
Note
l Changes in the domain boundary condition take effect during the next timestep, and model components falling outside the domain are deleted if the domain size is
changed.
l Domains are mostly pertinent to PFC. In a FLAC3D model, only discrete fracture networks (DFNs) will be affected by the domain.
l Commands
l FISH Functions
Commands
Domain Commands
domain condition
Set the domain boundary conditions.
domain extent
Specify the locations of the sides of the domain.
domain strain-rate
Specify the domain strain rate.
l domain.condition command
l domain.extent command
l domain.strain-rate command
domain.condition command
Syntax
domain condition sx <sy sz > (sz is 3D only)
Set the domain boundary conditions.
Note
Domains are mostly pertinent to PFC. In a FLAC3D model, only discrete fracture networks (DFNs) will be affected by the domain.
Each domain condition applies to the two box sides that are perpendicular to the direction (e.g., sx applies to the two sides that are perpendicular to the x-direction). If
sx is specified alone, then this condition applies to all boundaries. Otherwise, {two strings in the order x,y in 2D; three strings in the order x,y,z in 3D} must be
specified. The default condition is the stop condition.
Acceptable boundary conditions are stop, reflect, destroy and periodic.
The stop condition imposes the constraint that when the body centroid falls outside the model domain, the velocity and spin of the body are nulled. For walls, once a
facet centroid falls outside the model domain, the velocity and spin are nulled, including any vertex velocities.
The reflect condition imparts the opposite sign of the velocity, and the spin is unchanged if the body centroid falls outside the model domain. The use of this condition
as a contact rule is not recommended since it may induce instabilities. The reflect condition is not compatible with walls intersecting the domain.
The destroy condition deletes balls, clumps and wall facets whose individual extents (i.e., an axis-aligned bounding box that tightly encompasses the object) fall outside
the model domain.
The periodic condition applies periodic boundary conditions. When the ball or clump centroid falls outside of the model domain, they are translated back to the opposite
side of the model. To ensure that contacts are created as if the model was continuous, "ghost" balls and clumps are introduced. The periodic condition is not compatible
with walls intersecting the domain.
CS: some accommodation of FLAC3D is probably wanted here; something that explains that this is more of a pfc thing, but it has applicability in F3D in the following
manner...
domain.extent command
Syntax
domain extent fxl fxu <fyl fyu fzl fzu >
Specify the locations of the sides of the domain. Each set of values applies to the lower and upper bound of that dimension of the domain. If only fxl and fxu are
specified, then the domain is a cube.
domain.strain-rate command
Syntax
domain strain-rate v
Specify the domain strain rate.
CS: well that's rather spare. Probably could use some further elucidation here.
FISH Functions
The type specifiers used in the FISH function signatures are given in the FISH Type Index topic.
Domain Utilities
domain.condition(STR)
Get/set the domain conditions.
domain.max(<INT>)
Get/set the upper domain corner.
domain.min(<INT>)
Get/set the lower domain corner.
domain.strain.rate(<INT>)
Get/set the domain strain rate.
l domain.condition
l domain.max
l domain.min
l domain.strain.rate
domain.condition
Syntax
sr = domain.condition(sd)
domain.condition(sd) = sr
Get/set the domain conditions. The domain conditions govern the behavior of objects that meet or intersect the model domain.
Returns: sd - condition with acceptable values destroy, reflect, periodic, and stop
Accepts: sd - condition with acceptable values destroy, reflect, periodic, and stop
Arguments: sr - domain direction with acceptable values {x and y in 2D; x, y, and z in 3D}
See Also: domain.max | domain.min | domain condition
domain.max
Syntax
Vector Access
v = domain.max()
domain.max() = v
Get/set the upper domain corner.
Returns: v - upper domain corner vector or component

Accepts: v - upper domain corner vector or component
Arguments: i - optional vector component
Component Access
f = domain.max.x()
domain.max.x() = f
Get/set the x-component of the upper domain corner.
Returns: f - x-component of the upper domain corner vector

Accepts: f - x-component of the upper domain corner vector
f = domain.max.y()
domain.max.y() = f
Get/set the y-component of the upper domain corner.
Returns: f - y-component of the upper domain corner vector

Accepts: f - y-component of the upper domain corner vector
f = domain.max.z() (3D only)

domain.max.z() = f (3D only)
Get/set the z-component of the upper domain corner.
Returns: f - z-component of the upper domain corner vector

Accepts: f - z-component of the upper domain corner vector
See Also: domain.condition | domain.min
domain.min
Syntax
Vector Access
v = domain.min()
domain.min() = v
Get/set the lower domain corner.
Returns: v - lower domain corner vector or component

Accepts: v - lower domain corner vector or component
Component Access
f = domain.min.x()
domain.min.x() = f
Get/set the x-component of the lower domain corner.
Returns: f - x-component of the lower domain corner vector

Accepts: f - x-component of the lower domain corner vector
f = domain.min.y()
domain.min.y() = f
Get/set the y-component of the lower domain corner.
Returns: f - y-component of the lower domain corner vector

Accepts: f - y-component of the lower domain corner vector
f = domain.min.z() (3D only)

domain.min.z() = f (3D only)
Get/set the z-component of the lower domain corner.
Returns: f - z-component of the lower domain corner vector

Accepts: f - z-component of the lower domain corner vector
See Also: domain.condition | domain.max
domain.strain.rate
Syntax
Vector Access
v = domain.strain.rate()
domain.strain.rate() = v
Get/set the domain strain rate.
Returns: v - domain strain rate vector or component

Accepts: v - domain strain rate vector or component
Component Access
f = domain.strain.rate.x()
domain.strain.rate.x() = f
Get/set the x-component of the domain strain rate.
Returns: f - x-component of the domain strain rate vector

Accepts: f - x-component of the domain strain rate vector
f = domain.strain.rate.y()
domain.strain.rate.y() = f
Get/set the y-component of the domain strain rate.
Returns: f - y-component of the domain strain rate vector

Accepts: f - y-component of the domain strain rate vector
f = domain.strain.rate.z() (3D only)

domain.strain.rate.z() = f (3D only)
Get/set the z-component of the domain strain rate.
Returns: f - z-component of the domain strain rate vector

Accepts: f - z-component of the domain strain rate vector
See Also: domain strain-rate
Extrude
An extrusion is a 2D geometric description of a model, which can be extruded in the third dimension to create FLAC3D zones. Multiple sets of extrusion data can be created,
each under a different name. At any time there may only be one currently active set. All commands on set objects (blocks, points, edges, segments) will apply to the objects in
the currently active set only (see extrude set select).
Points are created in space, connected to edges, which are then joined to form three- or four-sided blocks. Blocks may be split (at edges or at an interior point) to help achieve
the desired geometry. Edges are either linear or curved. If curved they follow a path given by a number of control points. Zoning is defined along block edges. On creation,
the default zoning along an edge is three; this may be adjusted subsequently. Zone size and distribution dependencies across edges are propagated automatically across
opposing faces of blocks. Block edges may use multiplier factors to increase the number of zones in areas of interest, and may take ratio assignments to achieve radial
meshing.
Points, edges, and blocks can be assigned group names, which are then assigned to the gridpoints, faces and zones derived from them when zones are generated from the
extrusion set.
The extrusion data are also accessible by FISH, which means that an extruded geometry can be scripted and parameterized.
The Extrusion Pane of the FLAC3D interface provides graphical input of these commands. As one performs operations in the Extrusion pane to build a set, the commands
underlying those operations — as detailed here — are emitted in the record and will be saved with the model state in a save (*.sav or *.f3dsav) file. The information in this
section is a reference on the extrusion commands and FISH functions. See The Extrusion Pane for instructions on constructing extrusions graphically in the interface.
l Block
l Edge
l Point
l Segment
l Set
Block
A block is a three- or four-sided 2D object that is composed of three or four edges (where any edge is defined by a curvature type and two end points). An extrusion set must
contain valid blocks in order to produce zones when the zone generate from-extruder command is used.
l Commands
l FISH Functions
Commands
Operations on extrusion blocks.
Extrude Block Commands
extrude block create

Create block(s).
extrude block delete
Delete block(s).
extrude block group
Assign/remove a group name to blocks.

extrude block id
Modify a single block by ID.
extrude block list
Print information about blocks.
extrude block multiplier
Set the zone multiplier.
extrude block position
Modify a block by position.
l create command
l delete command
l group command
l id command
l list command
l multiplier command
l position command
create command
Syntax
extrude block create keyword
Primary keywords:
at | automatic | by-edges | by-points
Create block(s).
at f1 f2 <keyword>
Create a block from the edges surrounding the point with the 2D coordinates f1 , f2.
group s1 <slot s2 >
Assign the created block the group name s1 (in slot s2 if provided, in slot Default if not).
automatic <keyword> <range>
Scan all points in the range given, and attempt to create valid blocks from preexisting edges.
group s1 <slot s2 >
by-edges n1 n2 n3 n4 <keyword>
Create a quadrilateral block from the edge IDs n1 n2 n3 n4. Edges must be given in counterclockwise order.
group s1 <slot s2 >
by-points n1 n2 n3 n4
Create a quadrilateral block from the points with IDs n1 n2 n3 n4. If edges between these points do not already exist, they will be created.
group s1 <slot s2 >
Note
Use of the group logic is described in the Group topic.
delete command
Syntax
extrude block delete <range>
Delete block(s). If <range> is not supplied, all blocks are deleted.
group command
Syntax
extrude block group s <keyword> <range>
Primary keywords:
slot | remove
Assign/remove a group name to blocks. Use of the group logic is described in Group.
slot s2
Designate the slot for the group assignment. If omitted, the slot is set to Default.
remove
Remove the specified group/slot assignment.
id command
Syntax
extrude block id i keyword
Primary keywords:
cycle | group | multiplier | split
Modify a single block by ID.
cycle keyword
Cycle the edge assignments of the block, effectively rotating the orientation of the block in either a counterclockwise or clockwise direction. This useful for
triangular blocks, to change the corner where wedge zones will be created.
counter-clock-wise
Cycle counter-clockwise.
clock-wise
Cycle clockwise.
group s1 <slot s2 > <remove>
Assign the group name s1 in slot s2 (if supplied) to the block. The block is removed from the group/slot if remove is present. The slot is Default if not supplied.
multiplier n
Set the zone multiplier to n.
split <v2 > <tolerance-merge f >
Split the block at v2 (2D coordinate vector). If a location is not provided, then the block will be split at the centroid. If supplied, tolerance-merge specifies the
tolerance for merging points during splitting (that is, when new blocks are created from the split operation, any two points within tolerance-merge will be merged
automatically to one point).
See Also: extrude block position
list command
Syntax
extrude block list keyword <range>
Primary keywords:
extra | group | information | points
Print information about blocks. If <range> is not supplied, information for all blocks is provided.
extra index i
List FISH extra information. A valid integer index i must be supplied.
group
information
Print comprehensive block information. This includes: groups, extras, zone multiplier, number of zones, and edge IDs for each block.
points
Print point IDs for each block.
multiplier command
Syntax
extrude block multiplier i <range>
Set the zone multiplier. This setting applies to all blocks if <range> is not supplied. The zone multiplier is used to multiply by i the number of zones in the area(s) of
interest.
position command
Syntax
extrude block position v2 keyword
Primary keywords:
cycle | group | multiplier | split
Modify a block by position. The block containing point v2 (2D vector coordinates) is modified.
cycle keyword
Cycle the edge assignments of the block, effectively rotating the orientation of the block in either a counterclockwise or clockwise direction. This is mostly useful
for triangular blocks, to change the corner where wedge zones will be created.
counter-clock-wise
Cycle counter-clockwise.
clock-wise
Cycle clockwise.
Assign the group name s1 in slot s2 (if supplied) to the block. The block is removed from the group/slot if remove is present. The slot is Default if not supplied.
multiplier n
Set the zone multiplier to n.
split <tolerance-merge f >
Split the block at v2 (2D coordinate vector). If a location is not provided, then the block will be split at the centroid. If supplied, tolerance-merge specifies the
tolerance for merging points during splitting (that is, when new blocks are created from the split operation, any two points within tolerance-merge will be merged
automatically to one point).
See Also: extrude block id
FISH Functions
FISH functions operating on extrusion blocks. The type specifiers used in the FISH function signatures are given in the FISH Type Index section.
Extrude Block Functions
extrude.block.area(EXT_BLOCK_PNT)
Get the area of a block.
extrude.block.block(EXT_BLOCK_PNT,INT)
Get a block neighbor.
extrude.block.center(EXT_BLOCK_PNT)
extrude.block.check(EXT_BLOCK_PNT)
Get the validity of a block.
extrude.block.countzones(EXT_BLOCK_PNT)
Get the total number of zones in the block.
extrude.block.edge(EXT_BLOCK_PNT,INT)
Get a pointer to a block edge.
extrude.block.flip(EXT_BLOCK_PNT,INT)
Get the "flipped" state of a block edge.
extrude.block.grid.pos(EXT_BLOCK_PNT,INT,INT)
Get a gridpoint position.
extrude.block.multiplier(EXT_BLOCK_PNT)
Get/set the block zone multiplier.
extrude.block.next.block(EXT_BLOCK_PNT,INT)
Get the next block in the list of all blocks...
extrude.block.next.index(EXT_BLOCK_PNT,INT)
Get the index of the next block on the list...
extrude.block.param.pos(EXT_BLOCK_PNT,FLT,FLT)
Get a 2D vector ( |x| , |y| ) position of a parametrized location.
extrude.block.point(EXT_BLOCK_PNT,INT)
Get a point of a block.
extrude.block.size(EXT_BLOCK_PNT)
Get the number of edges of a block.
extrude.block.zones.i(EXT_BLOCK_PNT)
Get number of zones along the local x edge.
extrude.block.zones.j(EXT_BLOCK_PNT)
Get number of zones along the local y edge.
l extrude.block.area
l extrude.block.block
l extrude.block.center
l extrude.block.check
l extrude.block.countzones
l extrude.block.edge
l extrude.block.flip
l extrude.block.grid.pos
l extrude.block.multiplier
l extrude.block.next.block
l extrude.block.next.index
l extrude.block.param.pos
l extrude.block.point
l extrude.block.size
l extrude.block.zones.i
l extrude.block.zones.j
extrude.block.area
Syntax
f = extrude.block.area(bp)
Get the area of a block.
Returns: f - block area

extrude.block.block
Syntax
bpnext = extrude.block.block(bp,i)
Get a block neighbor. The neighbor is the block attached to the source block at the edge with index i. Edge indices on a block start at 1.
Returns: bpnext - neighbor block pointer

Arguments: bp - source block pointer
i - edge index
extrude.block.center
Syntax
v = extrude.block.center(bp)
extrude.block.check
Syntax
i = extrude.block.check(bp)
Get the validity of a block. Possible return values: 1 = valid, 0 = not valid.
extrude.block.countzones
Syntax
i = extrude.block.countzones(bp)
Get the total number of zones in the block.

extrude.block.edge
Syntax
ep = extrude.block.edge(bp,i)
Get a pointer to a block edge. Edge indices on a block start at 1.

i - edge index
extrude.block.flip
Syntax
iflipped = extrude.block.flip(bp,i)
Get the "flipped" state of a block edge. On a flipped edge the edge point order does not coincide with the ascending order of points of the block. Possible return values:
0 = not flipped, 1 = flipped. The block edge indices start with 1 and must not be more than the number of edges for a block (3 = triangle, 4 = quad).
Returns: iflipped - integer

i - block edge index
extrude.block.grid.pos
Syntax
v = extrude.block.grid.pos(bp,ii,ij)
Get a gridpoint position. Returns a 2D vector of the x,y position of indexed gridpoint (i,j). Values of i and j will range between 0 and extrude.block.zones.i and
extrude.block.zones.j, respectively.
ii - index i
ij - index j
extrude.block.multiplier
Syntax
i = extrude.block.multiplier(bp)
extrude.block.multiplier(bp) = i
Get/set the block zone multiplier. See extrude block multiplier.
Returns: i - current zone multiplier

Accepts: i - assigned zone multiplier
Arguments: bp - pointer to the block
extrude.block.next.block
Syntax
bpnext = extrude.block.next.block(bp,index)
Get the next block in the list of all blocks connected to the point attached to block bp at index index. Get the next block on the block list. The block that follows the
source block p on the list is returned.
Returns: bpnext - block pointer to the next block in the list of blocks connected to the point
Arguments: bp - source block pointer
index - index of the point in block bp
extrude.block.next.index
Syntax
p1 = extrude.block.next.index(p,i)
Get the index of the next block on the list of all blocks connected to a point. This returns the next blockblock list. The block that follows the source block p on the list is
returned.
Returns: p1 - next block pointer

Arguments: p - source block pointer
i - block pointer
extrude.block.param.pos
Syntax
m.. include:: /common/docproject/_static/mathroles.txt
v = extrude.block.param.pos(p,fu,fv)
Get a 2D vector (|x|,|y|) position of a parametrized location. u and v are floating point values between 0 and 1.
Returns: v - 2D vector (|x|,|y|) position

Arguments: p - block pointer
fu - first parameter coordinate (u)
fv - second parameter coordinate (v)
extrude.block.point
Syntax
pp = extrude.block.point(bp,i)
Get a point of a block. Point indices start with 1 and must not be more than the number of points for a block (3 = triangle, 4 = quad).

i - block point index
extrude.block.size
Syntax
i = extrude.block.size(bp)
Get the number of edges of a block. This will equal the number of points on the block. Possible return values are: 3 = triangle, 4 = quad.

extrude.block.zones.i
Syntax
i = extrude.block.zones.i(bp)
Get number of zones along the local x edge.
extrude.block.zones.j
Syntax
i = extrude.block.zones.j(bp)
Get number of zones along the local y edge.
Edge
An edge is principally defined by two end points, and by its curvature type, which must be one of: simple (line), polyline, arc, or spline. Types other than simple will be
further defined by control points that lie between the points and give definition to the edge shape.
l Commands
l FISH Functions
Commands
Operations on extrusion edges.
edge commands
extrude edge clear

Clear all zone size and ratio settings on edges.
extrude edge create
Create an edge between two points.
extrude edge delete
Delete edges.
extrude edge group
Assign/remove a group name to edges.
extrude edge id
Modify a single edge by ID.
extrude edge list
Print information about edges.
extrude edge ratio
Set the ratio.
extrude edge ratio-isolate
Set the flag to control ratio propagation.
extrude edge size
Set the number of zones on the edge.
l clear command
l create command
l delete command
l group command
l id command
l list command
l ratio command
l ratio-isolate command
l size command
clear command
Syntax
extrude edge clear
Clear all zone size and ratio settings on edges.
create command
Syntax
extrude edge create by-points i1 i2 <keyword>
Primary keywords:
group | ratio | ratio-isolate | size | type
Create an edge between two points. The edge connects the points with ID i1 and ID i2. If the resulting edge is a diagonal of an existing block, the block is split.
group s1 <slot s2 >
Assign the created edge the group name s1 (in slot s2 if provided, in slot Default if not).
ratio f
Set the ratio f (a number between 0.1 and 10.1), which is used to distribute zone lengths along the edge (each zone will be f of the size of the zone preceding it).
This setting automatically propagates across dependent edges while Ratio-Isolate is false.
ratio-isolate b
Set the flag to control ratio propagation. Ratio settings propagate when false (the default). If set true a ratio assignment on this edge will not propagate to
dependent edges.
size i
Set the number of zones on the edge. This will also automatically propagate across dependent edges and will turn auto-zoning off (see extrude set automatic-
zone).
type keyword
Specify the curve type of the edge.
arc
polyline
simple
This is the default type (a line).
spline
delete command
Syntax
extrude edge delete <invalid> <range>
Delete edges. All edges are deleted if <range> is not supplied. Only edges that not connected to a block will be deleted when invalid is used.
group command
Syntax
extrude edge group s <keyword> <range>
Primary keywords:
slot | remove
Assign/remove a group name to edges. Use of the group logic is described in the Group topic.
slot s2
remove
id command
Syntax
extrude edge id i <keyword>
Primary keywords:
control-point | split | group | ratio | ratio-isolate | size | type
Modify a single edge by ID.
control-point keyword
add <local> v <v ...>
Add one or more control points at locations v, 2D coordinate vector (x,y). If local is used, then the locations are in a coordinate system defined by the edge,
where x goes from end 1 at 0.0 to end 2 at 1.0, and y is normal to that.
clear
Remove all control points.
move i <local> v
Move the control point with index i to location v, 2D coordinate vector (x,y). If local is used, then edge local coordinate system is used. See add above.
remove i 
Remove one or more control points.
split v <block> <tolerance-merge f >
Split the edge at location v, a 2D coordinate vector (x,y). If keyword block is included, the split propagates across blocks, otherwise, deletes the block. If
supplied, tolerance-merge f will be used as the tolerance for merging points during splitting.
Assign the group name s1 in slot s2 (if supplied) to the edge. The edge is removed from the group/slot if remove is present. The slot is Default if not supplied.
ratio f
Set the ratio f (a number between 0.1 and 10.1), which is used to distribute zone lengths along the edge (each zone will be f of the size of the zone preceding it).
ratio-isolate b
Set the flag to control ratio propagation. Ratio settings propagate when false (the default). If set true, a ratio assignment on this edge will not propagate to
dependent edges.
size i
Set the number of zones on the edge. This will also automatically propagate across dependent edges and will turn auto zoning off.
type keyword
Specify the curve type of the edge.
arc
polyline
simple
This is the default type (a line).
spline
list command
Syntax
extrude edge list keyword <range>
Primary keywords:
blocks | extra | group | information | type
Print information about edges. If <range> is not supplied, information for all edges is provided.
blocks
Print blocks IDs for each edge.
extra index i
Print FISH extra information. A valid integer index i must be supplied.
group
information
Print comprehensive edge information, which includes: groups, extras, end points IDs, length, zone size, ratio, ratio isolate flag.
type
Print information about curve type of the edge and control points.
ratio command
Syntax
extrude edge ratio f <range>
Set the ratio. The value f (a number between 0.1 and 10.1) is used to distribute zone lengths along the edge (each zone will be f of the size of the zone preceding it).
ratio-isolate command
Syntax
extrude edge ratio-isolate b <range>
Set the flag to control ratio propagation. Ratio settings propagate when false (the default). If set true, a ratio assignment on this edge will not propagate to dependent
edges.
size command
Syntax
extrude edge size i <range>
Set the number of zones on the edge. This will also automatically propagate across dependent edges and will turn auto-zoning off (see extrude set
automatic-zone). All edges are affected if <range> is not supplied.
FISH Functions
Extrude Edge Functions
extrude.edge.blocked(EXT_EDGE_PNT)
Get block attachment state of an edge.
extrude.edge.center(EXT_EDGE_PNT)
Get the position (2D vector) of an edge midpoint.
extrude.edge.curve(EXT_EDGE_PNT)
Get edge curvature state.
extrude.edge.direction(EXT_EDGE_PNT)
Get the direction of an edge.
extrude.edge.grid.ratio(EXT_EDGE_PNT)
Get/set the ratio setting of an edge.
extrude.edge.grid.ratio.isolate(EXT_EDGE_PNT)
Get/set the ratio-isolate flag.
extrude.edge.grid.size(EXT_EDGE_PNT)
Get/set the zone grid size along an edge.
extrude.edge.gridpos(EXT_EDGE_PNT,INT)
Get the position of a grid point.
extrude.edge.length(EXT_EDGE_PNT)
extrude.edge.next.edge(EXT_EDGE_PNT,INT)
Get the next edge on the edge list.
extrude.edge.next.index(EXT_EDGE_PNT,INT)
Get the index of the next edge on the edge...
extrude.edge.parampos(EXT_EDGE_PNT,FLT)
Get the position of parameterized location v .
extrude.edge.point(EXT_EDGE_PNT,INT)
Get a point of an edge.
extrude.edge.poly.add(EXT_EDGE_PNT,VEC)
Add a control point.
extrude.edge.poly.localu(EXT_EDGE_PNT,INT)
Get/set the local parametric f coordinate of an edge control...
extrude.edge.poly.localv(EXT_EDGE_PNT,INT)
Get/set the local parametric f coordinate of an edge control...
extrude.edge.poly.point(EXT_EDGE_PNT,INT)
Get/set the position of a control point on an edge.
extrude.edge.poly.remove(EXT_EDGE_PNT,INT)
Remove a control point from an edge.
extrude.edge.poly.size(EXT_EDGE_PNT)
Get the number of the control points on an edge.
extrude.edge.simple(EXT_EDGE_PNT)
Get the control point usage of an edge.
extrude.edge.start.block(EXT_EDGE_PNT)
Get the first block on the list of blocks attached...
extrude.edge.start.index(EXT_EDGE_PNT)
Get the index of the first block on the list...
extrude.edge.type(EXT_EDGE_PNT)
Get/set the edge type.
l extrude.edge.blocked
l extrude.edge.center
l extrude.edge.curve
l extrude.edge.direction
l extrude.edge.grid.ratio
l extrude.edge.grid.ratio.isolate
l extrude.edge.grid.size
l extrude.edge.gridpos
l extrude.edge.length
l extrude.edge.next.edge
l extrude.edge.next.index
l extrude.edge.parampos
l extrude.edge.point
l extrude.edge.poly.add
l extrude.edge.poly.localu
l extrude.edge.poly.localv
l extrude.edge.poly.point
l extrude.edge.poly.remove
l extrude.edge.poly.size
l extrude.edge.simple
l extrude.edge.start.block
l extrude.edge.start.index
l extrude.edge.type
extrude.edge.blocked
Syntax
i = extrude.edge.blocked(ep)
Get block attachment state of an edge. Possible return values: 1 = there is at least one block attached to the edge; 0 = no block is attached to the edge.
extrude.edge.center
Syntax
v = extrude.edge.center(ep)
Get the position (2D vector) of an edge midpoint.
Returns: v - edge midpoint

extrude.edge.curve
Syntax
i = extrude.edge.curve(ep)
Get edge curvature state. Possible return values: 1 = the edge is curved; 0 = edge is linear.
extrude.edge.direction
Syntax
v = extrude.edge.direction(ep)
Get the direction of an edge. The return is the 2D vector from point1 to point2 of the edge.
Returns: v - direction of the edge (2D)

extrude.edge.grid.ratio
Syntax
f = extrude.edge.grid.ratio(ep)
extrude.edge.grid.ratio(ep) = f
Get/set the ratio setting of an edge. See extrude edge ratio.
Returns: f - ratio setting

Accepts: f - ratio setting
extrude.edge.grid.ratio.isolate
Syntax
i = extrude.edge.grid.ratio.isolate(ep)
extrude.edge.grid.ratio.isolate(ep) = i
Get/set the ratio-isolate flag. The flag has two possible values: 0 = false (propagation), 1 = true (no propagation). See extrude edge ratio-isolate.
Accepts: i - integer
extrude.edge.grid.size
Syntax
i = extrude.edge.grid.size(ep)
extrude.edge.grid.size(ep) = i
Get/set the zone grid size along an edge.
Returns: i - zone grid size

Accepts: i - zone grid size
extrude.edge.gridpos
Syntax
v = extrude.edge.gridpos(ep,i)
Get the position of a grid point. Returns a position (2D vector). Grid point indices range from 0 to extrude.edge.grid.size.
Returns: v - 2D vector-position of a grid point on the edge

i - grid point index
extrude.edge.length
Syntax
f = extrude.edge.length(ep)
Returns: f - edge length

extrude.edge.next.edge
Syntax
epnext = extrude.edge.next.edge(ep,i)
Get the next edge on the edge list. The edge returned is the one following the source edge on the edge list.
Returns: epnext - next edge pointer

i - edge index
extrude.edge.next.index
Syntax
inext = extrude.edge.next.index(ep,i)
Get the index of the next edge on the edge list. The edge returned is the one following the source edge on the edge list.
Returns: inext - next edge index

i - edge index
extrude.edge.parampos
Syntax
v = extrude.edge.parampos(ep,f)
Get the position of parameterized location v. Returns a 2D vector (x,y). Values of f should range between 0.0 and 1.0.
f - parameter coordinate (float [0,1])
extrude.edge.point
Syntax
pp = extrude.edge.point(ep,i)
Get a point of an edge. The edge endpoint index may be 1 or 2.

i - edge endpoint index
extrude.edge.poly.add
Syntax
void = extrude.edge.poly.add(ep,v)
Add a control point. The point is added at position v. If the edge type is simple line, the edge type will be changed to polyline type.
Returns:
v - 2D vector
extrude.edge.poly.localu
Syntax
f = extrude.edge.poly.localu(ep,i)
extrude.edge.poly.localu(ep,i) = f
Get/set the local parametric f coordinate of an edge control point. Control point indices start at 1.
Returns: f - local parametric coordinate

Accepts: f - local parametric coordinate
extrude.edge.poly.localv
Syntax
f = extrude.edge.poly.localv(ep,i)
extrude.edge.poly.localv(ep,i) = f
Get/set the local parametric f coordinate of an edge control point. Control point indices start at 1.
Returns: f - local parametric coordinate

Accepts: f - local parametric coordinate
extrude.edge.poly.point
Syntax
v = extrude.edge.poly.point(ep,i)
extrude.edge.poly.point(ep,i) = v
Get/set the position of a control point on an edge. Control point indices start at 1.
Returns: v - position (2D vector)

Accepts: v - position (2D vector)
extrude.edge.poly.remove
Syntax
void = extrude.edge.poly.remove(ep,i)
Remove a control point from an edge. Control point indices start at 1.
Returns:
extrude.edge.poly.size
Syntax
i = extrude.edge.poly.size(ep)
Get the number of the control points on an edge.
Returns: i - number of control points

extrude.edge.simple
Syntax
i = extrude.edge.simple(ep)
Get the control point usage of an edge. Possible return values are: 1 = edge is linear, has no control points; 0 = edge has control points.
extrude.edge.start.block
Syntax
b = extrude.edge.start.block(ep)
Get the first block on the list of blocks attached to an edge.
Returns: b - block pointer

extrude.edge.start.index
Syntax
i = extrude.edge.start.index(ep)
Get the index of the first block on the list of blocks attached to an edge. Block indices start at 1.
Returns: i - block index

extrude.edge.type
Syntax
i = extrude.edge.type(ep)
extrude.edge.type(ep) = i
Get/set the edge type. Possible return/assignment values are: 0 = simple, 1 = polyline, 2 = circlearcs, 3 = spline, 4 = ellipse.
Point
A point in an extrusion set is usually an end point (one of two) used to define an edge. They are distinct from control points, which are interior to the points on an edge and
are used to shape the line/curve formed by the edge.
l Commands
l FISH Functions
Commands
Operations on extrusion points.
point commands
extrude point create

Create a point.
extrude point delete
Delete points.
extrude point group
Assign/remove a group name to points.
extrude point id
Modify a single point by ID.
extrude point list
Print information about points.
extrude point transform
Transform points.
l create command
l delete command
l group command
l id command
l list command
l transform command
create command
Syntax
extrude point create v2 keyword
Primary keywords:
merge-tolerance | group
Create a point. The point is created in the supplied position v2 (2D vector coordinates).
merge-tolerance f
The point creation is canceled if there are existing points within a tolerance f from the position.
group s1 <slot s2 >
Assign the created point the group name s1 (in slot s2 if provided, in slot Default if not). Use of the group logic is described in the Group topic.
delete command
Syntax
extrude point delete <invalid> <range>
Delete points. All points are deleted if <range> is not supplied. When invalid is used, only points not connected to an edge will be deleted.
group command
Syntax
extrude point group s <keyword> <range>
Primary keywords:
slot | remove
Assign/remove a group name to points. Use of the group logic is described in the Group topic.
slot s2
remove
id command
Syntax
extrude point id i keyword
Primary keywords:
merge | move-to
Modify a single point by ID.
merge <point> i2
Merge the point with point i2 (point ID positive integer).
move-to v <merge-tolerance f >
Moves the point to location v, 2D coordinate vector (x,y). If supplied, merge-tolerance f will be used as a tolerance for merging points during moving.
list command
Syntax
extrude point list keyword
Primary keywords:
edges | extra | group | information
Print information about points. If <range> is not supplied, information for all points is provided.
edges
Print edge IDs for each point.
extra index i
Print FISH extra information. A valid integer index i must be supplied.
group
information
Print comprehensive point information. This includes: groups, extras, edge IDs, position.
transform command
Syntax
extrude point transform keyword <range>
Primary keywords:
merge-tolerance | origin | rotate | scale | translate | control-point
Transform points. The geometric transformation may be a rotation, move (translation), or scaling, or any combination of the three. If combined, the operations are
performed in the order: scale rotate translate. The scale and rotate operations are always performed with respect to origin. All points are transformed if <range> is not
supplied.
merge-tolerance f <range>
Set the merge tolerance. When supplied, this will be used as tolerance for merging points.
origin v2
Set the origin (point center) of the transformation v2 (2D vector coordinates).
rotate f
Set an angle of rotation f in degrees.
scale f1 <f2 >
Scale the points; f1 = scale factor along the x coordinate, f2 = scale factor along y coordinate.
translate v2
Translate points. Points are moved by v2 (2D vector coordinates).
control-point b
Move/freeze control points. When true (the default), control points are moved when the points they are associated with are moved. Control points will be "frozen"
when false.
FISH Functions
Extrude point Functions
extrude.point.pos(EXT_POINT_PNT)
Get/set the position of a point.
extrude.point.start.edge(EXT_POINT_PNT)
Get the first edge on the list of edges connected...
extrude.point.start.index(EXT_POINT_PNT)
Get the index of the first edge on the list...
l extrude.point.pos
l extrude.point.start.edge
l extrude.point.start.index
extrude.point.pos
Syntax
v = extrude.point.pos(p)
extrude.point.pos(p) = v
Get/set the position of a point.
Returns: v - position (2D vector)

Accepts: v - position (2D vector)
Arguments: p - point pointer
extrude.point.start.edge
Syntax
e = extrude.point.start.edge(p)
Get the first edge on the list of edges connected to a point.
Returns: e - edge pointer

extrude.point.start.index
Syntax
i = extrude.point.start.index(p)
Get the index of the first edge on the list of edges connected to a point.
Returns: i - edge index

Segment
The length and blocking of the extruded dimension in an extrusion set are determined by segments. Zoning in the third dimension is set along segments, similar to the way
that zoning is defined along the edges of blocks.
l Commands
l FISH Functions
Commands
Operations on extrusion segments.
segment commands
extrude segment add

Adds segment(s).
extrude segment clear
Clear all segment data.
extrude segment delete
Delete segment(s).
extrude segment index
Modify a segment by ID.
extrude segment list
List the segments and their values.
extrude segment origin
Set the start position of the first segment.
l add command
l clear command
l delete command
l index command
l list command
l origin command
add command
Syntax
extrude segment add keyword
Primary keywords:
position | number
Adds segment(s).
position f keyword
When specified, an existing segment is split at the location f. If f falls past the end a new segment is added.
group s1 <slot s2 >
Assign the created segment the group name s1 (in slot s2 if provided, in slot Default if not).
node-group s1 <slot s2 >
Assign the created nodes of the segment the group name s1 (in slot s2 if provided, in slot Default if not).
ratio f
Set the ratio f of zone size distribution along the segment.
size i
Set the number of zones i along the segment.
number i keyword
When specified, then i new segments are added onto the end.
group s1 <slot s2 >
Assign the created segment the group name s1 (in slot s2 if provided, in slot Default if not).
length f
Set the segment length f.
Assign the created nodes of the segment the group name s1 (in slot s2 if provided, in slot Default if not).
ratio f
Set the ratio f of zone size distribution along the segment.
size i
Set the number of zones along the segment.
Note
clear command
Syntax
extrude segment clear
Clear all segment data. The number of segments is set to zero.
delete command
Syntax
extrude segment delete i ...
Delete segment(s). Each segment index i given will be deleted, and the remaining segments will be renumbered.
index command
Syntax
extrude segment index i keyword
Primary keywords:
group | length | node-group | position | ratio | size
Modify a segment by ID.
group s1 <slot s2 >
Assign the segment the group name s1 (in slot s2 if provided, in slot Default if not).
length f
Set the segment length f.
Assign nodes of the segment the group name s1 (in slot s2 if provided, in slot Default if not).
position f
Set segment position. Note that segments may be split, deleted, or extended.
ratio f
Set the ratio f of zone size distribution along the segment. This setting defines zone sizes relatively along the segment, where the size of each zone will be f of the
previous zone length. The default value is 1.0 (uniform zones — same length).
size i
Set the number of zones i (integer) along the segment.
Note
list command
Syntax
extrude segment list information
List the segments and their values.
origin command
Syntax
extrude segment origin f
Set the start position of the first segment. The depth value of z for the first segment is set to f; all other segment lengths add to this position.
FISH Functions
Extrude segment Functions
extrude.segment.count(EXT_SET_PNT)
Get the number segments in the extrude set.
extrude.segment.grid.ratio(EXT_SET_PNT,INT)
Get/set ratio setting for the segment grid.
extrude.segment.grid.size(EXT_SET_PNT,INT)
Get/set the number of zones along a segment.
extrude.segment.group(EXT_SET_PNT,INT<,STR>)
Get the group name of a segment.
extrude.segment.isgroup(EXT_SET_PNT,INT,STR<,STR>)
Get segment node's group status.
extrude.segment.length(EXT_SET_PNT,INT)
Get/set the length of a segment.
extrude.segment.node.add(EXT_SET_PNT,FLT)
Add a segment node by position.
extrude.segment.node.delete(EXT_SET_PNT,INT)
Delete a segment (node).
extrude.segment.node.group(EXT_SET_PNT,INT<,STR>)
Get/set segment node group.
extrude.segment.node.isgroup(EXT_SET_PNT,INT,STR)
Remove a segment node group assignment.
extrude.segment.node.pos(EXT_SET_PNT,INT)
Get segment node position.
extrude.segment.node.removegroup(EXT_SET_PNT,INT,STR)
Remove a segment node group assignment.
extrude.segment.removegroup(EXT_SET_PNT,INT,STR)
Remove a segment group assignment.
l extrude.segment.count
l extrude.segment.grid.ratio
l extrude.segment.grid.size
l extrude.segment.group
l extrude.segment.isgroup
l extrude.segment.length
l extrude.segment.node.add
l extrude.segment.node.delete
l extrude.segment.node.group
l extrude.segment.node.isgroup
l extrude.segment.node.pos
l extrude.segment.node.removegroup
l extrude.segment.removegroup
extrude.segment.count
Syntax
i = extrude.segment.count(p)
Get the number segments in the extrude set.
Returns: i - number segments

Arguments: p - extrude set pointer
extrude.segment.grid.ratio
Syntax
f = extrude.segment.grid.ratio(p,i)
extrude.segment.grid.ratio(p,i) = f
Get/set ratio setting for the segment grid. See the ratio keyword of the extrude segment index command.
Returns: f - segment edge ratio

Accepts: f - segment edge ratio
i - segment index
extrude.segment.grid.size
Syntax
i1 = extrude.segment.grid.size(p,i)
extrude.segment.grid.size(p,i) = i1
Get/set the number of zones along a segment.
Returns: i1 - number of zones along segment
Accepts: i1 - number of zones along segment

i - segment index
extrude.segment.group
Syntax
s = extrude.segment.group(p,i<,s1>)
Get the group name of a segment.

i - segment index
s1 - slot name (string, optional)
extrude.segment.isgroup
Syntax
i = extrude.segment.isgroup(p,in,s<,s1>)
Get segment node's group status. Possible return values are: 1 = node is at index in in the given group (and slot, if supplied); 0 = node is not in the group(/slot).
Note that this will travel up the data hierarchy, as described in Group Heirarchies.
in - node segment index
s - group name
s1 - slot name (optional)
extrude.segment.length
Syntax
f = extrude.segment.length(p,i)
extrude.segment.length(p,i) = f
Get/set the length of a segment.
Returns: f - length
Accepts: f - length
i - segment index
extrude.segment.node.add
Syntax
i = extrude.segment.node.add(p,f)
Add a segment node by position. Possible return values are: 1 = success, 0 = failure. An existing segment is split at the location f. If the location falls past the end of the
extrusion's extent, a new segment is added.
f - segment node position
extrude.segment.node.delete
Syntax
= extrude.segment.node.delete(p,i)
Delete a segment (node).
Returns:
Arguments: p - extrude set pointer.
i - segment index
extrude.segment.node.group
Syntax
s = extrude.segment.node.group(p,i<,s1>)
extrude.segment.node.group(p,i<,s1>) = s
Get/set segment node group.
Returns: s - segment node group

Accepts: s - segment node group
i - segment node index
s1 - slot name (optional)
extrude.segment.node.isgroup
Syntax
i1 = extrude.segment.node.isgroup(p,i,s)
Remove a segment node group assignment. Possible return values are: 1 = success, 0 = failure.
Returns: i1 - integer
i - segment node index
s - group name
extrude.segment.node.pos
Syntax
f = extrude.segment.node.pos(p,i)
Get segment node position.
Returns: f - segment node position

i- index
extrude.segment.node.removegroup
Syntax
i1 = extrude.segment.node.removegroup(p,i,s)
Remove a segment node group assignment. Possible return values are: 1 = success, 0 = failure.
i - segment index
s - group name
extrude.segment.removegroup
Syntax
i1 = extrude.segment.removegroup(p,i,s)
Remove a segment group assignment. Possible return values are: 1 = success, 0 = failure.
i - segment index
s - group name
Set
An extrusion set comprises blocks that are used to generated FLAC3D zones. A model may contain multiple sets. At any time, one set is the currently active set in the
program. Operations on the set as a whole (block validation, automatic zoning, deletion, etc.) are performed with set commands.
l Commands
l FISH Functions
Commands
Operations on extrusion sets.
Segment Commands
extrude set automatic-validate

Set off/on automatic validation.
extrude set automatic-zone
Set automatic zoning of the extrusion set.
extrude set delete
Delete an extrude set.
extrude set list
List extrude set information.
extrude set metadata
Manipulate extrude set metadata.
extrude set select
Set the current extrude set.
extrude set system
Set the coordinate system.
l automatic-validate command
l automatic-zone command
l clear command
l delete command
l list command
l metadata command
l select command
l system command
automatic-validate command
Syntax
extrude set automatic-validate b <keyword>
Primary keywords:
tolerance
Set off/on automatic validation. This controls whether or not the program checks for valid geometry during changes. The default is true (on).
tolerance f
The optional tolerance value f changes the tolerance used in this check. The default value is 1e-6.
automatic-zone command
Syntax
extrude set automatic-zone keyword
Primary keywords:
active | direction | edge | size | total
Set automatic zoning of the extrusion set.
active b
If set on, then auto-zoning is continuously reapplied every time a change is made to the model. The default is off.
direction keyword
Control which part(s) of the extrusion are auto-zoned. If not specified, the last value specified is retained (the default is both).
both
Auto-zoning is applied to both the 2D construction data, and the 1D extrude segment data. This is the default.
construction
Auto-zoning is applied to the 2D construction data only.
extrusion
Auto-zoning is applied to the extrude segment data only.
edge f
Auto-zoning will attempt to keep the average length of a zone edge to the value f. If not supplied, the previous value will be used. The default value is 1.0.
size i
Auto-zoning will assign zone sizes so that there are approximately i zones across the largest model dimension. If not supplied, the previous value will be used.
The default value is 100.
total i
Auto zoning will assign zone sizes so that the total number of 3D zones created is approximately (but not more than) i.
clear command
Syntax
delete command
Syntax
extrude set delete <s >
Delete an extrude set. The set named s is deleted if supplied; the current set is deleted if not.
list command
Syntax
extrude set list keyword
Primary keywords:
all | information | metadata | quality
List extrude set information.
all
List all extrude sets.
information
Print detailed information about the current extrude set.
metadata
Print all metadata assigned to the current extrude set.
quality
Print a zone quality report for the current extrude set. This includes the number of zones that, when extruded, may result in "bad geometry" errors.
metadata command
Syntax
extrude set metadata keyword
Primary keywords:
clear | set | list
Manipulate extrude set metadata. Metadata values are keyword/string pairs that can be used to store arbitrary information in the set. They are used by the FLAC3D user
interface to store interface-specific data, for example. The following keywords are available.
clear
Clear all metadata.
set s1 s2
Set the string value s2 to the string key s1 in the extrude set metadata. If a value was already assigned to the key, it is overwritten. Otherwise, a new key/value
pair is created.
list
List all metadata assigned to the extrude set.
select command
Syntax
extrude set select s
Set the current extrude set. If there is not a set named s, a new set with that name is created.
system command
Syntax
extrude set system keyword
Primary keywords:
normal-axis | origin | u-axis | v-axis
Set the coordinate system. These settings affect how extruded object coordinates (u,v,n) map to global coordinates (x,y,z).
normal-axis v
Set the normal axis v (3D vector). This is the direction of extrusion (perpendicular to 2D local x,y).
origin v
Set the origin of the extrusion transformation v (3D vector). When extruded, the 2D extrusion coordinate (0,0) is mapped to (x,y,z) before being rotated into the
u,v,n coordinate system.
u-axis v
Set the u-axis (3D vector v). This axis is the direction of x from the 2D coordinate system when the model is extruded into 3D.
v-axis v
Sets the v-axis (3D vector v). This axis is the direction of y from the 2D coordinate system when the model is extruded into 3D.
FISH Functions
Extrude set Functions
extrude.set.axis.n(EXT_SET_PNT)
Get/set the normal axis.
extrude.set.axis.u(EXT_SET_PNT)
Get/set the u -axis.
extrude.set.axis.v(EXT_SET_PNT)
Get/set the v -axis.
extrude.set.block.create(EXT_SET_PNT,INT,INT,INT<,INT>)
Create a block from points.
extrude.set.block.delete(EXT_SET_PNT,EXT_BLOCK_PNT)
Delete a block.
extrude.set.block.find(EXT_SET_PNT,INT)
Get a block by ID.
extrude.set.block.list(EXT_SET_PNT)
Get a block list pointer.
extrude.set.block.near(EXT_SET_PNT,VEC<,FLT>)
Get the block nearest to a position.
extrude.set.block.size(EXT_SET_PNT)
Get the number of blocks in the extrude set.
extrude.set.create(STR)
Create an extrude set.
extrude.set.delete(EXT_SET_PNT)
extrude.set.edge.create(EXT_SET_PNT,INT,INT)
Create an edge from two points.
extrude.set.edge.delete(EXT_SET_PNT,EXT_EDGE_PNT)
Delete an edge.
extrude.set.edge.find(EXT_SET_PNT,INT)
Get an edge by ID.
extrude.set.edge.list(EXT_SET_PNT)
Get a list of edges.
extrude.set.edge.near(EXT_SET_PNT,VEC<,FLT>)
Get the edge nearest a position.
extrude.set.edge.size(EXT_SET_PNT)
Get number of edges in the extrude set.
extrude.set.find
Get an extrude set by name or ID.
extrude.set.id(EXT_SET_PNT)
Get the ID of an extrude set.
extrude.set.list
Get a list of extrude sets.
extrude.set.metadata.find(EXT_SET_PNT,STR)
Get a metadata value from a metadata key.
extrude.set.metadata.key(EXT_SET_PNT,INT)
Get a metadata key from a metadata vector index.
extrude.set.metadata.size(EXT_SET_PNT)
Get the number of MetaData objects in the Metadata vector.
extrude.set.metadata.value(EXT_SET_PNT,STR)
extrude.set.name(EXT_SET_PNT)
Get the name of an extrude set.
extrude.set.origin(EXT_SET_PNT)
Get/set the origin of the extrusion transformation.
extrude.set.point.create(EXT_SET_PNT,VEC)
Create a point at a position.
extrude.set.point.delete(EXT_SET_PNT,EXT_POINT_PNT)
Delete a point.
extrude.set.point.find(EXT_SET_PNT,INT)
Get a point by ID.
extrude.set.point.list(EXT_SET_PNT)
Get a list of points.
extrude.set.point.near(EXT_SET_PNT,V2<,FLT>)
Get the edge nearest a position.
extrude.set.point.size(EXT_SET_PNT)
Get number of points in the extrude set.
extrude.set.set.un(EXT_SET_PNT,VEC,VEC)
Sets both the u -axis and n -axis (normal axis).
extrude.set.set.uv(EXT_SET_PNT,VEC,VEC)
Sets both the u -axis and v -axis.
extrude.set.set.vn(EXT_SET_PNT,VEC,VEC)
Sets both the v -axis and n -axis (normal axis).
extrude.set.zone.auto(EXT_SET_PNT)
Get/set the flag that controls auto-zoning.
extrude.set.zone.count2(EXT_SET_PNT)
Get the number of 2D zones in the xy plane.
extrude.set.zone.count3(EXT_SET_PNT)
Get the total number of zones.
extrude.set.zone.target.autodir(EXT_SET_PNT)
Get/set the flag for auto-zoning direction.
extrude.set.zone.target.edge(EXT_SET_PNT)
Get/set the auto-zoning edge length.
extrude.set.zone.target.size(EXT_SET_PNT)
Get/set the autozoning size (number of zones).
extrude.set.zone.target.total(EXT_SET_PNT)
Get/set the auto-zoning total (number of zones).
l extrude.set.axis.n
l extrude.set.axis.u
l extrude.set.axis.v
l extrude.set.block.create
l extrude.set.block.delete
l extrude.set.block.find
l extrude.set.block.list
l extrude.set.block.near
l extrude.set.block.size
l extrude.set.create
l extrude.set.delete
l extrude.set.edge.create
l extrude.set.edge.delete
l extrude.set.edge.find
l extrude.set.edge.list
l extrude.set.edge.near
l extrude.set.edge.size
l extrude.set.find
l extrude.set.id
l extrude.set.list
l extrude.set.metadata.find
l extrude.set.metadata.key
l extrude.set.metadata.size
l extrude.set.metadata.value
l extrude.set.name
l extrude.set.origin
l extrude.set.point.create
l extrude.set.point.delete
l extrude.set.point.find
l extrude.set.point.list
l extrude.set.point.near
l extrude.set.point.size
l extrude.set.set.un
l extrude.set.set.uv
l extrude.set.set.vn
l extrude.set.zone.auto
l extrude.set.zone.autodir
l extrude.set.zone.count2
l extrude.set.zone.count3
l extrude.set.zone.target.edge
l extrude.set.zone.target.size
l extrude.set.zone.target.total
extrude.set.axis.n
Syntax
v = extrude.set.axis.n(sp)
extrude.set.axis.n(sp) = v
Get/set the normal axis. This is the direction of extrusion, perpendicular to 2D local x and y.
Returns: v - normal axis (3D vector)

Accepts: v - normal axis (3D vector)
Arguments: sp - extrude set pointer
extrude.set.axis.u
Syntax
v = extrude.set.axis.u(sp)
extrude.set.axis.u(sp) = v
Get/set the u-axis. This axis is the direction of x in the extruder 2D coordinate system when the model is extruded into 3D.
Returns: v - u-axis (3D vector)

Accepts: v - u-axis (3D vector)
extrude.set.axis.v
Syntax
v = extrude.set.axis.v(sp)
extrude.set.axis.v(sp) = v
Get/set the v-axis. This axis is the direction of y in the extruder 2D coordinate system when the model is extruded into 3D.
Returns: v - v-axis (3D vector)

Accepts: v - v-axis (3D vector)
extrude.set.block.create
Syntax
bp = extrude.set.block.create(sp,i1,i2,i3<,i4>)
Create a block from points. Possible inputs are: 3 points = triangle, 4 points = quad. Points may provided by IDs or by pointers.

i1 - first point ID (alternately, point pointer)
i2 - second point ID (alternately, point pointer)
i3 - third point ID (alternately, point pointer)
i4 - fourth point ID (alternately, point pointer)
extrude.set.block.delete
Syntax
void = extrude.set.block.delete(sp,bp)
Delete a block.
Returns: void - void return

Arguments: pp - extrude set pointer
bp - block pointer to delete
extrude.set.block.find
Syntax
bp = extrude.set.block.find(sp,i)
Get a block by ID.

i - ID
extrude.set.block.list
Syntax
l = extrude.set.block.list(sp)
Get a block list pointer.
Returns: l - block list pointer

extrude.set.block.near
Syntax
bp = extrude.set.block.near(sp,v<,f>)
Get the block nearest to a position. Null is returned if no block is found.

v - position (2D vector)
extrude.set.block.size
Syntax
i = extrude.set.block.size(sp)
Get the number of blocks in the extrude set.
Returns: i - number of blocks

extrude.set.create
Syntax
sp = extrude.set.create(s)
Create an extrude set. Returns a pointer to the the created set.
Returns: sp - extrude set pointer

Arguments: s - name of the extrude set
extrude.set.delete
Syntax
void = extrude.set.delete(sp)

Arguments: sp - extrude set pointer.
extrude.set.edge.create
Syntax
ep = extrude.set.edge.create(sp,i1,i2)
Create an edge from two points. The points may be provided by ID or by pointer.
Returns: ep - edge created (pointer)

i1 - first point ID (alternately, point pointer)
i2 - second point ID (alternately, point pointer)
extrude.set.edge.delete
Syntax
void = extrude.set.edge.delete(sp,ep)
Delete an edge.

ep - edge pointer to remove
extrude.set.edge.find
Syntax
ep = extrude.set.edge.find(sp,i)
Get an edge by ID.

i - edge ID
extrude.set.edge.list
Syntax
l = extrude.set.edge.list(sp)
Get a list of edges.
Returns: l - edge list pointer

extrude.set.edge.near
Syntax
ep = extrude.set.edge.near(sp,v<,f>)
Get the edge nearest a position. Returns null if no edge is found.

extrude.set.edge.size
Syntax
i = extrude.set.edge.size(sp)
Get number of edges in the extrude set.
Returns: i - number of edges in the extrude

extrude.set.find
Syntax
sp = extrude.set.find(s:STR or i:INT)
Get an extrude set by name or ID.
Returns: sp - extrude set pointer

Arguments: s - name or i - ID
extrude.set.id
Syntax
i = extrude.set.id(sp)
Get the ID of an extrude set.
Returns: i - extrude set ID

extrude.set.list
Syntax
l = extrude.set.list()
Get a list of extrude sets.
Returns: l - list of extrude sets pointer

Arguments:
extrude.set.metadata.find
Syntax
s1 = extrude.set.metadata.find(sp,s)
Returns: s1 - metadata value

s - metadata key
extrude.set.metadata.key
Syntax
s = extrude.set.metadata.key(sp,i)
Get a metadata key from a metadata vector index.
Returns: s - metadada key

i - metadata vector index
extrude.set.metadata.size
Syntax
i = extrude.set.metadata.size(sp)
Get the number of MetaData objects in the Metadata vector.
Returns: i - number of MetaData objects in the Metadata vector

extrude.set.metadata.value
Syntax
s = extrude.set.metadata.value(sp,s1)
Get a metadata value from a metadata key. In place of s1 an index position in the metadata vector may be supplied.
Returns: s - metadada value

s1 - metadada key
extrude.set.name
Syntax
s = extrude.set.name(sp)
Get the name of an extrude set.
Returns: s - name of the extrude set

extrude.set.origin
Syntax
v = extrude.set.origin(sp)
extrude.set.origin(sp) = v
Get/set the origin of the extrusion transformation. When extruded, the 2D extrusion coordinate (0,0) is mapped to (x,y,z) before being rotated into the u,v,n coordinate
system.
Returns: v - origin of the extrusion transformation (3D vector)

Accepts: v - origin of the extrusion transformation (3D vector)
extrude.set.point.create
Syntax
pp = extrude.set.point.create(sp,v)
Create a point at a position.

extrude.set.point.delete
Syntax
void = extrude.set.point.delete(sp,pp)
Delete a point.

pp - point pointer to remove
extrude.set.point.find
Syntax
pp = extrude.set.point.find(sp,i)
Get a point by ID.

i - ID
extrude.set.point.list
Syntax
lp = extrude.set.point.list(sp)
Get a list of points.
Returns: lp - list of points pointer

extrude.set.point.near
Syntax
pp = extrude.set.point.near(sp,v<,f>)
Get the edge nearest a position. Returns null if no is point found.

extrude.set.point.size
Syntax
i = extrude.set.point.size(sp)
Get number of points in the extrude set.
Returns: i - number of points in the extrude set

extrude.set.set.un
Syntax
void = extrude.set.set.un(sp,v_u,v_n)
Sets both the u-axis and n-axis (normal axis). They correspond to x and z directions in the extruder 2D coordinate system when the model is extruded into 3D.
Returns:
v_u - u-axis (3D vector)
v_n - n-axis (3D vector)
extrude.set.set.uv
Syntax
void = extrude.set.set.uv(sp,v_u,v_V)
Sets both the u-axis and v-axis. They correspond to x and y directions in the extruder 2D coordinate system when the model is extruded into 3D.
Returns:
v_u - u-axis (3D vector)
v_v - v-axis (3D vector)
extrude.set.set.vn
Syntax
void = extrude.set.set.vn(sp,v_v,v_n)
Sets both the v-axis and n-axis (normal axis). They correspond to y and z directions in the extruder 2D coordinate system when the model is extruded into 3D.
Returns:
v1 - v-axis (3D vector)
v2 - n-axis (3D vector)
extrude.set.zone.auto
Syntax
i = extrude.set.zone.auto(sp)
extrude.set.zone.auto(sp) = i
Get/set the flag that controls auto-zoning. See the lkwd:active keyword of extrude set automatic-zone. Possible return/assignment values are: 1 = on, 0 = off.
extrude.set.zone.autodir
Syntax
i = extrude.set.zone.autodir(sp)
extrude.set.zone.target.autodir(sp) = i
Get/set the flag for auto-zoning direction. See the lkwd:direction keyword of extrude set automatic-zone. Possible return/assignment values are: 0 = all (both
directions); 1 = x,y (construction direction); 2 - normal (extrusion direction).
extrude.set.zone.count2
Syntax
i = extrude.set.zone.count2(sp)
Get the number of 2D zones in the xy plane.
Returns: i - number of 2d zones in xy plane

extrude.set.zone.count3
Syntax
i = extrude.set.zone.count3(sp)
Get the total number of zones.
Returns: i - total number of number zones

extrude.set.zone.target.edge
Syntax
f = extrude.set.zone.target.edge(sp)
extrude.set.zone.target.edge(sp) = f
Get/set the auto-zoning edge length. The default is 1.0. See the edge keyword of extrude set automatic-zone.
Returns: f - length
Accepts: f - length
extrude.set.zone.target.size
Syntax
i = extrude.set.zone.target.size(sp)
extrude.set.zone.target.size(sp) = i
Get/set the autozoning size (number of zones). The default is 100. See the size keyword of extrude set automatic-zone.

Accepts: i - number of zones
extrude.set.zone.target.total
Syntax
i = extrude.set.zone.target.total(sp)
extrude.set.zone.target.total(sp) = i
Get/set the auto-zoning total (number of zones). The default is 100. See the total keyword of extrude set automatic-zone.
Returns: i - total zones

Accepts: i - total zones
FISH
FISH is a powerful scripting language that can be used to manipulate model components, parameterize models, control model runs, create/calculate new model outputs,
monitor results, and post-process model runs. See the FISH Scripting Reference for complete information on working with FISH.
Configuration settings and program interaction with FISH in FLAC3D are described here.
l FISH Commands
FISH Commands
FISH Commands
fish automatic-create
Set the FISH symbol automatic creation status.
fish boolean-convert
Convert other types to Boolean values.
fish callback
Add/remove functions to be executed in response to callback events.
fish create
Create a FISH symbol with name s and value a .
fish debug
Launch the FISH function s in debug mode.
fish define
Define a new FISH function.
fish history
Create a history of the FISH variable sym .
fish integer-convert
For FORTRAN-based codes that use index types, indicates whether automatic...
fish list
List FISH -related quantities.
fish results
Set storage of FISH information in results files.
fish set
Assign a FISH symbol.
fish trace
Create a particle trace of the FISH variable sym .
l fish automatic-create command

l fish boolean-convert command
l fish callback command
l fish create command
l fish debug command
l fish define command
l fish history command
l fish integer-convert command
l fish list command
l fish result command
l fish set command
l fish trace command
fish automatic-create command

Syntax
fish automatic-create b
Set the FISH symbol automatic creation status. If true, new global variables are created when unrecognized strings (that are valid possible symbol names) are found
during code interpretation of FISH expressions. Otherwise, all variables must be declared using local and global keywords in FISH. By default, automatic creation is on.
It is recommended that fish automatic-create off be specified if large, complex FISH functions are being written, to prevent errors arising from mistyped variable
names.
fish boolean-convert command

Syntax
fish boolean-convert b
Convert other types to Boolean values. If true, integer, float, pointer and index values can be automatically converted to Boolean values in FISH statements. The default
setting is true.
CS: more info?? How is the conversion done??
fish callback command

Syntax
fish callback keyword
Add/remove functions to be executed in response to callback events.
Note
The whilestepping expression inside a FISH function automatically inserts the FISH function into the cycle sequence at f = -1.0.
The callback mechanism allows for the FISH function sf to be executed at a specific point in the cycle sequence during cycling — at point f in the sequence (if
supplied) or when a specific callback event occurs (see the fish list callbacks command for a list of events).
Three types of events can trigger the execution of a FISH function: 1) model entity creation/deletion; 2) contact model events;[1] and 3) solve termination events. In
cases 1) and 2), values may be returned to sf as arguments, provided that sf takes arguments.
In case 1), the first argument passed to sf is a pointer to the entity that has been created or deleted. In case 2), the arguments depend on the contact model
implementation. [CS: removing the following until it is true] and are detailed in :flag:nomenclature
If the remove keyword is given, then the first instance of sf is removed. [CS: removing the following until it is true] See the :flag:tuto_callbacks for examples of
callback usage.
add sf keyword
Adds a FISH function to be called. When the function is called depends on the following keywords:
f <keyword>
The FISH function will be called every step at the location in the cycle sequence given by f. The following keywords are available to reduce the frequency
of the callback.
interval i
If specified, then the function will only be called every i steps.
process keyword
If specified, then the function will only be called if the process indicated is active during that particular cycle.
creep
The callback will only execute if the creep and mechanical process is active.
dynamic
The callback will only execute if the dynamic and mechanical process is active.
fluid
The callback will only execute if the fluid process is active.
mechanical
The callback will only execute if the mechanical process is active.
thermal
The callback will only execute if the thermal process is active.
event s
The FISH function will be called in response to the event named s.
remove sf <keyword>
Removes a FISH function callback. If no further keywords are specified, the function will be removed wherever it is found.
The first callback found at location f in the cycle is removed. If the function has been entered multiple times only one entry will be removed.
event s
The first callback found associated with the event s is removed. If the function has been entered multiple times only one entry will be removed.
Footnotes
Footnotes
[1] Contact model events are only pertinent in PFC.

fish create command

Syntax
fish create s a
Create a FISH symbol with name s and value a.
This command exists for convenience, but in general it is more flexible and reliable to use inline FISH as follows:
[global fred = vector(1,2,3)]
fish debug command

Syntax
fish debug s keyword
Launch the FISH function s in debug mode. Debugging is discussed FISH Debugging. [CS: given its prevalence in the below, a introduction/definition of the term
pseudo-code (or possibly a glossary entry for it) might be nice]
break keyword ...
This function sets and clears breakpoints in a number of ways. A breakpoint is set in a pseudo-code object, and causes FISH to stop before the object is executed,
and to provide the Debug> prompt. Note that breakpoints only function in debug mode.
clear
Remove all breakpoints from all pseudo-code objects.
code b
Set or clear a breakpoint at a pseudo-code object with ID number i. If i is not specified, then the current pseudo-code object is used.
fish b
Set or clear a breakpoint at the first pseudo-code object in the FISH function.
line on/off
Set or clear a breakpoint at the first pseudo-code object from line i in the current source file. If i is not specified, then the current line is used.
codeinto
Execute a single pseudo-code object. If a function call is made in that object, then execution is stopped at the start of that function.
codeover
Execute a single pseudo-code object, and execution is not stopped if a function call is made in that object.
codeto i
Execute until the pseudo-code object with ID i is about to be executed. If that object is never reached, then the original function call will end, as will the
debugging mode.
lineinto
Execute all pseudo-code objects originating from the current source line, and stop when the next pseudo-code object would have originated from the next line. If a
function call is made, the debugger stops upon entry to that function.
lineover
Execute all pseudo-code objects originating from the current source line, and stop when the next pseudo-code object originates from the next line. It does not stop
if function calls that cause code to be executed in other functions are made.
lineto i
Execute until code originating from the current source file at line i is reached. If that line is never reached, then the original function call will end, as will the
debugging mode.
list keyword ...

call
Output the current call stack. For instance, if function fred calls function george, and execution is halted in function george, the call stack will read:
fred
george
code <i1 > <i2 >
Output the pseudo-code object with ID i1; or if i1 is not specified, output the pseudo-code object that will be executed next. If i2 is specified, the pseudo-
code from i1 to i2 is to be output.
fish
Output the current value of FISH symbol fish. The leading @ symbol is not necessary here, but it will be accepted. If the symbol is a function, it will not be
executed; instead, its current value will be used.
register
Output the current contents of the register. The register is used to store FISH values that are going to be passed as arguments to FISH intrinsics, used for
array access, or passed as arguments to functions.
source <i1 > <i2 >
Output the line from the source file that was used to create the FISH function. If the source file is unavailable, an error will occur. If i1 is not specified, then
the line corresponding to the current execution point is used. If i2 is specified, then lines from i1 to i2 are output.
stack
The current contents of the stack are output. The stack is used to store local variables and arguments during function execution. At present, the names of
stack variables are not available.
run
Continue execution until a breakpoint is reached, or until the original function ends.
fish define command

Syntax
fish define s ...
Define a new FISH function. The function will be named s, and must be a valid symbol name. Tokens following are assumed to be arguments that the function will
take. Please see FISH Scripting Reference and the Tutorial: Working with FISH.
From here until an end statement is found, FISH syntax is expected instead of standard command processing. The FISH code is parsed into a compressed format called
pseudo-code, which is what is executed by the FISH runtime. Compilation errors are reported as the statements are processed.
The pseudo-code is considered part of the model state, and so is cleared on a model new, saved with model save, and recovered with model restore.
The function s will be created as a global symbol if one does not already exist. If it already exists then it will be tagged as a function and the code will be executed
whenever values are retrieved from it. Any function already defined on s will be deleted and overwritten.
Usage Example
The following example illustrates how fish define can be used.
To define a simple FISH function fred that returns a value of 4.5:
fish define fred

fred = 4.5
end
To define a FISH function that takes two arguments and returns the multiplied value
fish define george(a,b)

george = a * b
end
fish history command

Syntax
fish history <name s > sym
Create a history of the FISH variable sym. A name can be assigned for later reference. If not assigned, a name will be generated automatically based on the internally
assigned ID number. The value of the history will be taken at the history interval, the return value is assumed to be a number.
fish integer-convert command

Syntax
fish integer-convert b
For FORTRAN-based codes that use index types, indicates whether automatic conversion of integer types into indices is allowed. The default and strongly
recommended value is false, but this breaks some legacy FISH code. [CS: so presumably, this is for FLAC, UDEC, 3DEC. Say so?]
fish list command

Syntax
fish list keyword
List FISH-related quantities.
arrays
List all FISH arrays that have been created.
basic
A basic list of all global FISH symbols.
callbacks
List the FISH functions that have been added to be executed as callbacks (i.e., with the fish callback command).
callback-list
List the callback events that have been registered. For instance, the solve_complete event is a registered callback event. [CS: is the base list of events shown
anywhere??]
code <s >
List the FISH pseudo-code generated after parsing FISH syntax. If a specific symbol s is provided, only the code for that specific function is listed. Otherwise the
pseudo-code for all functions will be listed.
contents s
For FISH values of an aggregate type (arrays, matrices, structures, maps, etc.) this will list the contents of the type in a structured way.
intrinsics <s >
List the complete set of FISH intrinsics, both built-in and user-defined. If the string s is given, only those intrinsics that contain s in the name will be listed.
memory-items
List of all memory objects allocated. See the FISH function memory.create.
structures
List defined FISH structures, including their member names and values.
symbols
List all FISH symbols.
fish result command

Syntax
fish results active b
Set storage of FISH information in results files. By default this value is off. If set to on, all FISH information is stored, including function code.
fish set command
Syntax
fish set sym a
Assign a FISH symbol. The symbol sym is assigned the value a.
This command exists for convenience, but in general it is more flexible and reliable to use inline FISH as follows:
[ fred = 4.5 ]
fish trace command

Syntax
fish trace <name s > sym
Create a particle trace of the FISH variable sym. See the trace command. A name can be assigned for later reference. If not given, a name will be generated
automatically using the internally assigned ID number.
The FISH symbol is expected to be of vector (v) type. The trace will assume zero velocity for every reading.
Geometry
The geometry system allows the user to create, import and export geometric data. These data can be used to interact with the model in a variety of ways. The data can be used
as a filter with the range logic, and as a visualization aid with plotting. FISH extra variables and group names may be assigned to geometric data. FISH may be used to create
and manipulate the data. The geometric data are organized into geometric sets, which are named collections of nodes, edges and polygons.
Geometry objects do not require a domain for their creation, since they are not model components. The geometry import command is used to import geometric data from a
file that can be of type .stl, .dxf or the Itasca geoemetry format.
l Commands
l FISH Functions
Commands
Operate on geometry objects.
Geometry Commands
geometry assign-groups
This command assigns group names to objects based on their...
geometry copy
Copy geometric data.
geometry delete
Delete geometric sets.
geometry edge create
Create an edge.
geometry edge delete
Delete geometric edges.
geometry edge group
Assign the group s to the edges of the geometric...
geometry export
Export geometry data.
geometry generate
Generate objects with specified shapes.
geometry import
Import geometric data.
geometry list
List geometry information.
geometry node create
Create a node at the position v .
geometry node delete
Delete geometric nodes.
geometry node group
Assign the group s to the nodes of the geometric...
geometry paint-extra
"Paint" a scalar value from a zone field.
geometry polygon create
Create a polygon.
geometry polygon delete
Delete geometric polygons.
geometry polygon group
Assign the group s to the polygons of the geometric...
geometry refine
Refine the triangular or quadrilateral polygons in the geometric set...
geometry rotate
Rotate nodes.
geometry select
Specify the current geometric set (or create a new set...
geometry separate
Separate polygons into sets.
geometry set
Specify the current geometric set (or create a new set...
geometry tessellate
Tessellate nodes.
geometry translate
Translate nodes.
geometry triangulate
Triangulate planar polygons.
l geometry assign-groups command

l geometry copy command
l geometry delete command
l geometry edge create command
l geometry edge delete command
l geometry edge group command
l geometry export command
l geometry generate command
l geometry import command
l geometry list command
l geometry node create command
l geometry node delete command
l geometry node group command
l geometry paint-extra command
l geometry polygon create command
l geometry polygon delete command
l geometry polygon group command
l geometry refine command
l geometry rotate command
l geometry select command
l geometry separate command
l geometry set command
l geometry tessellate command
l geometry translate command
l geometry triangulate command
geometry assign-groups command

Syntax
geometry assign-groups keyword <range>
Primary keywords:
data | structure | zone
This command assigns group names to objects based on their relation to geometric sets. Use of the group logic is described in Group. All polygons in all sets are
assigned a surface number -- polygons that are connected topologically will be assigned the same number. From the position of each object, a ray is projected in the
direction specified by the projection keyword. FLAC3D will count the number of times that ray intersects each surface, and use that information to assign a group name.
For instance, if no surfaces are intersected, then the group name "No Intersections" is assigned. Each different combination of intersections is assigned a capital letter.
For examples, objects that intersect the surface number 2 once and surface number 3 twice might be assigned the letter "D". The group names are assigned to all objects
in the range.
See Geometry Data and Group Assignment for further discussion and examples on the use of this command.
The following keywords are available to select the type of object group names are assigned to:
data keyword
This assigs group names to the set of user-define data based on their location.
scalar keyword [keywordblock]
Assign groups to the user-defined scalar data using a Type Block keyword.
tensor keyword [keywordblock]
Assign groups to the user-defined tensors data using a Type Block keyword.
vector keyword [keywordblock]
Assign groups to the user-defined vectors data using a Type Block keyword.
structure keyword
This assigns group names to structural data (elements, nodes, or links). Elements are checked at their centroids.
beam keyword [keywordblock]
Assign groups to beams using a Type Block keyword.
cable keyword [keywordblock]
Assign groups to cables using a Type Block keyword.
geogrid keyword [keywordblock]
Assign groups to geogrids using a Type Block keyword.
liner keyword [keywordblock]
Assign groups to liners using a Type Block keyword.
link keyword [keywordblock]
Assign groups to links using a Type Block keyword.
node keyword [keywordblock]
Assign groups to nodes using a Type Block keyword.
pile keyword [keywordblock]
Assign groups to piles using a Type Block keyword.
shell keyword [keywordblock]
Assign groups to shells using a Type Block keyword.
zone <grid-point> keyword [keywordblock]
Assign groups to zones (or grid points if the option grid-point keyword is given) using a Type Block keyword.
Repeated Keyword Block
Geometry Assign-Groups Parameters
The following keywords may be used to modify the commands:
projection v
Specifies the direction the projection is made from each location considered. By default this direction is (0,0,1).
set s
Specifies the name of the set to use. More than one set name may be specified. By default, the current selected set is used.
slot i
Specifies the slot that the group names will be assigned in. If not specified the slot name is 'Default'.
geometry copy command

Syntax
geometry copy <source s1 > <target s2 > keyword <range>
Primary keywords:
edges | group | nodes | polygons
Copy geometric data. All geometric data from the source set s1 (or the current default, if not specified) are copied to the target geometric set s2. The target set is created
if it does not exist. The optional range can be used to filter which geometric objects are included in the copy. By default, all nodes, edges and polygons in the range are
copied unless the type to be copied is restricted with a keyword.
edges
If specified, only edges and dependent nodes will be copied.
group s <keyword>
All copied objects will be assigned group name s. Use of the group logic is described in Group. By default, the group name is added to slot Default.
add
Assign s to the next available slot. In this case, slot Default is used.
slot slot
nodes
If specified, only nodes will be copied.
polygons
If specified, only polygons and dependent edges and nodes will be copied.
geometry delete command

Syntax
geometry delete <set s >
Delete geometric sets. All sets are deleted unless a specific set is specified with the set keyword.
geometry edge create command

Syntax
geometry edge create keyword
Primary keywords:
by-node | by-position | by-arc | by-ray
Create an edge. The following keywords are available as different methods of edge creation.
by-node i1 i2 ... <[keywordblock]>
Create one or more edges by giving a series of node ID numbers. At least two ID numbers must be given, to create a single edge. If an edge already exists
connecting those to nodes, no new edge will be created.
by-position v1 v2 ... <[keywordblock]>
Create one or more edges by giving a series of positions. At least two positions must be given, to create a single edge. If an node already exists at that location
within a relative tolerance of 1e-7, then that node will be used instead of creating a new one. If an edge already exists between those two nodes, no new edge will
be created.
by-arc keyword <[keywordblock]>
Create edges describing a circular arc section in space. The arc is described by the locations origin, start, and end. origin defines the center of the arc, and start
defines both the starting direction and the arc radius. The end location defines the plane and sweep angle of the arc but the distance from the origin is ignored. The
arc will be broken into segments linear lengths.
The following keywords control the arc definition:
end v
The end location of the arc, defines the plane of the arc and the total sweep angle. The default end location is (0,0,1).
origin v
The origin of the arc. The default origin is (0,0,0).
segments i
The number of linear segments into which the arc is divided. Each segment will be a single edge, and segments+1 nodes will be created and/or found. The
default number of segments is 10.
start v
The starting position of the arc, and also defins the arc radius. The default start position is (1,0,0).
by-ray keyword <[keywordblock]>
Create edges described by a starting location, a direction, and a distance. The ray may be broken into a number of segments, each of which will be a separate
edge.
The following keywrods control the ray definition:
base v
The base of the ray, from which the edges will project. The default base location is (0,0,0).
direction v
The direction in which the edges will extend from the base. The length is ignored. The default direction is (1,0,0).
length f
The length of the edge(s) that will be generated. The default length is 1.0.
segments i
The number of segments that the ray will be divided into. The default segments is 1.
Keyword Block
The following keywords may be used in any edge creation keyword to add group or extra variable designations to any created edge. Note that created nodes are not
modified, and existing edges that are used instead are also not modofied. The following keywords are available: by-arc, by-node, by-position and by-ray.
Add the group name s using slot slot to all created edges. Use of the group logic is described in Group. If not specified the slot name Default is used. More than
one group keyword may be given.
extra i a
Add the value a to created edges in extra variable index i. More than one extra keyword may be given.
geometry edge delete command

Syntax
geometry edge delete <retain> <range>
Delete geometric edges. All objects that depend on a given object will be deleted. For instance, if a node is deleted, all edges connected to it will be deleted. If an
object's deletion causes data structures to be "orphaned" (i.e., no other objects refer to them), then these objects are automatically deleted as well, unless the retain
keyword is given.
geometry edge group command

Syntax
geometry edge group s <keyword> <range>
Primary keywords:
remove | slot
Assign the group s to the edges of the geometric set that fall within the range. Use of the group logic is described in Group. This command may take the form geometry
edge group "slotname = groupname" — quotation marks required, spaces at equals sign ignored — where slotname is the slot assignment and groupname is the group
name.
remove
Remove s from all edges. If no slot was specified, then the group will be removed from all slots it is found in.
slot slot
geometry export command

Syntax
geometry export s <keyword> <range>
Primary keywords:
binary | edges | format | nodes
Export geometry data. Polygons, as well as required nodes and edges, are output to the file with name s. If the nodes or edges keyword is specified, objects of that type
are included in the search even if they are not connected to polygons. The default file type is the Itasca geometry format, and the range applies to polygons.
binary
Indicate that the binary version of the file format should be used for export. This is not valid with DXF export.
edges
Indicate that free edges (i.e., not connected to any polygon) should be exported as well.
format keyword
Specifiy the file format to use for export. The default will be selected based on the file name extension.
dxf
AutoCAD DXF format with file extension ".dxf."
geometry
Itasca geometry format with file extentsion ".geom." This is the default format, and is described in Geometry Text File Format.
stl
STL format with file extension ".stl." This applies only to polygons, and cannot be used with the nodes or edges keyword.
nodes
Indicate that free nodes (i.e., not connected to any polygon) should be exported as well.
geometry generate command

Syntax
geometry generate keyword ...
Primary keywords:
box | cone | cylinder | disk | from-edges | from-faces | group | sphere
Generate objects with specified shapes. The polygons are created in the current geometry set and, if the optional group keyword is specified, then the group name is
applied to the generated polygons. The shapes include: box, cone, cylinder, disk and sphere.
Note
The group keyword must be given prior to any additional keywords.
box fxmin fxmax fymin fymax fzmin fzmax
Generate a closed box. If fxmin and fxmax are specified alone, then the box is a cube with equal sides.
cone keyword ... (3D only)
Generate a cone in 3D. Either a cone or a conic frustum (i.e., cone with the tip cut off, such as a funnel if the caps are absent) can be generated.
axis v3
Direction of the symmetry axis of the cone pointing from the base position that points in the positive z-direction, by default.
base v3
Position of the base of the cone (i.e., the center of the bottom end) that is the origin, by default.
cap bbottom <btop >
Indicate the inclusion status of the end caps. If one Boolean is specified, then this state is given to both end caps. If two Booleans are specified, then the
first one applies to the bottom cap and the second to the top cap. By default, the bottom cap is created. No top cap is created unless fradtop is specified and
is nonzero.
height fheight
Height of the cone. This is the distance from the base position to the point or, if a frustum, to the center of the top end. By default, fheight = 1.
radius fradbot <fradtop >
Radius of the cone. By default, fradbot = 1.0 and fradtop = 0.0, meaning that a cone is created. If fradtop > 0.0, then a conic frustum (i.e., cone with the tip
cut off) is created. In this case, fradbot is the bottom radius at the base location, and fradtop is the radius of the top of the frustum at a distance fheight from
the base location along the symmetry axis.
resolution fres
Resolution of the edges of the cone ends. The number of end edges is set so that the edge is smaller than fres * fradbot. If a frustum is to be generated with
fradtop > 0, then the end edge lengths are less than fres * min(fradbot, fradtop). By default, fres = 0.1.
cylinder keyword ...
Generate a cylinder in 3D.
axis v3
Direction of the symmetry axis of the cylinder pointing from the base position.
base v3
Position of the base of the cylinder (i.e., the center of the bottom end) that is the origin, by default.
cap bbottom <btop >
Indicate the inclusion status of the end caps. If one Boolean is specified, then this state is given to both end caps. If two Booleans are specified, then the
first one applies to the bottom cap and the second to the top cap. By default, both caps are created.
height fheight
Height of the cylinder. This is the distance from the base position to the center of the top end. By default, fheight = 1.
radius frad
Radius of the cylinder, or the distance from the axis of symmetry to the side.
resolution fres
Resolution of the edges of the cylinder ends. The number of end edges is set so that the edge is smaller than fres * frad. By default, fres = 0.1.
disk keyword ...
Generate a disk in 3D.
dip fdip
Dip angle of the disk in degrees in the range [0,90]. Dip is the angle from the dip direction projected on the xy-plane to the disk surface measured in the
negative z-direction. By default, fdip = 0.
ddir fddir
Dip direction of the disk in degrees, as measured in a clockwise fashion from the positive y-axis in the range [0,360]. By default, fddir = 0.
position v3
Position of the center of the disk that is the origin, by default.
radius frad
Radius of the disk that is 1.0, by default.
resolution fres
Resolution of the disk edges. The number of disk edges is set so that the edge is smaller than fres * frad. By default, fres = 0.1.
from-edges keyword ... <range>
Generate polygons by extruding from all edges in the range. The edges must be in the same set. All edges matching the range given are selected.
The following keywords are available:
extrude v
The direction and length to extrude from the given edges. The default value is (0,0,1).
segments i
The number of segments to divide the extruded direction into. The default value is 1.
from-faces keyword ... <range>
Generate polygons from the list of all zone faces in the range. By default only mechanical surface faces are considered.
internal
Internal as well as external faces will be considered.
fluid
Specifies that the null state of the fluid constitutive model will be considered in determining a surface.
Assigns the group name to all polygons created.
mechanical
Specifies that the null state of the mechanical constitutive model will be considered in determining a surface. This is the default state. If thermal or fluid is
specified then mechanical will be removed unless it is specified as well.
or
If more than one instance of mechanical, thermal, or fluid are given then the default behavior is to require that all of them be null for it to be considered a
null zone. If this keyword is given then if any of then are null it will be considered a null zone.
split-nonplanar b
By default, quadrilateral faces that are non-planar are split into two triangular polygons. By setting split-nonplanar to false, the polygons will remain non-
planar quadrilaterals. Be aware that non-planar polygons can cause errors when performing geometry operations.
thermal
Specifies that the null state of the thermal constitutive model will be considered in determining a surface.
group s keyword ...
Specify that the created polygons are given the group name s. Use of the group logic is described in Group. If the slot keyword is not specified, then the group
name is assigned to the slot Default.
slot slot
Set the group slot slot to s. By default, the slot Default is assigned.
sphere keyword ...
Generate a closed sphere in 3D. The sphere is generated by refining an icosahedron (i.e., a sphere composed of 20 identical equilateral triangles) so that the edge
lengths are smaller than a length defined by the resolution keyword.
position v3
Position of the sphere centroid that is the origin, by default.
radius frad
Radius of the sphere that is 1.0, by default.
resolution fres
Resolution of the edges. The number of edges is set so that the edge length is smaller than fres * frad. By default, fres = 0.1.
geometry import command

Syntax
geometry import s <keyword>
Primary keywords:
format | group | merge | set
Import geometric data. s is the file name.
format keyword
The importer will attempt to infer the proper format from the contents of the file, but the format keyword can be used to force it to interpret the file as a given
format. The following formats are available:
dxf
DXF file (.dxf). This is a partial implementation of the format as of AutoCAD version 12. Layer names are assigned to group slot 1.
geometry
Itasca geometry file format geometry file (.geom). Binary or text version is determined automatically (described in Geometry Text File Format and
Geometry Binary File Format.
stl
STL file (.stl). Solid names are assigned to group slot 1. Binary or text version is determined automatically.
group s <keyword>
Specify group names to imported geometry objects. Use of the group logic is described in Group.
add
Assign s to the next available slot.
slot slot
merge b
By default, the STL format will search for and merge nodes and edges that are in the same location in space, within a default tolerance. Using this keyword will
stop this process, speeding up the import but increasing the amount of data imported.
set s
By default, the imported geometry is assigned to a set with a name that is identical to the imported file name without extension. This can be overridden with the
set keyword.
geometry list command

Syntax
geometry list keyword <range>
Primary keywords:
information | nodes | edges | polygons | blocks
List geometry information.
information
List of all information.
nodes
List of node information.
edges
List of edge information.
polygons
List of polygon information.
blocks
List of block information.
geometry node create command

Syntax
geometry node create v <keyword>
Primary keywords:
extra | group
Create a node at the position v.
extra i a
group s1 <slot s2 >
Optionally assign the group name s1 to slot s2.
geometry node delete command

Syntax
geometry node delete <retain> <range>
Delete geometric nodes. All objects that depend on a given object will be deleted. For instance, if a node is deleted, all edges connected to it will be deleted. If an
keyword is given.
geometry node group command

Syntax
geometry node group s <keyword> <range>
Primary keywords:
remove | slot
Assign the group s to the nodes of the geometric set that fall within the range. Use of the group logic is described in Group. This command may take the form geometry
node group "slotname = groupname" — quotation marks required, spaces at equals sign ignored — where slotname is the slot assignment and groupname is the group
name.
remove
Remove s from all nodes. If no slot was specified, then the group will be removed from all slots it is found in.
slot slot
geometry paint-extra command

Syntax
geometry paint-extra i keyword <range>
Primary keywords:
acceleration | acceleration-x | acceleration-y | acceleration-z | condition | density | displacement | displacement-x | displacement-y | displacement-z | extra | pore-pressure
| property | property-fluid | property-thermal | ratio-local | saturation | strain-increment | strain-rate | stress | stress-strength-ratio | stress-effective | temperature | timestep-
dynamic | unbalanced-force | unbalanced-force-x | unbalanced-force-y | unbalanced-force-z | velocity | velocity-x | velocity-y | velocity-z
"Paint" a scalar value from a zone field. The value is painted onto nodes in the current geometric set. The values are placed in the extra variable index i on each node.
The range selects which nodes of the geometric set are painted.
If the value is gridpoint-based, then a value at the node location is calculated using a weighting function inside the zone.
If the value is zone-based, the value will be determined by a curve-fitting algorithm extrapolated to the node location. Which algorithm is used can be specified in the
following [keywordblock]. By default a value is considered constant within a zone.
Note that if the need for "painting" is temporary (i.e., for visualization), this can be done on a geometry plot item when plotting — which bypasses the command and the
overhead it requires to store the field values at gridpoints. CS: this should have a link to a topic that describes how to do that
acceleration [keywordblock]
Paint acceleration magnitude at the gridpoint (only available if model configure dynamic has been specified).
acceleration-x [keywordblock]
Paint x-acceleration at the gridpoint (only available if model configure dynamic has been specified).
acceleration-y [keywordblock]
Paint y-acceleration at the gridpoint (only available if model configure dynamic has been specified).
acceleration-z [keywordblock]
Paint z-acceleration at the gridpoint (only available if model configure dynamic has been specified).
condition [keywordblock]
Paint a measure of how badly deformed a zone is. [URGENT: CS: content required for link here appears to need adding to doc set: Link to wherever the contents
of section 1.1.5 in the Command Reference end up
density [keywordblock]
Paint the density of the zone.
displacement [keywordblock]
Paint displacement magnitude at the gridpoint.
displacement-x [keywordblock]
Paint x-displacement at the gridpoint.
displacement-y [keywordblock]
Paint y-displacement at the gridpoint.
displacement-z [keywordblock]
Paint z-displacement at the gridpoint.
extra [keywordblock]
Paint an 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 zone 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 [keywordblock]
Paint pore pressure in a zone. By default this will be the average zone pore pressure, but the gridpoint pressure can be specified by using the source keyword
modifier.
property [keywordblock]
Paint 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 [keywordblock]
Paint 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 [keywordblock]
Paint 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
ratio-local [keywordblock]
Paint 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.
saturation [keywordblock]
Paint the saturation at the gridpoint (only available if model configure fluid has been specified).
strain-increment [keywordblock]
Paint 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 [keywordblock]
Paint 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 [keywordblock]
Paint 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 [keywordblock]
Paint 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 [keywordblock]
Paint 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 [keywordblock]
Paint the temperature at the gridpoints. The source modifier keyword can be used to specify that zone based temperature should be used instead.
timestep-dynamic [keywordblock]
Paint the local critical dynamic time step of that particular gridpoint. (only available if model configure dynamic has been specified).
unbalanced-force [keywordblock]
Paint the unbalanced force magnitude at the gridpoint.
unbalanced-force-x [keywordblock]
Paint the x-unbalanced force at the gridpoint.
unbalanced-force-y [keywordblock]
Paint the y-unbalanced force at the gridpoint.
unbalanced-force-z [keywordblock]
Paint the z-unbalanced force at the gridpoint.
velocity [keywordblock]
Paint the velocity magnitude at the gridpoint.
velocity-x [keywordblock]
Paint the x-velocity at the gridpoint.
velocity-y [keywordblock]
Paint the y-velocity at the gridpoint.
velocity-z [keywordblock]
Paint the z-velocity at the gridpoint.
Keyword Block
Zone Field Modifiers
The following modifiers are available to specify addition information for the geometry paint-extra keywords. The following keywords are available.
acceleration, acceleration-x, acceleration-y, acceleration-z, condition, density, displacement, displacement-x, displacement-y,
displacement-z, extra, pore-pressure, property, property-fluid, property-thermal, ratio-local, saturation, strain-increment, strain-rate,
stress, stress-effective, stress-strength-ratio, temperature, timestep-dynamic, unbalanced-force, unbalanced-force-x, unbalanced-force-y,
unbalanced-force-z, 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 vector, this setting is
ignored. The available options are:
Get the x-component of the vector.
Get the y-component of the vector
Get the z-component of the vector
magnitude
Get the 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.
label s
Assign 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 a 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
Specify the power of the distance used to weight values. The default power is 3.0.
radius-ratio f
Specify 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 >
Use 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.
null
Specify the criteria used to ignore zone values. By default mechanical null zones are ignored.
fluid b
Zones with a null fluid constitutive model are also ignored if this is set to on.
mechanical b
Zones with a null mechanical constitutive model are ignored if this is set to on (this is the default).
thermal b
Zones with a null thermal constitutive model are ignored if this is set to on.
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
intermediate
Get the intermediate principal stress.
maximum
Get the maximum (most positive) value of principal stress. Note that in FLAC3D compressive stresses are negative.
mean
Get 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
Get the minimum (most negative) principal stress. Note that in FLAC3D compressive stresses are negative.
norm
Get the norm of the strain rate; see the equation in Zone Field Data Names.
octahedral
Get octahedral stress; see the equation in Zone Field Data Names.
shear-maximum
Get the maximum shear stress.
total-measure
Get the distance of tensor value to the origin in principal space.
volumetric
Get the volumetric change, or trace.
von-mises
Get the Von Mises measure; see the equation in Zone Field Data Names.
xx
Get the xx-component of the tensor.
xy
Get the xy-component of the tensor.
xz
Get the xz-component of the tensor.
yy
Get the yy-component of the tensor.
yz
Get the yz-component of the tensor.
zz
Get the 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
Values are retrieved from the 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, 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
Set type to scalar float. This is the default.
vector
Set type to vector.
tensor
Set type to tensor.
geometry polygon create command

Syntax
geometry polygon create keyword
Primary keywords:
by-edges | by-nodes | by-positions
Create a polygon. A list of edges, a list of nodes or a list of points in space can be input. If an edge list is used, the edges must be given in order and form a closed
polygon. If a node list is used, edges are created if none are found, and the polygon is automatically closed. If a position list is used, nodes and edges are created if none
are found, and the polygon is automatically closed. A warning results if the polygon is not planar or is not convex. If an extrude vector is provided, then the polygon
will be extruded along that vector, resulting in a closed volume of polygonal surfaces.
by-edges i1 i2 <keyword> [keywordblock]
List of edge IDs that belong to the polygon. The IDs must be ordered such that the edges form a closed polygon. The Repeat Block keywords may optionally be
specified.
by-nodes i1 i2 <keyword> [keywordblock]
List of node IDs that belong to the polygon. Edges are created if none are found, and the polygon is automatically closed. The Repeat Block keywords may
optionally be specified.
by-positions v1 v2 <keyword> [keywordblock]
List of nodal positions that belong to the polygon. Nodes and edges are created if none are found, and the polygon is automatically closed. The Repeat Block
keywords may optionally be specified.
Repeated Keyword Block
Geometry Polygon Create Parameters
The following keywords may be used to modify the commands: by-edges, by-nodes and by-positions.
extrude v
will create polygon and "extrude" in the direction supplied.
extra i a
group s1 <slot s2 >
Optionally assign the group name s1 to slot s2 (optional).
geometry polygon delete command

Syntax
geometry polygon delete <retain> <range>
Delete geometric polygons. All objects that depend on a given object will be deleted. For instance, if a node is deleted, all edges connected to it will be deleted. If an
keyword is given.
geometry polygon group command

Syntax
geometry polygon group s <keyword> <range>
Primary keywords:
remove | slot
Assign the group s to the polygons of the geometric set that fall within the range. Use of the group logic is described in Group. This command may take the form
geometry polygon group "slotname = groupname" — quotation marks required, spaces at equals sign ignored — where slotname is the slot assignment and
groupname is the group name.
remove
Remove s from all polygons. If no slot was specified, then the group will be removed from all slots it is found in.
slot slot
geometry refine command

Syntax
geometry refine <range>
Refine the triangular or quadrilateral polygons in the geometric set into smaller versions.
A very simple refinment of the geometry data is performed. Each triangle in the set is replaced by four smaller triangles by adding a new node to the midpoint of each
edge. Each quadrilateral is replaced by four smaller quadrilaterals by adding a new node to the midpoint of each edge and an additional node to the centroid.
The optional index i allows multiple levels of refinement to be specified. The default level is 1. If more than one is specified, then the refinement is done recursively.
Only a maximum of 4 levels may be applied at once -- a very large number of polyons may be created very quickly even then.
geometry rotate command

Syntax
geometry rotate keyword <range>
Primary keywords:
angle | axis | origin
Rotate nodes. The optional range is applied to nodes, and they are rotated via the right-hand rule about a specified axis that passes through a specified point.
angle f
Angle of rotation in degrees.
axis v
Axis of rotation about which to rotate following the right-hand rule.
origin v
Point to rotate about.
geometry select command

Syntax
geometry select s
Specify the current geometric set (or create a new set named s and make it the current set, if one with that name does not exist). All nodes, edges and polygons are
contained inside a geometric set. These sets may be referred to by ID number or by a string name. If never specified, the set is named Default. This is a synonym for the
geometry set command.
geometry separate command

Syntax
geometry separate <name s > keyword <range>
Primary keywords:
by-closed-volume | by-connected | by-group
Separate polygons into sets. Individual sets are created out of each group of polygons that fit the desired separation criteria. For instance, a geometry set containing two
polygons are split into two separate geometry sets. The geometry set names will be s with an integer count appended (e.g., if s = fred, then one set will be named fred1
and the other will be fred2). If the name keyword is not given, then the current set name is used.
The following separation criteria are supported:
by-closed-volume
Attempts to separate polygons into collections that form closed watertight volumes.
by-connected
Separates polygons into collections that are connected across edges.
by-group
Separates polygons into collections sharing the same group name. Note that polygons may end up in multiple sets if they share group names in multiple slots.
geometry set command

Syntax
geometry set s
Specify the current geometric set (or create a new set named s and make it the current set, if one with that name does not exist). All nodes, edges and polygons are
contained inside a geometric set. These sets may be referred to by ID number or by a string name. If never specified, the set is named Default. This is a synonym for the
geometry select command.
geometry tessellate command

Syntax
geometry tessellate keyword <range>
Primary keywords:
convex-hull | delaunay | start-set | to-set | voronoi
Tessellate nodes. The nodes are tessellated in the current geometry set using the Qhull (http://www.qhull.org) package. Polygons are created in the current set, by
default. See the to-set and start-set keywords to output polygons to different geometry sets.
convex-hull
Calculate the convex hull of the nodes in the current geometry set. This keyword is not compatible with the start-set.
delaunay
Calculate the Delaunay simplices of the nodes of the current geometry set.
start-set s
Each Delaunay simplex or Voronoi region is placed in a unique set. Each set name is a combination of s with the ID of the set post-pended to s. For example, the
set with ID = 13 with s = con would have name con13. This keyword cannot be used with the convexhull keyword.
to-set s
Place the resulting polygons in the set with name s. This set is created if it does not exist.
voronoi
Calculate the Voronoi regions of the nodes in the current geometry set.
Note
Voronoi regions with points at infinity are skipped when producing the output.
geometry translate command

Syntax
geometry translate v <range>
Translate nodes. The node positions are translated by v, and the optional range is applied to nodes.
geometry triangulate command

Syntax
geometry triangulate keyword <range>
Primary keywords:
clean | to-set
Triangulate planar polygons. The planar polygons in the current geometry set are triangulated. This may be useful for plotting polygons that have concavities. Polygons,
that are triangles, are created in the current set by default. See the to-set keyword to output the polygons to different geometry sets.
clean
Delete the polygons that have been triangulated.
to-set s
Place the resulting polygons in the set with name s. This set is created if it does not exist.
FISH Functions
l Geometry Set Utilities

l Geometry Set Intrinsics
l Geometry Polygon Utilities
l Geometry Polygon Intrinsics
l Geometry Edge Utilities
l Geometry Edge Intrinsics
l Geometry Node Utilities
l Geometry Node Intrinsics
Geometry Set Utilities
geom.set.find(INT/STR)
Find a geometry set.
geom.set.list
Get the global geometry set list.
geom.set.maxid
Get the maximum geometry set ID.
geom.set.num
Get the number of geometry sets.
geom.set.typeid
Get the geometry set type number.
Geometry Set Intrinsics
geom.set.closest(GSET_PNT,VEC<,FLT>)
Get closest node coordinate vector from the position supplied .
geom.set.create(STR)
Create a geometry set.
geom.set.delete(GSET_PNT)
Delete a geometry set.
geom.set.edge.maxid(GSET_PNT)
Get the maximum edge ID.
geom.set.edge.num(GSET_PNT)
geom.set.id(GSET_PNT)
Get the geometry set ID.
geom.set.name(GSET_PNT)
Get the geometry set name.
geom.set.node.maxid(GSET_PNT)
Get the maximum node ID.
geom.set.node.num(GSET_PNT)
Get/set the number of nodes.
geom.set.poly.maxid(GSET_PNT)
Get the maximum polygon ID.
geom.set.poly.num(GSET_PNT)
Get the number of polygons.
geom.set.remove(GSET_PNT)
Delete a geometry set.
Geometry Polygon Utilities
geom.poly.find(GSET_PNT,INT)
Find a polygon.
geom.poly.list(GSET_PNT)
Get the polygon list of a geometry set.
geom.poly.near(GSET_PNT,VEC<,FLT>)
Find the closest polygon to a point.
geom.poly.typeid
Get the polygon type number.
Geometry Polygon Intrinsics
geom.poly.add.edge(GPOL_PNT,GE_PNT)
Add an edge to a polygon.
geom.poly.add.node(GSET_PNT,GPOL_PNT<,GN_PNT><,VEC><,INT>)
Add an edge via a node addition.
geom.poly.area(GPOL_PNT)
Get the polygon area.
geom.poly.check(GPOL_PNT)
Get the validity status.
geom.poly.close(GSET_PNT,GPOL_PNT)
Close a polygon.
geom.poly.create(GSET_PNT)
Create a polygon.
geom.poly.delete(GSET_PNT,GPOL_PNT)
Delete a polygon.
geom.poly.edge(GPOL_PNT,INT)
Get a polygon edge.
geom.poly.extra(GPOL_PNT,INT)
Get/set polygon extra variable.
geom.poly.group(GPOL_PNT<,STR>)
Get/set polygon groups.
geom.poly.group.remove(GPOL_PNT,STR)
Remove polygon groups.
geom.poly.id(GPOL_PNT)
Get the polygon ID.
geom.poly.isgroup(GPOL_PNT,STR<,STR>)
geom.poly.next.index(GPOL_PNT,INT)
Get the index of the next edge of a polygon.
geom.poly.next.poly(GPOL_PNT,INT)
Get the next polygon connected to an edge.
geom.poly.node(GPOL_PNT,INT)
Get a node.
geom.poly.normal(GPOL_PNT<,INT>)
Get the polygon normal.
geom.poly.pos(GPOL_PNT<,INT>)
Get the polygon position.
geom.poly.remove(GSET_PNT,GPOL_PNT)
Delete a polygon.
geom.poly.size(GPOL_PNT)
Geometry Edge Utilities
geom.edge.find(GSET_PNT,INT)
Find an edge.
geom.edge.list(GSET_PNT)
Get the edge list of a geometry set.
geom.edge.near(GSET_PNT,VEC<,FLT>)
Find the closest edge to a point.
geom.edge.typeid
Get the edge type number.
Geometry Edge Intrinsics
geom.edge.create(GSET_PNT,INT/GN_PNT,INT/GN_PNT)
Create an edge.
geom.edge.delete(GSET_PNT,GE_PNT)
Delete an edge.
geom.edge.dir(GE_PNT<,INT>)
Get the edge direction.
geom.edge.extra(GE_PNT,INT)
Get/set edge extra variable.
geom.edge.group(GE_PNT<,STR>)
Get/set edge groups.
geom.edge.group.remove(GE_PNT,STR)
Remove edge groups.
geom.edge.id(GE_PNT)
Get the edge ID.
geom.edge.isgroup(GE_PNT,STR<,STR>)
geom.edge.next.edge(GE_PNT,INT)
Get the edge connected to a node.
geom.edge.next.index(GE_PNT,INT)
Get the edge index connected to a node.
geom.edge.node(GE_PNT,INT)
Get an edge node.
geom.edge.node.pos(GE_PNT,INT<,INT>)
Get/set the node position.
geom.edge.pos(GE_PNT<,INT>)
Get the edge position.
geom.edge.remove(GSET_PNT,GE_PNT)
Delete an edge.
geom.edge.start.index(GE_PNT)
Index of the first polygon attached to an edge.
geom.edge.start.poly(GE_PNT)
Get the first polygon attached to an edge.
Geometry Node Utilities
geom.node.find(GSET_PNT,INT)
Find a node.
geom.node.list(GSET_PNT)
Get the node list of a geometry set.
geom.node.near(GSET_PNT,VEC<,FLT>)
Find the closest node to a point.
geom.node.typeid
Get the node type number.
Geometry Node Intrinsics
geom.node.create(GSET_PNT,VEC)
Create a node.
geom.node.delete(GSET_PNT,GN_PNT)
Delete a node.
geom.node.extra(GN_PNT,INT)
Get/set node extra variable.
geom.node.group(GN_PNT<,STR>)
Get/set node groups.
geom.node.group.remove(GN_PNT,STR)
Remove node groups.
geom.node.id(GN_PNT)
Get the node ID.
geom.node.isgroup(GN_PNT,STR<,STR>)
geom.node.pos(GN_PNT<,INT>)
geom.node.remove(GSET_PNT,GN_PNT)
Delete a node.
geom.node.start.edge(GN_PNT)
Get the first edge connected to a node.
geom.node.start.index(GN_PNT)
Index of the first edge connected to a node.
l geom.edge.create
l geom.edge.delete
l geom.edge.dir
l geom.edge.extra
l geom.edge.find
l geom.edge.group
l geom.edge.group.remove
l geom.edge.id
l geom.edge.isgroup
l geom.edge.list
l geom.edge.near
l geom.edge.next.edge
l geom.edge.next.index
l geom.edge.node
l geom.edge.node.pos
l geom.edge.pos
l geom.edge.remove
l geom.edge.start.index
l geom.edge.start.poly
l geom.edge.typeid
l geom.node.create
l geom.node.delete
l geom.node.extra
l geom.node.find
l geom.node.group
l geom.node.group.remove
l geom.node.id
l geom.node.isgroup
l geom.node.list
l geom.node.near
l geom.node.pos
l geom.node.remove
l geom.node.start.edge
l geom.node.start.index
l geom.node.typeid
l geom.poly.add.edge
l geom.poly.add.node
l geom.poly.area
l geom.poly.check
l geom.poly.close
l geom.poly.create
l geom.poly.delete
l geom.poly.edge
l geom.poly.extra
l geom.poly.find
l geom.poly.group
l geom.poly.group.remove
l geom.poly.id
l geom.poly.isgroup
l geom.poly.list
l geom.poly.near
l geom.poly.next.index
l geom.poly.next.poly
l geom.poly.node
l geom.poly.normal
l geom.poly.pos
l geom.poly.remove
l geom.poly.size
l geom.poly.typeid
l geom.set.closest
l geom.set.create
l geom.set.delete
l geom.set.edge.maxid
l geom.set.edge.num
l geom.set.find
l geom.set.id
l geom.set.list
l geom.set.maxid
l geom.set.name
l geom.set.node.maxid
l geom.set.node.num
l geom.set.num
l geom.set.poly.maxid
l geom.set.poly.num
l geom.set.remove
l geom.set.typeid
geom.edge.create
Syntax
e = geom.edge.create(g,n1,n2)
Create an edge. The nodes can either be specified by their IDs or as node pointers. The nodes must already exist.

Arguments: g - geometry set pointer
n1 - ID or node pointer of node 1
n2 - ID or node pointer of node 2
geom.edge.delete
Syntax
v = geom.edge.delete(g,e)
Delete an edge. Any object (e.g., a polygon) connected to the edge is also deleted.

e - edge pointer
geom.edge.dir
Syntax
Vector Access
v = geom.edge.dir(e<,i>)
Get the edge direction. The edge direction is defined from node 1 to node 2.
Returns: v - direction vector or component

Arguments: e - edge pointer
Component Access
f = geom.edge.dir.x(e)
Get the x-component of the edge direction.
Returns: f - x-component of the direction vector

f = geom.edge.dir.y(e)
Get the y-component of the edge direction.
Returns: f - y-component of the direction vector

f = geom.edge.dir.z(e) (3D only)
Get the z-component of the edge direction.
Returns: f - z-component of the direction vector

geom.edge.extra
Syntax
a = geom.edge.extra(e,i)
geom.edge.extra(e,i) = a
Get/set edge extra variable.

i - extra index
geom.edge.find
Syntax
e = geom.edge.find(g,id)
Find an edge.

Argument: g - geometry set pointer
id - edge ID
geom.edge.group
Syntax
s = geom.edge.group(e<,slot>)
geom.edge.group(e<,slot>) = s
Get/set edge groups. Use of the group logic is described in Group.

geom.edge.group.remove
Syntax
br = geom.edge.group.remove(e,s)
Remove edge groups. The specified group name is removed from all group slots.
Returns: br - success indicator

s - group name
geom.edge.id
Syntax
i = geom.edge.id(e)
Get the edge ID.
Returns: i - edge ID
geom.edge.isgroup
Syntax
b = geom.edge.isgroup(e,s<,slot>)
Query the existence of a group. If slot is not provided then all slots are queried.

s - group name
geom.edge.list
Syntax
l = geom.edge.list(g)
Get the edge list of a geometry set. Use the loop foreach construct to iterate through the list.
Returns: l - edge list

geom.edge.near
Syntax
e = geom.edge.near(g,v<,f>)
Find the closest edge to a point. If f is specified, then the search radius is limited.

v - position
geom.edge.next.edge
Syntax
er = geom.edge.next.edge(e,i)
Get the edge connected to a node. The node is specified by the index i with 1 i 2. This can be used to iterate through all edges connected to a node with the
geom.edge.next.index function.
Returns: er - edge pointer

i - node index with 1 i 2
Usage Example
The following example illustrates how geom.edge.next.edge can be used to iterate through all edges attached to a node, counting the number of edges.
Was this topic helpful? Let us know...
geom.edge.next.index
Syntax
ir = geom.edge.next.index(e,i)
Get the edge index connected to a node. The node is specified by the index i with 1 i 2. This can be used to iterate through all edges connected to a node with the
geom.edge.next.edge function.
Returns: ir - edge index

i - node index with 1 i 2
Usage Example
The following example illustrates how geom.edge.next.index can be used to iterate through all edges attached to a node, counting the number of edges.
; Test node to edge loop

global test23 = 0
local node_pnt = geom.node.find(setpnt,1)
local edge_pnt = geom.node.start.edge(node_pnt)
local edge_ind = geom.node.start.index(node_pnt)
loop while edge_pnt # null
test23 = test23 + 1
local next_pnt = geom.edge.next.edge(edge_pnt,edge_ind)
edge_ind = geom.edge.next.index(edge_pnt,edge_ind)
edge_pnt = next_pnt
geom.edge.node
Syntax
n = geom.edge.node(e,i)
Get an edge node.
Returns: n - node pointer

i - edge index with i = 1 or 2
geom.edge.node.pos
Syntax
Vector Access
v = geom.edge.node.pos(e,ie<,i>)
geom.edge.node.pos(e,ie<,i>) = v
Returns: v - node position vector or component

Accepts: v - node position vector or component
ie - Node index with 1 ie 2.
Component Access
f = geom.edge.node.pos.x(e,ie)
geom.edge.node.pos.x(e,ie) = f
Get/set the x-component of the node position.
Returns: f - x-component of the node position vector

Accepts: f - x-component of the node position vector
f = geom.edge.node.pos.y(e,ie)
geom.edge.node.pos.y(e,ie) = f
Get/set the y-component of the node position.
Returns: f - y-component of the node position vector

Accepts: f - y-component of the node position vector
f = geom.edge.node.pos.z(e,ie) (3D only)

geom.edge.node.pos.z(e,ie) = f (3D only)
Get/set the z-component of the node position.
Returns: f - z-component of the node position vector

Accepts: f - z-component of the node position vector
geom.edge.pos
Syntax
Vector Access
v = geom.edge.pos(e<,i>)
Get the edge position. The edge position is the center of the edge.
Returns: v - edge position vector or component

Component Access
f = geom.edge.pos.x(e)
Get the x-component of the edge position.
Returns: f - x-component of the edge position vector

f = geom.edge.pos.y(e)
Get the y-component of the edge position.
Returns: f - y-component of the edge position vector

f = geom.edge.pos.z(e) (3D only)
Get the z-component of the edge position.
Returns: f - z-component of the edge position vector

geom.edge.remove
Syntax
v = geom.edge.remove(g,e)
Delete an edge. Any object (e.g., a polygon) connected to the edge is also deleted.

e - edge pointer
geom.edge.start.index
Syntax
i = geom.edge.start.index(e)
Index of the first polygon attached to an edge. This is used to iterate through all polygons attached to an edge with the geom.edge.start.poly, geom.poly.next.poly
and geom.poly.next.index functions.
Returns: i - polygon index

Usage Example
The following example illustrates how geom.edge.start.index can be used to iterate through all polygons connected to an edge.
; Test edge to poly loop

global test25 = 0
local edge_pnt = geom.edge.find(setpnt,1)
local poly_pnt = geom.edge.start.poly(edge_pnt)
local poly_ind = geom.edge.start.index(edge_pnt)
loop while poly_pnt # null
test25 = test25 + 1
local next_pnt = geom.poly.next.poly(poly_pnt,poly_ind)
poly_ind = geom.poly.next.index(poly_pnt,poly_ind)
poly_pnt = next_pnt
See also
geom.edge.start.poly
geom.edge.start.poly
Syntax
p = geom.edge.start.poly(e)
Get the first polygon attached to an edge. This is used to iterate through all polygons attached to an edge with the geom.edge.start.index, geom.poly.next.poly
and geom.poly.next.index functions.
Returns: p - polygon pointer

Usage Example
The following example illustrates how geom.edge.start.poly can be used to iterate through all polygons connected to an edge.

global test25 = 0
test25 = test25 + 1
poly_pnt = next_pnt
See also
geom.edge.start.index
geom.edge.typeid
Syntax
i = geom.edge.typeid
Get the edge type number. The type ID can be used to uniquely identify edge FISH pointers, and distinguish them from any other type of FISH pointer.
geom.node.create
Syntax
n = geom.node.create(g,v)
Create a node. The node is located at v.

v - node position
geom.node.delete
Syntax
v = geom.node.delete(g,n)
Delete a node. All dependent objects connected to the node are deleted.

n - node pointer
geom.node.extra
Syntax
a = geom.node.extra(n,i)
geom.node.extra(n,i) = a
Get/set node extra variable.

Arguments: n - node pointer
i - extra index
geom.node.find
Syntax
n = geom.node.find(g,id)
Find a node.

id - node ID
geom.node.group
Syntax
s = geom.node.group(n<,slot>)
geom.node.group(n<,slot>) = s
Get/set node groups. Use of the group logic is described in Group.

geom.node.group.remove
Syntax
br = geom.node.group.remove(n,s)
Remove node groups. The specified group name is removed from all group slots.

s - group name
geom.node.id
Syntax
i = geom.node.id(n)
Get the node ID.
Returns: i - node ID
geom.node.isgroup
Syntax
b = geom.node.isgroup(n,s<,slot>)

s - group name
geom.node.list
Syntax
l = geom.node.list(g)
Get the node list of a geometry set. Use the loop foreach construct to iterate through the list.
Returns: l - node list

geom.node.near
Syntax
n = geom.node.near(g,v<,f>)
Find the closest node to a point. If f is specified, then the search radius is limited.

v - position
geom.node.pos
Syntax
Vector Access
v = geom.node.pos(n<,i>)
geom.node.pos(n<,i>) = v
Returns: v - node position vector or component

Accepts: v - node position vector or component
Component Access
f = geom.node.pos.x(n)
geom.node.pos.x(n) = f
Get/set the x-component of the node position.
Returns: f - x-component of the node position vector

Accepts: f - x-component of the node position vector
f = geom.node.pos.y(n)
geom.node.pos.y(n) = f
Get/set the y-component of the node position.
Returns: f - y-component of the node position vector

Accepts: f - y-component of the node position vector
f = geom.node.pos.z(n) (3D only)

geom.node.pos.z(n) = f (3D only)
Get/set the z-component of the node position.
Returns: f - z-component of the node position vector

Accepts: f - z-component of the node position vector
geom.node.remove
Syntax
v = geom.node.remove(g,n)
Delete a node. All dependent objects connected to the node are deleted.

n - node pointer
geom.node.start.edge
Syntax
e = geom.node.start.edge(n)
Get the first edge connected to a node. This can be used to iterate through all edges attached to a node with the geom.node.start.index, geom.edge.next.edge and
geom.edge.next.index functions.

Usage Example
The following example illustrates how geom.node.start.edge can be used to iterate through all edges attached to a node, counting the number of edges.

global test23 = 0
test23 = test23 + 1
edge_pnt = next_pnt
geom.node.start.index
Syntax
i = geom.node.start.index(n)
Index of the first edge connected to a node. This can be used to iterate through all edges attached to a node with the geom.node.start.edge, geom.edge.next.edge
and geom.edge.next.index functions.
Returns: i - edge index

Usage Example
The following example illustrates how geom.node.start.index can be used to iterate through all edges attached to a node, counting the number of edges.

global test23 = 0
test23 = test23 + 1
edge_pnt = next_pnt
geom.node.typeid
Syntax
i = geom.node.typeid
Get the node type number. The type ID can be used to uniquely identify node FISH pointers, and distinguish them from any other type of FISH pointer.
geom.poly.add.edge
Syntax
er = geom.poly.add.edge(p,e)
Add an edge to a polygon. The edges must be in order so that each edge connects via a node to the edge before it. An error results if this is not true.
Returns: er - edge pointer with er = e

Arguments: p - polygon pointer
e - edge pointer
geom.poly.add.node
Syntax
e = geom.poly.add.node(g,p<,n><,v><,i>)
Add an edge via a node addition. The first node in the created edge is whichever unconnected node remains from the last edge added to the polygon. A node pointer or a
vector or an integer must be specified as the third argument to identify the second node to complete the edge. If a vector is specified, then that position is queried for a
node. If an integer is specified, then the nodes in this geometry set are queried to find the node with that ID. If a node is not found, then a new node is created and is
used to complete the edge.
If no edge has been created, the node is stored pending another geom.poly.add.node call so that the first edge may be created from those two points. In this case, e is a
null pointer.
Note
If an edge already exists between any two nodes, a new edge will not be created and the preexisting one will be used by the polygon and returned.

p - polygon pointer
n - optional node pointer of the second node
v - optional vector position of the second node
i - optional ID of the second node
geom.poly.area
Syntax
f = geom.poly.area(p)
Get the polygon area. The polygon must be valid.
Note
If the polygon is nonplanar in 3D, the return value is approximate and based on assumptions about the surface shape.
Returns: f - polygon area

geom.poly.check
Syntax
b = geom.poly.check(p)
Get the validity status. A polygon is valid if: 1) it has at least 3 edges; 2) the edges are all connected; and 3) the polygon is closed.
Note
Edge crossings, convexity and planarity in 3D are not checked.
Returns: b - validity status

geom.poly.close
Syntax
e = geom.poly.close(g,p)
Close a polygon. An edge is created between the first node of the first edge and the last node of the last edge. If an edge already exists between the nodes, then the
preexisting edge will be used by the polygon and returned.
Note
An error occurs if the polygon is already closed.

p - polygon pointer
geom.poly.create
Syntax
p = geom.poly.create(g)
Create a polygon. The newly created polygon has no edges, so is in an invalid state. Edges may be added with geom.poly.add.edge or geom.poly.add.node before
the polygon is in a valid state.

geom.poly.delete
Syntax
v = geom.poly.delete(g,p)
Delete a polygon. The polygon must belong to g.

p - polygon pointer
geom.poly.edge
Syntax
e = geom.poly.edge(p,i)
Get a polygon edge. A null pointer may be returned.

i - edge index with 1 i geom.poly.size
geom.poly.extra
Syntax
a = geom.poly.extra(p,i)
geom.poly.extra(p,i) = a
Get/set polygon extra variable.

i - extra index
geom.poly.find
Syntax
p = geom.poly.find(g,id)
Find a polygon.

id - polygon ID
geom.poly.group
Syntax
s = geom.poly.group(p<,slot>)
geom.poly.group(p<,slot>) = s
Get/set polygon groups. Use of the group logic is described in Group.

geom.poly.group.remove
Syntax
br = geom.poly.group.remove(p,s)
Remove polygon groups. The specified group name is removed from all group slots.

s - group name
geom.poly.id
Syntax
i = geom.poly.id(p)
Get the polygon ID.
Returns: i - polygon ID
geom.poly.isgroup
Syntax
b = geom.poly.isgroup(p,s<,slot>)

s - group name
geom.poly.list
Syntax
l = geom.poly.list(g)
Get the polygon list of a geometry set. Use the loop foreach construct to iterate through the list.
Returns: l - polygon list

geom.poly.near
Syntax
p = geom.poly.near(g,v<,f>)
Find the closest polygon to a point. If f is specified, then the search radius is limited.

v - position
geom.poly.next.index
Syntax
ir = geom.poly.next.index(p,i)
Get the index of the next edge of a polygon. This can be used to iterate through all polygons connected to an edge using the geom.poly.next.poly function.
Returns: ir - edge index

i - edge index
Usage Example
The following example illustrates how geom.poly.next.index can be used to iterate through all polygons connected to an edge.

global test25 = 0
test25 = test25 + 1
poly_pnt = next_pnt
See also
geom.poly.next.poly
geom.poly.next.poly
Syntax
pn = geom.poly.next.poly(p,i)
Get the next polygon connected to an edge. This can be used to iterate through all polygons connected to an edge using the geom.poly.next.index function.
Returns: pn - next polygon pointer

i - edge index with 1 i geom.poly.size
Usage Example
The following example illustrates how geom.poly.next.poly can be used to iterate through all polygons connected to an edge.

global test25 = 0
test25 = test25 + 1
poly_pnt = next_pnt
See also
geom.poly.next.index
geom.poly.node
Syntax
n = geom.poly.node(p,i)
Get a node.
Note
If the polygon is invalid because it is not yet closed, this function cannot be used to access the last node on the trailing edge.

i - node index with 1 i geom.poly.size
geom.poly.normal
Syntax
Vector Access
v = geom.poly.normal(p<,i>)
Get the polygon normal. If not planar, this is the average of each vertex
Returns: v - polygon normal vector or component

i - Optional vector component that ranges from {3 to 3 in 2D; 1 to 3 in 3D}.
Component Access
f = geom.poly.normal.x(p) (3D only)
Get the x-component of the polygon normal.
Returns: f - x-component of the polygon normal vector

f = geom.poly.normal.y(p) (3D only)
Get the y-component of the polygon normal.
Returns: f - y-component of the polygon normal vector

f = geom.poly.normal.z(p)
Get the z-component of the polygon normal.
Returns: f - z-component of the polygon normal vector

geom.poly.pos
Syntax
Vector Access
v = geom.poly.pos(p<,i>)
Get the polygon position.
Returns: v - polygon position vector or component

Component Access
f = geom.poly.pos.x(p)
Get the x-component of the polygon position.
Returns: f - x-component of the polygon position vector

f = geom.poly.pos.y(p)
Get the y-component of the polygon position.
Returns: f - y-component of the polygon position vector

f = geom.poly.pos.z(p) (3D only)
Get the z-component of the polygon position.
Returns: f - z-component of the polygon position vector

geom.poly.remove
Syntax
v = geom.poly.remove(g,p)
Delete a polygon. The polygon must belong to g.

p - polygon pointer
geom.poly.size
Syntax
i = geom.poly.size(p)

geom.poly.typeid
Syntax
i = geom.poly.typeid
Get the polygon type number. The type ID can be used to uniquely identify polygon FISH pointers, and distinguish them from any other type of FISH pointer.
geom.set.closest
Syntax
v = geom.set.closest(g,vp<,f>)
Get closest node coordinate vector from the position supplied .
Returns: v - node coordinate vector

Arguments: g - geometric set pointer
vp - 3d vector position
f - initial search radius( optional float)
geom.set.create
Syntax
g = geom.set.create(s)
Create a geometry set.
Returns: g - geometry set pointer

Arguments: s - geometry set name
geom.set.delete
Syntax
v = geom.set.delete(g)
Delete a geometry set. All associated edges/nodes are deleted.

geom.set.edge.maxid
Syntax
i = geom.set.edge.maxid(g)
Get the maximum edge ID.
Returns: i - maximum edge ID

geom.set.edge.num
Syntax
i = geom.set.edge.num(g)

geom.set.find
Syntax
g = geom.set.find(id)
Find a geometry set.
Returns: g - geometry set pointer

Argument: id - geometry set ID or name
geom.set.id
Syntax
i = geom.set.id(g)
Get the geometry set ID.
Returns: i - geometry set ID

geom.set.list
Syntax
l = geom.set.list
Get the global geometry set list. Use the loop foreach construct to iterate through the list.
Returns: l - geometry set list
geom.set.maxid
Syntax
id = geom.set.maxid
Get the maximum geometry set ID.
Returns: id - maximum geometry set ID
geom.set.name
Syntax
s = geom.set.name(g)
Get the geometry set name.
Returns: s - geometry set name

geom.set.node.maxid
Syntax
i = geom.set.node.maxid(g)
Get the maximum node ID.
Returns: i - maximum node ID

geom.set.node.num
Syntax
i = geom.set.node.num(g)
Get/set the number of nodes.
Returns: i - number of nodes

geom.set.num
Syntax
i = geom.set.num
Get the number of geometry sets.
Returns: i - number of geometry sets
geom.set.poly.maxid
Syntax
i = geom.set.poly.maxid(g)
Get the maximum polygon ID.
Returns: i - maximum polygon ID

geom.set.poly.num
Syntax
i = geom.set.poly.num(g)
Get the number of polygons.
Returns: i - number of polygons

geom.set.remove
Syntax
i = geom.set.remove(g)
Delete a geometry set. All associated edges/nodes are deleted.
Returns: i - integer 0
geom.set.typeid
Syntax
i = geom.set.typeid
Get the geometry set type number. The type ID can be used to uniquely identify geometry set FISH pointers, and distinguish them from any other type of FISH pointer.
Group
Groups are useful command constructs, providing a utility to name objects for later sorting. Groups, in conjunction with the group range element, can be used to restrict
commands to objects with a specific name, for instance. Groups are presented in detail in this section, while the documentation of group commands is given here.
History
The values of a set of variables can be sampled and stored during a model run by using the history command. These variables can then be plotted versus step number or versus
other histories. Histories can also be written to a file (with the history export command). Only one variable may be given per history command. History variables may be
added at any time. The contents of all histories can be erased with the history purge command, and all histories can be deleted with the history delete command. A
summary of all histories is printed by the history list all command.
All histories are sampled at a single sampling interval. By default, the sampling interval for the history mechanism is every 10 steps. The sampling interval can be changed
with the history interval command. Different sampling intervals cannot be assigned for different history variables.
l Commands
Commands
Operate on histories.
Each history records and stores a single scalar value during cycling. The interval is controlled by the history interval command. Histories are created using the history
keyword applied to a specific data type (for example zone history or ball history).
Please note that the history logic is not intended for the purpose of taking a very large number of histories. While the code will not stop you from taking tens of thousands of
histories every step (or even more), the amount of data stored will quickly become unmanageable and might even fill up a hard drive.
History data is stored in a temporary file while the model is open, and this data is transferred to the save file when the model is saved.
History Commands
history delete
All history traces are deleted.
history export
Write the contents of the list of histories to the...
history interval
Specifies the history-sampling interval.
history list
List history information.
history name label
Assigns a label with the name sl to history sn .
history purge
The contents of all history traces are erased, but the...
history results
indicates whether history information is stored in subsequent results files.
l history delete command

l history export command
l history interval command
l history list command
l history name command
l history purge command
l history results command
history delete command

Syntax
history delete
All history traces are deleted.
history export command

Syntax
history export <keyword> ...
Primary keywords:
s | begin | end | file | skip | table | vs
Write the contents of the list of histories to the screen, a file (with the file keyword) or a table (with the table keyword). If any history ID is negative, then the value of
the history with corresponding positive ID is reversed (multiplied by -1). The information can be limited to a specified range of data using the following keywords:
s <reverse>
Adds a history by name s to the list of those being output. If the reversed keyword is given, the negative of that history value is output.
begin i
Values with a step number greater than or equal to i will be output.
end i
Values with a step number less than or equal to i will be output.
file s <truncate> <append>
The history information is sent to a text file. If no extension is specified, ".his" is used. truncate causes any previously existing file to be replaced. append causes
data to be appended to the end of the file. append is the default option.
skip i
Only one set of values for every i sampled intervals will be output. For example, skip 10 means that every 10th recorded set of values (starting with the first) will
be output.
table s
The contents of the history are added to the contents of table s. Note that only one history at a time may be output to a table.
vs keyword
Specifies the values to use for the x-axis of the history output. By default this value is the step number. The values of history s at the same step may be used
instead. If the reverse keyword is given, then the negative values of history s at the same step are used.
s <reverse>
step
history interval command

Syntax
history interval i
Specifies the history-sampling interval.
history list command

Syntax
history list keyword
Primary keywords:
all | labels | limit | series
List history information.
all
All histories are listed including their IDs, names and positions.
labels
The labels associated with all histories are listed.
limit
The limits (i.e., minimum interval, maximum interval, minimum value and maximum values) are listed for all histories.
series keyword ...
Lists the contents of selected histories to the console
s <reverse>
Adds a history by name s to the list of those being output. If the reversed keyword is given, the negative of that history value is output.
begin i
Values with a step number greater than or equal to i will be output.
end i
Values with a step number less than or equal to i will be output.
skip i
Only one set of values for every i sampled intervals will be output. For example, skip 10 means that every 10th recorded set of values (starting with the
first) will be output.
vs keyword
Specifies the values to use for the x-axis of the history output. By default this value is the step number. The values of history s at the same step may be used
instead. If the reverse keyword is given, then the negative values of history s at the same step are used.
s <reverse>
step
history name command

Syntax
history name sn label sl
Assigns a label with the name sl to history sn. During plotting, this name will appear instead of the default name. If you wish to use the original name again, assign an
empty string (“ ”).
history purge command

Syntax
history purge
The contents of all history traces are erased, but the traces themselves remain.
history results command

Syntax
history results active b
indicates whether history information is stored in subsequent results files. By default this value is off.
Model
These are a group of commands that affect the current model state. Thus, unlike with most commands that are specific to a model component (i.e., a data scalar or a geometry
set), many model commands act on the entire model. For instance, the entire model state is reset with the model new command and is saved/restored with the model save and
model restore commands. These commands differ from the program commands where the results are not saved with the model state but are generally stored in the computer
registry.
l Commands
Commands
These commands examine or modify the general model state. These are either settings that are saved/restored/reset along with the model, or general model controls that do not
pertain to a specific module (like zone, structure elements, or ball).
Model Commands
model calm
Calm the model.
model clean
Clean the model.
model configure
Configure an additional calculation mode.
model creep
Set parameters for a creep material analysis.
model cycle
Execute timesteps.
model deterministic
Set the deterministic mode.
model display
Set information to display during cycling.
model domain
Specify the domain boundaries and conditions.
model dynamic
Set parameters for a dynamic material analysis.
model factor-of-safety
Set factor of safety analysis parameters.
model fluid
Set parameters for a fluid flow analysis.
model gravity
Set the gravity.
model history
Create a history of a model quantity.
model largestrain
Sets the program to use the numerical formulation for large-strain...
model list
List a model related quantity.
model mechanical
Set parameters for a mechanical analysis.
model new
Clear model-state information.
model precision
Set the listing precision.
model random
Set the seed for the random-number generator.

model range
Create/delete a named range.
model restore
Restore program-state information.
model results
Perform file operations on results files.
model save
Save all model-state information.
model solve
Solve to a specified limit.
model step
Execute timesteps.
model thermal
This command sets parameters for a thermal material analysis (only...
model title
Set the model title.
model update-interval
Set the number of cycles taken between updating the existing...
l model calm command

l model clean command
l model configure command
l model creep command
l model cycle command
l model deterministic command
l model display command
l model domain command
l model dynamic command
l model factor-of-safety command
l model fluid command
l model gravity command
l model history command
l model largestrain command
l model list command
l model mechanical command
l model new command
l model precision command
l model random command
l model range command
l model restore command
l model results command
l model save command
l model solve command
l model step command
l model thermal command
l model title command
l model update-interval command
model calm command

Syntax
model calm
Calm the model. For mechanical processes, all linear and rotational velocities are set to 0.
model clean command

Syntax
model clean
Clean the model.
Note
FLAC3D objects (zones and structural elements) are not affected by this command. It is present in support of PFC objects (balls, walls, etc.). See PFC Plugin for futher
context.
During model creation, prior to cycling, a model is not valid in the sense that there are no contacts between pieces, piece properties may not be set, and pieces may not
be entered into a data structure for efficient spatial searching. The model.clean command is a global command that can be given at any point during the model creation
process to create all contacts in the model, initialize all piece properties, ensure that the data structures are present for spatial searching, and update the contact activity
status based on the geometry. This command is invoked when the model timestep fix and model timestep auto commands are given.
Caution
In PFC, when using DFNs to insert contacts: if the fracture model command is not given prior to a model clean command, then the newly created contacts that intersect
fractures will not be assigned a fracture ID.
model configure command

Syntax
model configure keyword ...
Configure an additional calculation mode. This command allows the user to specify that the model is using calculation modes that either require extra resources or are
restricted by your license information. The model.configure command can be given at any stage of an analysis, but it must be given before the calculation mode (model
solve or model cycle) can be invoked.
The following keywords apply.
creep
Creep material analysis*
dynamic
Fully dynamic analysis*
fluid
Fluid-flow analysis
imass
The Itasca Model for Advanced Strain Softening*
plugin
C++ user-defined models and/or FISH intrinsic plugins.* FISH plugins can be loaded (but cycling is disabled) without this configuration.
thermal
Thermal analysis
Note
*These analysis modes are available only if the corresponding program option is included in the program license.
model creep command

Syntax
model creep keyword
Primary keywords:
active | time-total | list | slave | substep | timestep
Set parameters for a creep material analysis. Time-dependent creep material analysis is only available if model configure creep has been specified. This is only
available with the Creep model option — see Creep Constitutive Models for details.
active b
The creep process is on, by default, when the model configure creep command is given. Specify active off to suppress the creep calculation.
time-total f
f is the accumulated creep time for the model. This can be reset to any value, and will continue to be accumulated during cycling after that.
list
Display creep calculation-mode information.
slave b
Specifies that creep mode is to be considered a slave, and cycled to equilibrium after each master step has been taken. This particular option is provided for
completeness, but is rarely useful in creep calculations.
substep i
Specifies the maximum number of steps the creep process will take when solving with slave on.
timestep
Timestep controls for creep calculations. Note that there is no analytical solution for the stable timestep for most creep models, therefore the timestep in automatic
mode is controlled by a servo tied to the unbalanced force ratio. See the topic Automatic Adjustment of the Creep Timestep in the Creep section. The following
keywords are available.
automatic b
If on, the stable timestep is determined according to the timestep servo with settings specified below. If off the timestep must be set manually using the fix
keyword.
fix f
Set the timestep to be the fixed value f. All timestep calculations are skipped.
Warning
Using the fix keyword may result in model instabilities if f is above the stable timestep limit. Use this with extreme caution.
increment f
Set the incremental amount that the timestep is allowed to increase from one cycle to the next in automatic mode. By default, f = 1.05. The timestep can
decrease by any amount to ensure stability.
latency i
Set the minimum number of steps that must elaspe before the timestep is changed when the servo is controlling the timestep. Using this keyword implicitly
sets servo on. By default the :latency: is 1.
lower-bound f
If the current convergence ratio falls below f, then the lower-multiplier is applied to the time step to increase it. Using this keyword implicitly sets servo on.
By default the :lower-bound: is 1e-3.
lower-multiplier f
The value applied to the current timestep when the convergence ratio falls below lower-bound. This value should be greater than 1.0. By default lower-
multiplier is 1.01.
maximum f
The maximum timestep allowed. The servo will not raise the timestep above this value. There is no default timestep maximum.
minimum f
The minimum timestep allowed. The servo will not lower the timestep below this value. There is no default timestep minimum.
servo b
Activate or de-activate the timestep servo control. If the timestep has been set to automatic on and servo off, then the last calculated servo value will
continue to be used.
starting f
Specify the timestep to use at the start of creep calculations, when the timestep is under servo control. The timestep will be adjusted by the servo every step
afterwards. A starting timestep must be given before starting creep calculations.
unbalanced b
Indicate that the timestep servo is to use maximum unbalanced force instead of the convergence ratio. The values lower-bound and upper-bound are now
compared against the maximum unbalanced force. Note that the default values of lower-bound and upper-bound are unlikely to be valid for this case.
upper-bound f
If the current convergence ratio falls above f, then the upper-multiplier is applied to the time step to increase it. Using this keyword implicitly sets servo on.
By default the :upper-bound: is 5e-3.
upper-multiplier f
The value applied to the current timestep when the convergence ratio falls above upper-bound. This value should be less than 1.0. By default lower-
multiplier is 0.9.
model cycle command

Syntax
model cycle i <calm i2 >
Execute timesteps. The synonym model step may also be used. This is the equivalent of calling model solve with the cycles keyword set to i.
i timesteps are executed unless processing is interrupted by pressing the Shift + Esc, which will terminate cycling, exit the current data file (and all levels of nested data
files that may have been used to call it), and return input to the command prompt after the current step is completed.
The optional calm keyword is used in mechanical processes to reset the linear and angular velocities to zero every i2 cycles.
model deterministic command

Syntax
model deterministic <default> b
Set the deterministic mode. Deterministic mode is reset to the default setting whenever a model new command is given. The optional default keyword is used to set the
default settingto b. When default is not used then the current deterministic mode only is set. On installation (that is, prior to any user change) the program's default
determinism setting is on. The default setting can also be changed by unchecking "Determinism by default" checkbox in the Options Dialog.
When a calculation is performed in parallel over multiple CPUs or cores, the order in which specific computations occur can and will change. This can cause roundoff
errors to accumulate differently. For many models, the final result of these differences is nearly impossible to detect. But for a wide class of models these differences
can magnify, resulting in a situation where a different result occurs every time a given model is run.
It is important to note that all of these results are equally valid, as they are all within the range of finite-precision floating point error. Deterministic mode sacrifices
efficiency and memory to force the parallel computation to result in the same answer every time, regardless of the number of CPUs it is performed on or their relative
speed.
The following are the effects of turning determinism off.
l The model will run faster. How much faster will be code- and model-dependent: as much as 20% faster in FLAC3D or PFC3D.
l Results will not be repeatable. In some cases where small changes propagate, very different results will occur every time you run the model.
l Data files (and project bundle) will no longer reliably reproduce your results. For archival purposes, users should store the resulting save files along with input
data.
l For a problem requiring support, Itasca may not be able to replicate the issue. In this case the model should be rerun with determinism on. If the problem no
longer occurs, there might be very little that can be done to resolve the issue.
model display command

Syntax
model display keyword
Set information to display during cycling. Along with the baseline information, additional information can be displayed during cycling using the keywords below. This
information will be updated every step.
active b
Turn off or on the additional information in the cycle information. This is set to on automatically when one of the other keywords is specified.
fish s
Add the value of the FISH symbol s to the cycle output. A leading "@" is optional.
history i
Add the tabulated value of the history with ID i to the cycle output. Only the result of one history can be shown.
model domain command

Syntax
model domain keyword
Specify the domain boundaries and conditions. DFN fractures only exist within the domain extent.
Note
In FLAC3D, zones and structural elements are not aware of the model domain.
In PFC, walls clumps and balls must be inside of the domain and are aware of the domain boundary conditions.
condition keyword <keyword keyword>
Set the domain boundary conditions. Each domain condition applies to the two box sides that are perpendicular to the direction.
The first keyword specifies the condition for the x direction. The second for the y, and the third for the z. If only one keyword is specified, then y and z are set to
the same condition as x. The default condition is the stop condition.
The following keywords can be used to specify domain conditions.
stop
The stop condition imposes the constraint that if the body centroid falls outside the model domain, the velocity and spin of the body are nulled. For PFC
walls, once a facet centroid falls outside the model domain, the velocity and spin are nulled, including any vertex velocities.
reflect
The reflect condition imparts the opposite sign of the velocity, and the spin is unchanged if the body centroid falls outside the model domain. The use of
this condition as a contact rule is not recommended since it may induce instabilities. The reflect condition is not compatible with walls intersecting the
domain.
destroy
The destroy condition deletes balls, clumps, and wall facets whose individual extents (i.e., an axis-aligned bounding box that tightly encompasses the
object) fall outside the model domain.
periodic
The periodic condition applies periodic boundary conditions. When the ball or clump centroid falls outside of the model domain, they are translated back to
the opposite side of the model. To ensure that contacts are created as if the model was continuous, "ghost" balls and clumps are introduced. The periodic
condition is not compatible with walls intersecting the domain.
extent fxl fxu <fyl fyu fzl fzu >
Specify the locations of the sides of the domain. Each set of values applies to the lower and upper bound of that dimension of the domain. If fxl and fxu are
specified alone, then the domain is a cube.
model dynamic command

Syntax
model dynamic keyword
Primary keywords:
active | list | time-total | slave | substep | timestep
Set parameters for a dynamic material analysis. The command is only available if model configure dynamic has been specified, and if the Dynamic Option is present.
See the topic Dynamic Analysis for more information.
active b
The dynamic process is on, by default, when the model configure dynamic command is given. Specify active off to suppress dynamic calculations.
list
Display dynamic calculation-mode information.
time-total f
f is the accumulated dynamic time for the model. This can be reset to any value, and will continue to be accumulated during cycling after that.
slave b
Specify that dynamic mode is to be considered a slave, and cycled to equilibrium after each master step has been taken. This particular option is provided for
completeness, but is rarely useful in dynamic calculations.
substep i
Specify the maximum number of steps the dynamic process will take when solving with slave on.
timestep
automatic
The stable timestep is calculated based on the current stiffnesses and masses of all objects in the system. This is the default setting.
fix f
Set the timestep to be the fixed value f. All timestep calculations are skipped. Setting a value greater than the calculated critical timestep will result in an
error.
increment f
Set the incremental amount that the timestep is allowed to increase from one cycle to the next in auto mode. By default, f = 1.05. The timestep can decrease
by any amount to ensure stability.
maximum f
Set the maximum allowed timestep. By default, there is no bound to the maximum timestep.
safety-factor f
Set the timestep safety factor, or the factor that is multiplied by the stable timestep calculated by automatic mode. By default, f = 1.0.
model factor-of-safety command

Syntax
model factor-of-safety <keyword> ...
Set factor of safety analysis parameters. See the section Factor of Safety for a complete description. The following keywords apply.
associated
Apply associated flow rule. The dilation angle is set equal to the friction angle, as modified by the factor of safety procedure. (By default, the nonassociated flow
applies.)
bracket f1 f2
Set two starting bracket values. Factor of safety calculation stops with a warning message issued if it turns out that the factor of safety falls outside of the
specified brackets. If f1 = f2, FLAC3D tests one value for stability.
characteristic-steps i
Set the characteristic response steps. If not specified, i is tested using the existing perturbation method.
convergence f
Specifies the convergence value used to determine equilibrium. See the discussion of ratio options in Reaching Equilibrium.
filename s
Sets the file name prefix used to identify save files created during the factor of safety calculation. Three files will be created during the process. For example, if
the prefix given was test, then the filenames test-Init.f3sav, test-Stable.f3sav, and test-Unstable.f3sav will be created. These files represent the initial state, the last
stable state, and the last unstable state, respectively.
interface
Specify which interface properties to change during analysis. The user may include or exclude specific interface properties from the list. Note that factor of safety
calculations in large strain mode are not supported if interfaces are present.
include s
Properties matching s are included. Their values are adjusted in the constitutive model as the target factor of safety is changed.
exclude s
Properties matching s are excluded. Their values will stay the same in the constitutive model as the target factor of safety is changed.
list
Display the last factor of safety result.
perturbation f
Set the stress perturbation factor. This is used in determining the characteristic response steps, by perturbing the model from its current (assumed) equilibrium
state by adjusting the stress field and not allowing failure. The default factor is 2.0.
ratio f
Specify the unbalanced force ratio used to determine equilibrium. If this is not explicitly set, the program uses the current value used by the previous model
solve command. The default is 1e-5.
ratio-average f
Specify the unbalanced force ratio used to determine equilibrium, and that the average ratio be used. See the discussion of ratio options in Reaching Equilibrium.
ratio-local f
Specify the unbalanced force ratio used to determine equilibrium, and that the local ratio be used. See the discussion of ratio options in Reaching Equilibrium.
ratio-maximum f
Specify the unbalanced force ratio used to determine equilibrium, and that the maximum ratio be used. See the discussion of ratio options in Reaching
Equilibrium.
resolution f
Set the resolution in comparing two bracketing (stable and unstable) factors. The default is .005 × the mean value. Once the gap betwen the to known stable and
unstable factors is less than this value, the factor of safety calculation will end.
step-limit i
Set a limit on the number of characteristic steps allowed. If the characteristic steps would be above this limit the check is halted and this value is used. The default
value is 200,000.
zone keyword
Specify which interface properties to change during analysis. The user may include or exclude specific zone properties from the list. By default the list of
properties being included is friction, cohesion, joint-cohesion, and joint-friction.
include s
Properties matching s are included. Their values are adjusted in the constitutive model as the target factor of safety is changed.
exclude s
Properties matching s are excluded. Their values will stay the same in the constitutive model as the target factor of safety is changed.
model fluid command

Syntax
model fluid keyword
Primary keywords:
Set parameters for a fluid flow analysis. This command is only available model configure fluid has been specified. See the Fluid-Mechanical Interaction section for
complete information.
active b
The fluid process is on, by default, when the model configure fluid command is given. Specify active off to suppress fluid calculations.
list
Display fluid calculation-mode information.
time-total f
f is the accumulated fluid time for the model. This can be reset to any value, and will continue to be accumulated during cycling after that.
slave b
Specify that fluid mode is to be considered a slave, and cycled to equilibrium after each master step has been taken.
substep i
Specify the maximum number of steps the fluid process will take when solving with slave on.
timestep
automatic
The stable timestep is calculated automatically. This is the default setting.
fix f
error.
increment f
maximum f
safety-factor f
Set the timestep safety factor, or the factor that is multiplied by the stable timestep calculated when auto mode. By default, f = 1.0.
model gravity command

Syntax
model gravity v3
Set the gravity. Gravity is set in units of acceleration. Body force is calculated as the product of the gravity vector and the real mass of an object.
As a shorthand, only a single scalar value f may be specified instead. If this is done gravity is set to (0,0,-f).
model history command

Syntax
model history <name s > keyword
Create a history of a model quantity. These quantities are mostly associated with a process.
The keyword name may be used to give the history a unique identifier for later reference. If name is not specified the history will be given a name automatically based
on the internally assigned ID number.
The following keywords apply:
creep keyword
Values associated with the creep process.
cycles-total
The total number of cycles accumulated while this process is active.
time-total
The total accumulated time while this process is active.
dynamic keyword
Values associated with the dynamic process.
cycles-total
time-total
fluid keyword
Values associated with the fluid process.
cycles-total
time-total
mechanical keyword
Values associated with the fluid process.
cycles-total
ratio
The value of the ratio currently being used. See the definition of ratios in Reaching Equilibrium. this and and next three need to be checked with DR closer
to release!!!!
ratio-average
The value of the average force ratio. See the definition of ratios in Reaching Equilibrium.
ratio-local
The value of the local force ratio. See the definition of ratios in Reaching Equilibrium.
ratio-maximum
The value of the maximum force ratio. See the definition of ratios in Reaching Equilibrium.
time-total
unbalanced-maximum
The maximum unbalanced force in any object.
unbalanced-average
The average unbalanced force over all objects.
thermal
Values associated with the thermal process.
cycles-total
time-total
timestep
The active timestep.
model largestrain command

Syntax
model largestrain b
Sets the program to use the numerical formulation for large-strain deformation. The default is off. See the section Large- and Small-Strain Modes for discussion of the
additional calculations done in this formulation.
model list command

Syntax
model list keyword
Primary keywords:
domain | information | range | record | requirements
List a model related quantity. The following keywords apply:
domain
List the domain extent and the conditions.
information
List general information about the current model state.
range <s>
above needs fixing; looks like use of RAnge as a keyword here prevents proper use of :str:s as needed List all named ranges created as a part of this model. If s is
provided, the contents of the matching named range are listed.
record <keyword>
List information about the current model record. This is a record of all commands and input to the model. See Model State Tracking (the State Record Pane) in
the FLAC3D Interface section.
commands
List all commands given interactively, including commands emitted by interactive tools. Note that commands input as part of a data file are not recorded,
instead the data file is tracked in the Files section.
This list can be sent to the program playback command. When a project bundle is created (See the Tools/Bundle/Pack menu entry in the user interface)
the a .record file is created to represent each model save state in the project. This can theoretically be used to recreate that model state.
files
A list of all input files that can affect the model state, including data files. The name, size, and last modified time and date of the file is recorded.
information
A single line displaying the number of lines of commands and number of file entries stored in the record. This is the default option if no keyword is
specified.
requirements
A complete list of the security requirements for the current model state. Note that if no model exists or the model that does exist is smaller than the demo limits,
need a this to be a link to a section *somewhere* that describes demo version nothing may be listed.
model mechanical command

Syntax
model mechanical keyword
Primary keywords:
Set parameters for a mechanical analysis.
active b
The mechanical process is on by default. Specify active off to suppress mechanical calculations.
list
Display mechanical calculation-mode information.
time-total f
f is the accumulated mechanical time for the model. This can be reset to any value, and will continue to be accumulated during cycling after that.
slave b
Specifies that mechanical mode is to be considered a slave, and cycled to equilibrium after each master step has been taken.
substep i
Specifies the maximum number of steps the mechanical process will take when solving with slave on.
timestep
automatic
The stable timestep is calculated based on the current stiffnesses and masses of all objects in the system. This is the default setting. In a static mechanical
FLAC3D analysis the timestep is arbitrary, and will be set by default to 1.0.
fix f
Set the timestep to be the fixed value f. In a FLAC3D static mechanical analysis the timestep can be set to any value, and inertial masses will be scaled to
ensure stability. See the section Mechanical Timestep Determination for Numerical Stability for a discussion of mass scaling.
increment f
Set the incremental amount that the timestep is allowed to increase from one cycle to the next in automatic mode. By default, f = 1.05. The timestep can
decrease by any amount to ensure stability.
maximum f
safety-factor f
Set the timestep safety factor, or the factor that is multiplied by the stable timestep calculated when auto mode. By default, f = 1.0 in FLAC3D. If the PFC
module is loaded, the default value is f = 0.8. This value is not used for static mechanical FLAC3D analysis.
scale f
This value is not used in FLAC3D mechanical timestep calculations.
update i
This value is not used in FLAC3D mechanical timestep calculations.
model new command

Syntax
model new <force>
Clear model-state information. Model information is cleared, allowing one to begin a new problem. The optional force keyword suppresses the model reset confirmation
dialog (which will normally appear if the model has changed since the last save when the model.new command is used).
Values associated with the project or program state are unaffected by the model new command. See the project new and program commands.
Model-state information includes any defined FISH functions and variables, histories, and tables.
The entire model state can be written to a file via the model save command for subsequent recovery via the model restore command. Alternatively, a FISH function
can write data to a file (see File Utilities), and a different FISH function (created after the model.new command is executed) can read back that data.
Note
When running several different problems from a called file, the model new command must be given before each new problem.
model precision command

Syntax
model precision i
Set the listing precision. The listing precision setup affects outputting floating point values to the screen with the program list command, where 1 i 15 and i = 6,
by default. A different default precision can be set in the user interface (see the "Listings" tab in the Options Dialog). The default setting is reinstated after a model new
command.
model random command

Syntax
model random i
Set the seed for the random-number generator. By default i = 10,000. The value specified should be of the same magnitude as the default value. If the model.random
keyword is given after a model new command, identical models can be generated for multiple runs. The seed is not reset by the model new command.
The value of the random-number seed is emitted into the record, so the record can be used to exactly recreate the original model (see Model State Tracking (the State
Record Pane)).
model range command

Syntax
model range keyword ...
Primary keywords:
create | delete
Create/delete a named range.
create s range
A named range with the name s is created if one does not exist. A list of range elements must follow s. The list of range elements appears in the range keyword
reference topic.
Once a named range has been created, it can be specified in place of a set of range elements in any command (using the named-range keyword) that uses the
range logic.
delete s
Delete the range with name s.
Note
As seen here, the link range (non-optional) or <range > (optional), whenever it appears in a command signature, is a link to the range keyword reference.
model restore command

Syntax
model restore s
Restore program-state information. The state information, resulting from a previous model save command, is in the save file s. If s does not contain a file extension,
then the extension ".f3sav" is added. The path to the save file can be included as part of s.
Information that is part of the project state (see project) or program state (see program) is not affected by a restore.
All model state information (including any defined FISH functions/variables, histories, tables, or model components) is lost and replaced by the information contained
in the file s.
model results command

Syntax
model results keyword
Primary keywords:
clear-map | export | import | index | interval | list | map | prefix | warn
Perform file operations on results files. Results files are lightweight versions of save files. Importing results files will fully overwrite the model state (as with model
restore), but only a small, predetermined portion of the complete model is included. In general, a results file is about 5% of the size of a complete save file, depending
on how much information is included. A state imported from a results file cannot be further cycled.
The user controls what information is included in a results file using the results keyword available to many model objects. In FLAC3D for example, see the zone
results command.
Results files can be explicitly exported at any time using the model results export command. They can also be automatically exported in regular intervals during
cycling using the model results interval command.
Results files are commonly used to export model states at regular intervals — both to allow the creation of a movie later and to make it easy to check the progress of a
model during solution. Movie files can be created by using the Generate Movie Frames... wizard available in the Tools menu of FLAC3D. The "Results" section of the
Options Dialog can also be used to specify an output interval, and control what values are exported.
Results file settings are part of the model state, and are saved and restored with the model. They are reset after a model new command.
Result files generated automatically during cycling are named sequentially using the prefix and the index values. If a prefix is not specified it will default to flac3d;
index defaults to 1. The format used will be prefixXXXX.result, where XXXX is the index value output as four digits with leading zeros as needed. After each file is
exported the index will automatically be incremented.
clear-map
Clear the current list of tabulated results.
export s
Export the results file to the file s. The default extension is f3result in FLAC3D and {p2result in PFC2D; p3result in PFC3D}.
import s or i <skip-fish>
Import the contents of the results file s or the results file with index i. If an integer is given a prospective filename is created given the prefix specified. The
assumed default extension is f3result in FLAC3D and {p2result in PFC2D; p3result in PFC3D}. By default, the FISH state is reset and any FISH variables saved
with the results file are imported. The skip-fish keyword specifies that the current FISH state is kept intact and any FISH variables stored in the results file are not
imported.
index i
Specify the numeric index to use for the name of the next results file to be exported.
interval keyword
Control the interval at which results files are exported during cycling, if at all. The default setting is model results interval active off.
active b
Turn automatic exporting of results files on and off. The default setting is off. In general, setting an export interval will automatically turn exporting on.
clock f keyword
Activate exporting of results files at real-time intervals. f specifies the amount of time between exports. The following keywords are available to define the
units of time f uses.
hours
f is in hours between result file exports.
minutes
f is in minutes between result file exports.
seconds
f is in seconds between result file exports.
creep f
Export a result file every f units of accumulated creep time.
dynamic f
Export a result file every f units of accumulated dynamic time.
fluid f
Export a result file every f units of accumulated fluid time.
mechanical f
Export a result file every f units of accumulated mechanical time. Note that this will include cycles taken under static, creep, or dynamic conditions. Static
cyling always uses a timestep of 1.0.
step i
Export a result file every i cycles. Note that for loosely coupled analyses (see the model solve command) the steps are "super-cycles", and do not includes
steps taken to solve slave processes to equilibrium.
thermal
Export a result file every f units of accumulated thermal time.
list
List the current results file settings. This list starts with a detailed breakdown of all optional values which can be included, and their current setting. It ends with
the current interval values.
map s or sy
Place the list of tabulated results into a FISH map. If the FISH variable does not exist a string name must be given. Otherwise the symbol name can be given
without quotes. The keys are either the super-cycle numbers or the accumulated time at the instant of tabulation while the values are the results file names.
prefix s
Specify the prefix used for automatically exported result files. The default prefix is flac3d in FLAC3D and {pfc2d in PFC2D; pfc3d in PFC3D}.
warn b
Specify whether the user will be notified if a results file overwrites an existing results file when cycling is initiated from the console.
model save command

Syntax
model save s <keyword>
Save all model-state information. The file s is created and, if no extension is provided, the extension is set to ".f3sav". This information includes any defined FISH
functions/variables, histories, tables, and other model components.
The inputdir and localdir keywords can be place after s to specify the location of the save file relative to the calling file or the project file.
A saved model state can be re-activated via the model restore command.
readonly
If the optional readonly keyword is used, the save file is marked as read only. If restored, the model will be restricted from cycling and certain other
modifications.
text
If the optional text keyword is used, the save file will be output as a Unicode text file in JSON format. Note that this will significantly increase both the size of the
file and the amount of time required to save and restore the model. This option is incompatible with the readonly keyword.
model solve command
Syntax
model solve keyword ...
Primary keywords:
and | calm | clock | convergence | creep | cycles-total | dynamic | elastic | fish-call | fish-halt | fluid | mechanical | or | ratio | ratio-average | ratio-local | ratio-maximum |
thermal | time | time-total | time-total-zone | unbalanced-average | unbalanced-maximum
Solve to a specified limit. The solve logic provides a mechanism to continue cycling a model until specified criteria are met, oftentimes resulting in a model that is in
equilibrium to some tolerance. Any combination of the keywords below can be given in a single model.solve command.
Note
If multiple solve limits are given, then cycling will continue until one of the limits is met, unless the and keyword is used, in which case all criteria must be met before
cycling stops.
and
Indicates that when multiple solve limits are given, all must be met before cycling is stopped. The default behavior is to stop once any solve limit is met.
calm i
Specify that every i cycles, the model will be calmed. For mechanical processes, all velocities (both linear and angular) that are not fixed are nulled during a calm.
clock f
Limit the computer run time to f in minutes. By default, there is no limit to the run time.
convergence f
Limit based on the maximum convergence value of all gridpoints and zones in the model (note that currently PFC balls do not support this keyword). The
convergence value for a gridpoint or node is defined as the ratio of the current mechanical force ratio to the target force ratio of the gridpoint. See the zone
gridpoint initialize ratio-target and structure node initialize ratio-target commands. A convergence value of 1.0 is therefore considered
"converged", but it is possible to restrict or relax that by using a value greater or less than 1.0.
creep keyword
Specify a solve limit for the creep process specifically.
cycles i
Limit of the number of cycles to take with creep active during this solve operation.
cycles-total i
Total number of cycles taken with creep active since model creation.
cycles-total-zone i
Total number of cycles taken with creep active in the zone module.
time f
Limit of the time accumulated while this process is active during this solve operation.
time-total f
Limit of the time accumulated while this process is active since model creation.
time-total-zone f
Total accumulated creep time in the zone module.
cycles-total i
A solve limit based on the total number of accumulated cycles.
dynamic
Specify a solve limit for the dynamic process specifically.
cycles i
Limit of the number of cycles to take with dynamic active during this solve operation.
cycles-total i
Total number of cycles taken with dynamic active since model creation.
cycles-total-zone i
Total number of cycles taken with dynamic active in the zone module.
time f
time-total f
time-total-zone f
Total accumulated dynamic time in the zone module.
elastic <only>
Perform a mechanical calculation in two steps: first, assuming elastic behavior; then, using the actual strength values of the material. The cohesion and tensile
strength for all materials in the model are set to high values for the first step. For the second step, the cohesion and tensile strength are reset to their original
values. If the optional only keyword is provided, then only the elastic portion (i.e., the first step) is undertaken. This keyword only applies to the mechanical
process.
fish-call f s <keyword>
Add the FISH function s to the Fish-Call list at location f, as with the fish callback command. See the section FISH Callback Events for a discussion of FISH
callbacks. The following keywords are available to reduce the frequency of the callback.
interval i
If specified, then the function will only be called every i steps.
process keyword
If specified, then the function will only be called if the process indicated is active during that particular cycle.
creep
The callback will only execute if the creep and mechanical process is active
dynamic
The callback will only execute if the dynamic and mechanical process is active
fluid
The callback will only execute if the fluid process is active
mechanical
The callback will only execute if the mechanical process is active
thermal
The callback will only execute if the thermal process is active
fish-halt s
The FISH function s is called during every cycle to determine whether cycling should continue. If s returns false, cycling continues; otherwise, cycling terminates.
fluid keyword
Specifies a solve limit for the fluid process specifically.
cycles i
Limit of the number of cycles to take with fluid-flow active during this solve operation.
cycles-total i
Total number of cycles taken with fluid-flow active since model creation.
cycles-total-zone i
Total number of cycles taken with fluid-flow active in the zone module.
ratio-flow f
Specifies a limiting convergence ratio as defined by the fluid-flow logic. See section xxx of the fluid discussion — CS on 3/7/17 still don't know where this
should go
time f
time-total f
time-total-zone f
mechanical keyword
Specifies a solve limit for the mechanical process specifically.
convergence f
Limit based on the maximum convergence value of all gridpoints and zones in the model (note that currently PFC balls do not support this keyword). The
convergence value for a gridpoint or node is defined as the ratio of the current mechanical force ratio to the target force ratio of the gridpoint. See the zone
gridpoint initialize ratio-target and structure node initialize ratio-target commands. A convergence value of 1.0 is therefore
considered "converged", but it is possible to restrict or relax that by using a value greater or less than 1.0.
cycles i
Limit of the number of cycles to take with mechanical active during this solve operation.
cycles-total i
Total number of cycles taken with mechanical active since model creation.
cycles-total-zone i
Total number of cycles taken with mechanical active in the zone module.
ratio f
Limit based on the current convergence ratio value, as defined by the various modules that use it. By default this is the same as ratio-average. See Reaching
Equilibrium.
ratio-average f
Limited based on the average convergence ratio. See Reaching Equilibrium.
ratio-local f
Limited based on the local convergence ratio. See Reaching Equilibrium.
ratio-maximum f
Limited based on the maximum convergence ratio. See Reaching Equilibrium.
time f
time-total f
time-total-zone f
Total accumulated mechanical time in the zone module.
unbalanced-average f
Limit based on the average unbalanced force among model objects.
unbalanced-maximum f
Limit based on the maximum unbalanced force among model objects.
or
Indicates that when multiple solve limits are set, cycling should stop when any one limit is met. This is the default behavior.
ratio f
Limit based on the convergence ratio returned by all active modules.
ratio-average f
Limit based on the average convergence ratio returned by all active modules.
ratio-local f
Limit based on the local convergence ratio returned by all active modules.
ratio-maximum f
Limit based on the maximum convergence ratio returned by all active modules.
thermal keyword
Specifies a solve limit for the thermal process specifically.
cycles i
Limit of the number of cycles to take with thermal active during this solve operation.
cycles-total i
Total number of cycles taken with thermal active since model creation.
cycles-total-zone i
Total number of cycles taken with thermal active in the zone module.
ratio f
Specifies a limiting convergence ratio as defined by the thermal logic.
ratio-local f
Specifies a limiting local convergence ratio as defined by the thermal logic.
time f
time-total f
time-total-zone f
time f
Cycle until the total time accumulated by any active process after the initiation of the solve meets or exceeds f. This is distinct from the time-total keyword that
refers to the total age of the process.
time-total f
Cycle until the total age of any active process meets or exceeds f. This is distinct from the time keyword.
time-total-zone f
Cycle until the total age of any active process in a zone module meets or exceeds f. This is distinct from the time keyword.
unbalanced-average f
Cycle until the average unbalanced quantity, defined by the active processes, is less than or equal to f. For the mechanical process, unbalanced refers to the
average unbalanced force (i.e., the unbalanced force is what remains after all forces are applied to a model object).
unbalanced-maximum f
Cycle until the maximum unbalanced quantity, defined by the active processes, is less than or equal to f. For the mechanical process, unbalanced refers to the
maximum unbalanced force (i.e., the unbalanced force is what remains after all forces are applied to a model object).
model step command

Syntax
model step i <calm i2 >
Execute timesteps. The synonym model cycle may also be used. This is the equivalent of calling model solve with the cycles keyword set to i.
i timesteps are executed unless processing is interrupted by pressing the Shift + Esc, which will terminate cycling, exit the current data file (and all levels of nested data
files that may have been used to call it), and return input to the command prompt after the current step is completed.
The optional calm keyword is used, in mechanical processes, to reset the linear and angular velocities to zero every i2 cycles.
model thermal command

Syntax
model thermal keyword
Primary keywords:
active | list | slave | substep | time-total | timestep
This command sets parameters for a thermal material analysis (only available if model configure thermal has been specified. See the topic Thermal Analysis.
active b
The thermal process is on, by default, when the model configure thermal command is given. Specify active off to suppress thermal calculations.
list
Display thermal calculation-mode information.
slave b
Specifies that thermal mode is to be considered a slave, and cycled to equilibrium after each master step has been taken. This particular option is provided for
completeness, but is rarely useful in thermal calculations.
substep i
Specifies the maximum number of steps the thermal process will take when solving with slave on.
time-total f
f is the accumulated thermal time for the model. This can be reset to any value, and will continue to be accumulated during cycling after that.
timestep
automatic
The stable timestep is calculated automatically. This is the default setting.
fix f
error.
increment f
maximum f
safety-factor f
Set the timestep safety factor, or the factor that is multiplied by the stable timestep calculated when auto mode. By default, f = 0.8.
update i
This value is not used in FLAC3D thermal timestep calculations.
model title command

Syntax
model title <s >
Set the model title. The title may be displayed in plots and is stored in save files. The command model list information lists the current title.
If s is specified, then that token is parsed as a string and taken as the title. The token may be a FISH string variable. If so, do not enter the token in single quotes. If s is
not specified, then the Job Title: prompt appears and the next input line is taken as the title. At the Job Title: prompt, if [Enter] is pressed but no string is specified, then
the title will be cleared.
model update-interval command

Syntax
model update-interval i
Set the number of cycles taken between updating the existing plots in the user interface. The default value is 100.
Plot
The FLAC3D model can be visualized interactively using controls in the View Pane. As with most FLAC3D operations, one can also create, delete, modify, etc. plots via
commands. It should be clear, though, by taking a quick look at the controls for any plot, that there may be a plethora of keywords associated with modifying any specific
plot. In order to facilitate scripting plots, we have added the ability to export the plot commands to create the current plot view for the user to modify as needed. This is the
recommended process for scripting plotting, and is outlined in the next section.
The plot commands may be used to create, manipulate, and delete plots. The equivalent operations provided by the plot commands are also available from within the
FLAC3D user interface. We recommend interactive plotting as it is much easier and faster (in terms of composition) than command driven plotting. See the Plotting (the View
Pane) section for reference on the View Pane and plotting.
Loosely, the plot commands fall into three groups: commands that operate on the plot as an object (plot create, plot current, plot delete, plot update, and so on),
the command that controls the current view of the plot (plot view), and commands that manipulate the contents, or what appears in a plot (plot item, plot clear, plot
title, etc.). Complete documentation for the first two kinds of operation are available here. For the third group, see Command-Driven Plotting Workflow for discussion.
l Command-Driven Plotting Workflow

l Commands
Command-Driven Plotting Workflow

The heart of plot construction is the addition of plot items to a plot view (plot item create) and then subsequent modification of the plot item (plot item modify) or
deletion of the plot item (plot item delete). On creation or modification, the appearance of the item is controlled by a number of switches that have been set to default
values. If these default settings are adequate for your need, addition of a plot item via commands might be as simple as something like plot item create zone. However, in
the event that the default appearance of a plot item needs to be changed, the switches will need to be modified via the plot item modify command.
The switches, which are rather extensive, are not included in the documentation of the plot command. However, this fact does not prevent access to the keywords associated
with each switch. Instead, we recommend that the user exports their plots to data files and inspect the exported files. We have taken care to name and generally order the
command keywords similarly to the switch arrangement in the user interface, making it relatively intuitive and simple to find keywords associated with specific switches.
The following workflow is the recommended path for creating commands to script plotting:
1. Construct a plot item, or multiple plot items, in the View Pane. Adjust the plot items(s) using the interactive controls until they appear exactly as desired (i.e.,
perspective, magnification, coloring, line styles and sizes, etc.).
2. Make sure that the desired plot view has mouse focus by left clicking on the plot view and export the plot to a data file. This can be accomplished either by: right
clicking on the plot view and selecting Export ‣ Data File ...; selecting File ‣ [plotname] ‣ Export ‣ Data File... from the main menu; or using the "Export Plot" button (
— with the selection "Data File...") on the View pane toolbar. The data file includes all keywords associated with the switches assigned interactively in the user
interface. Note that after export, the resulting data file is automatically opened in the Editor pane for review.
3. If use of plot commands is part of a plotting sequence where changes must occur (for instance, as part of a movie where the model view shifts, magnification changes,
colors change, etc.), it is recommended that the desired change is made interactively and a new data file is created. By comparing the data files, one can relatively easily
identify the keywords and values associated with the modification of the specified switches.
The images above illustrate the first two steps of this process. The first image shows a typical plot (this stress resultant plot comes from the example of an embedded retaining
wall). The second image shows the state of the Control Panel for the plot when the "Zone Uniform" item is selected. Adjacent to that is the portion of the data file exported
from the plot that contains the plot item create command that is responsible for creating the "Zone Uniform" plot item (click the image to enlarge to full resolution, if
needed). There is a very close correspondence between the keywords in the command and the "Attribute" labels in the Control Panel. Accessing the command switches for
plots this way is — as is the case with plotting itself — much faster than trying to construct a plot directly from reference information on the command.
Data files that are created on export will follow a specific structure that moves from plot-level commands (plot create, plot clear, etc.) to the command (or possibly
commands) controlling the view (plot view), followed by the plot item commands that "populate" the plot. Use of indentation for the switches facilitates identification of
the plot's command structure. As can be seen, there are an extensive number of switches that govern the appearance of plot items. However, when controlling a plot via
command is performed, it is likely that only a few switches will be pertinent to the user's goals in manipulating the plot.
See also Switch/Keyword Options for lists of commonly accessed switch options (colors, line styles, etc.).
For reference, the complete exported file for the above plot is listed below.
plot create
plot clear
plot active on
plot background 'white'
plot outline active on width 2 color 'black'
plot legend active on heading color 'black' copyright color 'black' ...
placement left size 25,50 ...
step active off ...
time-real active off ...
time-model active off ...
title-customer active off ...
view-info active off
plot title-job active off
plot title active off
plot view projection perspective magnification 0.977107 ...
center (5,2,4.9) eye (-6.3723,-11.553,4.9) roll 0.000 ...
clip-front -1e+10 clip-back 1e+10
plot item create axes active on ...
axis-x color 'black' draw-positive on draw-negative off label-positive 'X' ...
axis-y color 'black' draw-positive on draw-negative off label-positive 'Y' ...
axis-z color 'black' draw-positive on draw-negative off label-positive 'Z' ...
position (0,0,0) size 1 ...
font size 10 family 'Arial' style bold ...
transparency 0 ...
legend active off
plot item create structure-liner active on ...
contour resultants ...
ramp rainbow ...
minimum automatic maximum automatic interval automatic ...
reversed on above automatic below automatic resultant my use-engine-data on ...
shrink 1 ...
map axis xyz translate (-0.01,0,0) scale (1,1,1) ...
deformation-factor active off ...
marker none ...
system none ...
polygons fill on outline active on width 1 color 'black' ...
outline-transparency 80 lighting off offset 0.5 2 ...
transparency 0 ...
cut active off ...
clip active off ...
legend active on ...
title active on text "" size 55 family 'Times New Roman' style bold color 'black' ...
shrink-caption active off ...
labels active on size 44 family 'Arial' style normal color 'black' ...
labels-maximum 20 ...
map active on size 44 family 'Arial' style normal color 'black' ...
deformation-factor active on size 44 family 'Arial' style normal color 'black' count active off
plot item create zone active on ...
label uniform ...
color-list global on clear ...
label "Zone" color 'cyan' ...
polygons fill on outline active on width 1 color 'black' ...
outline-transparency 80 lighting on offset 0.5 2 selected-only off selected-highlight off ...
null-faces-only off ...
map axis xyz translate (0,0,0) scale (1,1,1) ...
deformation-factor active off ...
hide-null mechanical on thermal off fluid off ...
transparency 70 ...
cut active off ...
clip active off ...
legend active on ...
title active on text "" size 55 family 'Times New Roman' style bold color 'black' ...
map active on size 44 family 'Arial' style normal color 'black' ...
hide-null active off ...
deformation-factor active on size 44 family 'Arial' style normal color 'black' ...
color-list label active on size 44 family 'Arial' style normal color 'black' ...
heading active on text "" size 44 family 'Arial' style normal color 'black' ...
count active off
Commands
Operate on a plot, change its appearance, or its contents. The following commands are available.
Plot commands
plot
Destroys all existing plots in the project.
plot active
This command activates or deactivates plot s .
plot background
Specifies the background color of the plot.
plot clear
removes all plot items from the plot.
plot copy
The plot is copied to the plot named sDest .
plot create
A new plot named s is made the current (i.
plot current
The plot named s is made the current (i.
plot delete
The plot named s is deleted.
plot export
The contents of the plot named s is exported to...

plot item
Create, destroy, or modify plot items associated with the plot.
plot legend
set attributes of the plot legend.
plot load
attempts to load one or more user-defined plot item DLLs.
plot movie
controls whether this plot participates in automatic movie generation.
plot outline
controls the line used to oultine the plot and the...
plot print-size
the size of the bitmap used when exporting plot images...
plot rename
renames the plot named s to sNew .
plot show
This is the same as the plot current command, but...
plot title
the font and settings used to render the title at...
plot title-job
the font and settings used to render the job title...
plot update
if set to off , the plot is not automatically updated...
plot view
controls the camera view of the plot.
l Switch/Keyword Options
l plot active command
l plot background command
l plot clear command
l plot copy command
l plot create command
l plot current command
l plot delete command
l plot export command
l plot item command
l plot legend command
l plot load command
l plot movie command
l plot outline command
l plot print-size command
l plot rename command
l plot reset command
l plot show command
l plot title command
l plot title-job command
l plot update command
l plot view command
Switch/Keyword Options
When using commands for plotting, a number of plot item switches will terminate in an option — a name or value for a color when specifying color, for instance. Each
heading below presents commonly encountered switches for FLAC3D plot items, with instructions on usage and terminal keywords.
Color
When the keyword color is used, color may be specified in the following way:
l by red, greed, blue (RGB) intensity, as integers. Usage: color rgb 10 20 255. Integer values in each position range from 0 to 255.
l by red, green, blue (RGB) intensity, as hexadecimal values. Usage: color "colRRGGBB", where RR, GG, and BB are two-digit hex codes (so "colFFFFFF"
gives white; "col000000" gives black).
l by hue, saturation, and value (HSV). Usage: color hsv 300 100 200. Integer values for hue range from 0 to 359; values for saturation and value range from
0 to 255.
l by name: there are 174 named colors; see table below. Usage: color "darkgold". The list of colors is derived from
http://www.w3.org/TR/SVG/types.html#ColorKeywords. for a list
There is a special color name none. Anything rendered in this color is instead not rendered at all.
Color Ramps
Contour plots use pre-defined ramps of color.
l Usage: ramp keyword, where keyword may be one of: rainbow greyscale bwr bcwyr gwr
See the table below for an illustration of each color ramp.
Lines
Lines have settings for:
l Color — use line color with a valid color specification (see above)
l Visibility — use line active on or line active off to show/hide line rendering
l Style — use line style with one of the six options listed on the table below.
l Width — use line width and a value between 1 and 10, where 1 is the thinnest line width (one pixel). See table below.
Text
Text will provide settings to control:
l Color — use text color with a valid color specification (see above)
l Visibility — use line active on or line active off to show/hide line rendering
l Typeface — use text family with a font-face name (e.g., "Times New Roman") to set the typeface
l Type size - use text size with an integer to indicate type size
l Style — use text style to set the type style to one of: normal bold italic bolditalic (normal is the default)
l Content — Some items will provide a control to specify the text that is to be used, in which case text text s may be used, where s is the specified text
Tables of Values
Table 1: Color Names
aliceblue antiquewhite aqua aquamarine azure beige bisque
black blanchedalmond blue blueviolet brown burlywood cadetblue
cardinal chartreuse chocolate coral cornflowerblue cornsilk crimson
cyan darkblue darkbrown darkcardinal darkcyan darkgold darkgoldenrod
darkgray darkgreen darkgrey darkkhaki darkmagenta darkolivegreen darkorange
darkorchid darkolive darkpeach darkpink darkpurple darkred darksalmon
darkseagreen darkskyblue darkslateblue darkslategray darkslategrey darkturquoise darkviolet
darkyellow deeppink deepskyblue dimgray dimgrey dodgerblue firebrick
floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod
gray grey green greenyellow honeydew hotpink indianred
indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon
lightblue lightbrown lightcardinal lightcoral lightcyan lightgold lightgoldenrodyellow
lightgray lightgreen lightgrey lightolive lightorange lightpink lightpurple
lightred lightsalmon lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue
lightteal lightviolet lightyellow lime limegreen linen magenta
maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue
mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin
navajowhite navy oldlace olive olivedrab orange orangered
orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peach
peachpuff peru pink plum powderblue purple red
rosybrown royalblue saddlebrown salmon sandybrown seagreen seashell
sienna silver skyblue slateblue slategray slategrey snow
springgreen steelblue tan teal thistle tomato transparent
turquoise violet wheat white whitesmoke xlightgold xlightgreen
xlightolive xlightpink xlightpurple xlightred xlightskyblue xlightyellow yellow
yellowgreen
Table 2: Color Ramp

Options
rainbow
greyscale
bwr
bcwyr
gwr
Table 3: Line Options

styles
none
solid
dash
dot
dashdot
dashdotdot
widths
1
2
3
4
5
6
7
8
9
10
plot active command

Syntax
plot <s > active b
This command activates or deactivates plot s. If a plot name s is not specified, the current view is assumed.
By default a plot is active. If a plot is inactive, nothing is rendered in the window except a message indicating as much.
If an error occurs during rendering, the plot will be automatically deactivated to keep the error from reoccurring ever time the screen is refreshed.
plot background command

Syntax
plot <s > background color
Specifies the background color of the plot. If a plot name s is not specified, the current view is assumed.
plot clear command

Syntax
plot <s > clear
removes all plot items from the plot. The plot settings are not changed. If a plot name s is not specified, the current view is assumed.
plot copy command

Syntax
plot <s > copy <sDest > <keyword>
Primary keywords:
both | items | settings
The plot is copied to the plot named sDest. If a plot name s is not specified, the current plot is assumed. If sDest does not already exist, a new plot will be created with
that name. Otherwise the existing plot with that name will be overwritten. If the plot sDest is not specified, a new plot will be created and assigned a default name.
The optional keywords settings, items and both determine whether the plot settings, the plot-item list, or both are copied. The default is both. If a new plot is created, it
is made the active plot. Note that the plot settings include the current camera view settings.
both
Both the plot items in the plot, and the plot settings, are copied to the destination. This is the default option.
items
Only the list of plotitems is copied to the destination.
settings
Only the current plot settings are copied to the destination.
plot create command

Syntax
plot create <s >
A new plot named s is made the current (i.e., active) plot. If no name is specified, one is assigned by default.
plot current command

Syntax
plot <s > current
The plot named s is made the current (i.e., active) plot. This will show the plot if it is hidden.
plot delete command

Syntax
plot <s > delete
The plot named s is deleted. If no plot name is specified, the current view is assumed.
plot export command

Syntax
plot <s > export keyword
Primary keywords:
bitmap | csv | datafile | dxf | pdf | postscript | print | svg | vrml
The contents of the plot named s is exported to a file. If no plot name is specified, the current view is assumed.
This an be used to create a hardcopy of the plot image, create a version of the plot in a different file format, or create a data file that if read in the command processor
will recreate the plot.
If not specified explicitly, all files created will be named "flac3d_name", where "name" is the name of the plot being exported. The default file name extension will be
specific to the kind of file being exported.
The following keywords are used to specify the export format:
bitmap <keyword ...>
renders the plot to a bitmap file. The following keywords can be used to control the format and size of the bitmap created:
filename s
sets the destination file name. If one is not specified, then one will be assigned. The extension determines the format, and PNG is used by default if no
extension is specified. PNG, BMP, PPM, XBM, and XPM formats are supported.
size ix iy
determines the size of the bitmap (in pixels). The default is 1024 x 768.
csv <filename s >
creates a text file of data in CSV (Comma Separated Values) format, with data data from all plot items that support the conversion (e.g., charts, tables, etc.). This
will be arranged in tabular form. This file can be easily imported into a spreadsheet progral like Excel, for further processing.
The filename keyword can be used to specify the file output, which will have the CSV extension by default.
datafile <filename s >
This command exports a data file that, if read with the program call command, should completely recreate the contents of the plot.
The filename keyword can be used to specify the file output, which will have the F3DAT extension by default.
dxf <filename s >
This command attempts to export the geometric contents of the plot as a DXF file. NOTE: The DXF format does not support all of the features used to generate a
plot. Your results may differ substantially from the plot on the screen.
The filename keyword can be used to specify the file output, which will have the DXF extension by default.
pdf <keyword ...>
creates a PDF file of the plot.
filename s
sets the destination file name. The default extension will be PDF.
landscape
specifies use of the landscape layout. The default is portrait.
margin fx1 fx2 fy1 fy2 <inches, millimeters>
specifies the amount of margin to leave around the edges of the page in the layout (in inches or millimeters). The default is 0.25, 0.25, 0.25, 0.25 in.
paper fx fy <inches, millimeters>
specifies the paper size to use in the layout (in inches or millimeters). The default is 11.0, 8.5 in.
size ix iy
determines the size of the bitmap used to render the 3D image. By default, the current print image size setting is used. See the PRINT SIZE property in the
PLOT global settings dialog and the plot global print-size command.
postscript <keyword ...>
creates a Postscript file of the plot.
filename s
sets the destination file name. The default extension will be PS.
landscape
specifies use of the landscape layout. The default is portrait.
margin fx1 fx2 fy1 fy2 <inches, millimeters>
specifies the amount of margin to leave around the edges of the page in the layout (in inches or millimeters). The default is 0.25, 0.25, 0.25, 0.25 in.
paper fx fy <inches, millimeters>
specifies the paper size to use in the layout (in inches or millimeters). The default is 11.0, 8.5 in.
size ix iy
determines the size of the bitmap used to render the 3D image. By default, the current print image size setting is used. See the PRINT SIZE property in the
print
sends the plot to the operating system print system. If in interactive mode, this will open up a print dialog. If running as part of a data file, the plot will be sent to
the default windows printer.
svg <keyword ...>
generates a Scalable Vector Graphics (SVG) file of the plot. The following keywords are available:
filename s
specifies which file and path to give to the SVG file. The default extension is SVG.
size ix iy
specifies the size of the bitmap portion of the plot (in pixels). By default, the current print image size setting is used. See the PRINT SIZE property in the
vrml <keyword ...>
generates a VRML file representing the plot. This file can be viewed directly by a compatible application. For example, Adobe Acrobat 3D can be used to turn
the resulting VRML into a PDF file, or to embed the VRML file into another PDF document. The following keywords are available:
compress b
specifies whether the VRML file output will be compressed or in plain text. The default is false.
filename s
specifies which file and path to give to the VRML file. The default extension is WRL.
plot item command

Syntax
plot <s > item keyword
Create, destroy, or modify plot items associated with the plot. If a plot name s is not specified, the current view is assumed.
The available keywords are:
create keyword ...
adds a new plot item to the list associated with the plot. An alphabetical list of keywords, matched to the items available from the Build Plot dialog, is shown
below. Note that additional plot items can be added by plug-ins to the system at any time.
delete i
destroys the ith plot item in the list associated with the current plot. Note that this will renumber the plots following that in the list.
modify i keyword ...
allows modification of the existing plot item at the ith position in the list associated with the current plot.
Warning
The plot items listed below may be configured through a wide variety of keywords that control various aspects of item's appearance. Those keywords are not
documented here. Instead, the syntax is available by inspection of the results of a plot export to data file (see Command-Driven Plotting Workflow).
Table 1: Plot Items by Keyword (for use with plot item create)
Keyword Build Plot dialog Label Description
axes Axes A cartesian axes representation that helps identify view orientation and location.
chart-history History Chart A chart of the contents of history trace(s). See the History command.
chart-table Table Chart A chart of a table. See the Table command.
data-disk Disks representing user defined data. See the data vector command.
data-label Labels User defined labels. See the Data commands.
data-scalar Scalars User defined scalar data. See the Data commands.
data-tensor Tensors User defined tensor data. See the Data commands.
data-vector Vectors Plots user defined vector data. See the Data commands.
fos Factor of Safety The last calculated factor of safety, displayed as an item in the legend only. See
the model factor-of-safety command.

fracture Fracture Fractures created by the Discrete Fracture Network system. See DFN Commands.
geometry Geometry Geometry data created or imported via the Geometry command.
gridpoint-fix Gp Fixity Lines whose orientation and color indicate gridpoint fixity conditions and
direction.
history-locations History Locations The location of history traces (where approrpriate). See History.
particle-trace Particle Trace The path taken by particle trace records. See Trace.
scalebox Scalebox A background 3D scale box for size reference.
structure-beam Beam Structural beam elements. See the beam commands.
structure-cable Cable Structural cable elements. See the cable commands.
structure-geogrid Geogrid Structural geogrid elements. See the geogrid commands.
structure-liner Liner Structural liner elements. See the liner commands.
structure-pile Pile Structural pile elements. See the pile commands.
structure-shell Shell Structural shell elements. See the shell commands.
structure-vector Vectors Vectors of values at structural nodes (like velocity, displacement, etc).
zone Zone Surfaces of zones in the range.
zone-attach Attach Conditions Attach conditions connecting gridpoints to gridpoints, edges, and faces. See the
zone attach command.
zone-boundary Boundary Boundaries of surfaces of the model, rather than all zone faces.
zone-face Face Zone faces that fall within the range.
zone-group Zone Group Surfaces Zone faces along boundaries where group names change, transparently.
zone-interface Interface Zone interface elements and nodes. [CS: need to work out how to to this: See
the :cmd:-zone.interface- command.]
zone-isosurface IsoSurface Isosurfaces of zone field values.
zone-profile Profile A profile of zone field values along a line in space.
zone-stereonet Stereonet A stereonet projection of oriented values associated with zones, like the minimum
principal stress direction.
zone-tensor Tensors Tensor values of zones, like stress, strain-rate, etc.
zone-track Tracked Particles The paths recorded by zone fluid particle tracking. See the zone fluid track
command.
zone-vector Vectors Vector-based zone values, like velocities, displacements, etc.
zone-water Water Table The last specified water table used to install pore pressures in gridpoints.
plot legend command

Syntax
plot <s > legend keyword ...
Primary keywords:
active | copyright | heading | placement | position | size | step | time-model | time-real | title-customer | view-dip | view-info
set attributes of the plot legend. If a plot name s is not specified, the current view is assumed.
active b
turns the legend on and off (the default is on).
copyright :tok:`text`
the font used to indicate Itasca?s copyright, and code restriction information, if present. Note that only the color can be modified.
heading text
the font used to draw the heading (i.e., "FLACD 6.0") Note that only the color can be modified.
placement keyword
legend location on the plot. The available options are:
floating
legend floats on top of the plot in an arbitrary position
left
legend on left side of plot (default)
right
legend on right side of plot
position ix iy
position of the legend if floating. Values are from 0 to 100, representing percentage of display size.
size iw ih
size of the legend, in percentage of screen width (iw) and height (ih). If legend placement is left or right, only iw is used. iw may vary from 5 to 50; ih may vary
from 5 to 100.
step text
the font used to draw the step number
time-model text
the font used to draw the total time of any active process in the current model.
time-real text
the font used to draw the current date and time
title-customer text
the font used to draw the customer title at the bottom of the legend (if space is available)
view-dip b
if set to on, then the orientation output in the view-info part of the legend is given in terms of dip, dip-direction, roll, and distance. Otherwise the orientation is
given by eye position and roll. The default is off.
view-info text
the font used to draw the current camera view information.
plot load command

Syntax
plot load keyword
Primary keywords:
automatic | s
attempts to load one or more user-defined plot item DLLs. If successful, these plot items will be available in the GUI for plotting.
The following options are available:
automatic
will automatically attempt to load all compatible DLLS found in the exe64pluginsplotitem3d directory (and subdirectories) of the installation directory. The DLLs
must follow the naming convention "plotitem3dname005.dll", where "name" is the unique name of the plotitem.
will attempt to load the plotitem DLL named s. If not a fully qualified path name the code will search the plugins directory exe64pluginsplotitem3d, the current
directory, and the project directory.
The file name of the DLL must follow the convention "plotitem3dname005.dll". You can either specify the full file name, or the string "name" will be auto
expanded into the standard convention.
plot movie command

Syntax
plot s movie keyword
Primary keywords:
active | extension | index | interval | prefix | size
controls whether this plot participates in automatic movie generation. If a plot name s is not specified, the current view is assumed.
Note that only the keywords active and index apply to plot s, the rest of the keywords apply to all plots.
See also the Movie tab in the Tools/Options dialog.
The available options are:
active b
Turns participation in movie frame generation on and off. The default is off.
extension
the extension used for movie bitmap file generation. The value assigned at install is png. This applies to all plots. This values is saved and restored with the
project, and stored in the registry and program shutdown.
index i
Specifies the next index used for the filename the movie frame will be stored in. This index is incremented automatically after every frame.
interval i
the number of global calculation steps taken between movie frames, when the movie option is active for a plot. The value assigned at install is 1000. This applies
to all plots. This values is saved and restored with the project, and stored in the registry and program shutdown.
prefix
the prefix used for the automatically generated file names created using the movie option. The value assigned at install is movie_. This applies to all plots. This
values is saved and restored with the project, and stored in the registry and program shutdown.
size
The size of the bitmap used for movie frame generation. The value assigned at install is 1024 x 768. This applies to all plots. This values is saved and restored
with the project, and stored in the registry and program shutdown.
plot outline command

Syntax
plot s outline line
controls the line used to oultine the plot and the legend.
plot print-size command

Syntax
plot print-size ix iy
the size of the bitmap used when exporting plot images to certain formats including Postscript, PDF, and SVG. The value assigned at install is 1650 x 1238. This values
is saved and restored with the project, and stored in the registry and program shutdown.
plot rename command

Syntax
plot s rename sNew
renames the plot named s to sNew. If a plot name s is not specified, the current view is assumed.
plot reset command

Syntax
plot reset
Destroys all existing plots in the project.
plot show command

Syntax
plot s show
This is the same as the plot current command, but the plot is also forced to regenerate its contents as if the Regenerate tool button were pressed.
plot title command

Syntax
plot s title text
the font and settings used to render the title at the top of the plot. If a plot name s is not specified, the current view is assumed.
plot title-job command

Syntax
plot s title-job text
the font and settings used to render the job title at the top of the plot. If a plot name s is not specified, the current view is assumed.
plot update command

Syntax
plot s update
if set to off, the plot is not automatically updated when changes are made to the model. If a plot name s is not specified, the current view is assumed.
plot view command

Syntax
plot <s > view keyword ...
Primary keywords:
center | clip-back | clip-front | dip | dip-direction | distance | eye | magnification | projection | reset | roll
controls the camera view of the plot. If a plot name s is not specified, the current view is assumed.
center v
the center of the view. The camera always points from the eye position to the view center. In model mode (the default) the eye rotates around the view center
when the view is rotated.
clip-back f
the limiting distance to the back clipping plane. This is by default set to 1e10 so to be not a constraint. If the default view depth setting is causing objects that are
very far away to reduce the resolution of the depth buffer, you can adjust this parameter bring it forward.
clip-front f
the limiting distance to the back clipping plane. This is by default set to -1e10 so to be not a constraint. If the default view depth setting is causing objects that are
very close to reduce the resolution of the depth buffer, you can adjust this parameter bring it back.
dip f
sets the orientation of the view plane, in degrees. The current view center and distance is kept constant and the eye is rotated about the center until the vector from
the eye to the view center is normal to the plane with this dip.
dip-direction f
sets the orientation of the view plane, in degrees. The current view center and distance is kept constant and the eye is rotated about the center until the vector from
the eye to the view center is normal to the plane with this dip direction.
distance f
sets the distance from the eye to the view center. The direction of the current vector from the eye position to the view center is held constant, but the eye is moved
so that the distance between them is this value.
eye v
sets the current eye position. The viewing direction is always from the eye position to the view center. The direction of "up" is determined by the current roll,
which is held constant.
magnification f
sets the current view magnification. The default value is 1.0, which represents a field of view angle of 45 degrees. Increasing the magnification decreases the field
of view angle.
projection keyword
sets if the view includes perspective distortion or if it is an orthographic (parallel) projection. The available keywords are:
parallel
Sets the view to be a orthographic or parallel projection. Objects do not get smaller as they get farther away. The distance parameter has no immediate
effect on the view, except to change the result of interactive controls.
perspective
Sets the view to be a perspective view based on the current eye position with a field of view determined by the current magnification. This is the default
value.
reset
Clears the current view positions, causing the camera view to be determined automatically at the default orientation.
roll f
Sets the current roll, in degrees. Roll defines which direction is towards the top of the screen.
The camera always faces from the eye position to the view center. Roll is defined by the angle from the vector pointing to the top of the screen to the global z
direction projected onto the screen. The global x direction is used if the view is entirely along the z-axis, and therefore has no projection.
Program
These are a group of commands that control and configure program execution. The data associated with program commands are generally not saved at all, or are saved in the
registry of the computer running the program, to be available the next time the program is run. However, the data are not associated with any specific project or model state.
All program commands may be formed with or without the leading word program — the commands forms program.quit and quit will achieve the same result. These
commands differ from the model commands where the results usually impact the model state.
l Commands
Commands
These commands affect the current program state. These values are settings that are not affected either by the model state or by projects — and therefore are unaffected when
the model or project state changes (for instance, when a model is restored).
Some program commands, where noted, are stored in a persistent location on the current computer and remain in effect across multiple program executions. Others only affect
the current instance of the program and will reset if the program is exited and restarted.
All Program commands can be issued with or without the leading command word program. So, for example, call is equivalent to program call.
Program Commands
program call
Process the specified data file(s).
program continue
Resume processing after a program pause.
program customer-title-1
Set the first line of customer information.
program customer-title-2
Set the second line of customer information.
program directory
Set the working directory.
program echo
Set the echo state.
program echo-line
Specify output to echo to the console.
program exit
Close the program.
program list
Print program information.
program load
Load a compatible DLL.
program log
Turn on/off logging.
program log-file
Specify the log file by name.
program mail
Compose and send email messages.
program notice
Set the notice state.
program pagination
Set the pagination state.
program pause
Pause command processing.
program playback
Play back a record file.
program quit
Close the program.
program return
Return program control.
program stop
Close the program.
program system
Send commands to DOS.
program threads
Set the number of threads for calculations and plotting.
program undo
Undo commands.
program warning
Set the warning state.
l program call command

l program continue command
l program customer-title-1 command
l program customer-title-2 command
l program directory command
l program echo command
l program echo-line command
l program exit command
l program list command
l program load command
l program log command
l program log-file command
l program mail command
l program notice command
l program pagination command
l program pause command
l program playback command
l program quit command
l program return command
l program stop command
l program system command
l program threads command
l program undo command
l program warning command
program call command

Syntax
program call s <keyword> ...
Process the specified data file(s).
Note
As with all program commands, use of the command word program is optional; program call and call are both valid.
If the file name s is supplied without an extension, then the code will look for the string both with the ".dat" extension and with the code specific extension (".f3dat" for
FLAC3D).
A file that is called with a relative rather than an explicit path will be searched for first in the folder containing the data file currently being processed, then in the
current directory.[1] [this is something that should be its own topic *somewhere*, and once it is this will be changed to a link to that topic.]
Any series of input instructions can be placed in a data file. Additional files may, in turn, be called from a data file; there is no limit to the levels of nesting. However,
files must not call each other recursively (e.g., file "ABC" calls file "DEF," which then calls file "ABC").
The program pause and program return commands can be used to interrupt data file processing; the program continue command can be given at the command
prompt in the console to resume processing. See those commands for details, particularly with regard to the call stack. Pressing Shift + Esc terminates input from data
files and returns program control to the command prompt, no matter to what level calls have been nested.
call s <keyword> ...
Using two or more call keywords allows multiple files to be called on one line. The called files will processed in the order that they appear in the command, from
last to first. Multiple-file calls each start with the program call command word — the multiple-file call is, in effect, a string of individual calls. The keywords
available for each are the same as allowed for the program call command.
line i
If the line keyword is specified, then the data file starts reading at the line i. If the line is past the end of the file, the file returns instantly, as if you had processed
to the end of the file. This cannot be used with the label option.
label sl
If the label keyword is specified, then the data file starts reading at the label sl. To place a label in a data file, use the syntax ":label" (where the colon must be the
first character in the line). The data file will be read starting with the first line after the label. Lines containing a label are ignored (as if the colon were a
comment). If the label is not found in the data file, an error is indicated. This cannot be used with the line option.
suppress
If the optional keyword suppress is added once in a command, then the command processor will not echo the contents of the called file(s) to the screen while it
processes the file(s) (and any files called by it/them).
Footnotes
Footnotes
[1] The current directory is defined as:
l the folder containing the current project file, unless

l a project file is not in use, in which case it is the folder containing the program, unless
l the program is in a folder secured by Windows (such as the "program files" folder, which is common), in which case it is the folder where the
application data was copied, unless
l the application data has not been copied, in which case it is the base folder for the profile of the current user on the computer (the location of this folder
differs among the versions of Windows available)
Using the program directory command will override any of the above to the location specified in the command. Use list directory to determine the current
directory.
Usage Example
The example file "call_use.dat" below shows a number of possible program call commands. It uses two data files, "table_w1.dat" and "table_w2.dat" — which are shown
below for reference. In reviewing the example, it is important to observe that "table_w2.dat" calls "table_w1.dat" in its fourth line.
;call_use.dat
;basic calls:
call 'table_w2.dat' ;(a)
;call 'table_w2' (b)
;call 'c:\projects\flac3d\examples\table_w2' (c)
;call 'c:\\projects/flac3d//examples\table_w2.dat' (d)
;call 'folder\table_w2.dat' -- ERROR!! (e)
;using line keyword

new
call 'table_w1' call 'table_w2' line 5 ;(f)
new
call 'table_w2' line 5 ;(g)
;using suppress keyword

new
call 'table_w1' suppress call 'table_w2' line 5 ;(h)
The section of the file marked "basic calls" shows five uses of program call. The first four are valid ways to call the file "table_w2.dat", assuming the current directory is
the path "c:\projects\flac3d\examples" as shown in (c) and (d). The fifth use (e) produces an error because the supplied relative path is incorrect. Case (c) illustrates that file
paths may be demarcated using any of "\", "/", "\\", or "//" interchangeably.
The next group is marked ;using line keyword. Usage (f) achieves the same result as the basic calls in cases (a-d). First "table_w2.dat" is processed (starting at line 5, after its
own call to "table_w1.dat" in line 4), then "table1.dat". Note the variance in the processing order means that the "world" tables are created first, therefore they have lower
indices and are listed first when the final program list table command is processed in "table_w2.dat". Case (g) uses the line keyword to bypass the call in "table_w2.dat" to
"table_w1.dat", so in this case only the tables that spell out "world" are created.
The last usage (h) illustrates the suppress keyword. Its call procedure is the same as usage (f), however, the console only shows the results of the program list commands
with this usage.
;table_w1.dat
table letter_h 2,12 2,8 2,10, 4,10 4,12 4,8

table letter_e 7,12 5,12 5,10 7,10 5,10 5,8 7,8
table letter_l1 8,12 8,8 10,8
table letter_l2 11,12 11,8 13,8
table letter_o1 15,12 14,11 14,9 15,8 16,8 17,9 17,11 16,12 15,12
list table
;table_w2.dat
new
call 'table_w1'
table letter_w 2,7 3,3 4,7 5,3 6,7

table letter_o2 8,7 7,6 7,4 8,3 9,3 10,4 10,6 9,7 8,7
table letter_r 11,3 11,7 12,7 13,6 12,5 11,5 13,3
table letter_l3 14,7 14,3 16,3
table letter_d 17,7 17,3 19,3 20,4 20,6 19,7 17,7
list table
plot create
plot clear
plot item create chart-table table 1 table 2 table 3 table 4 table 5 table 6 table 7 ...
table 8 table 9 10 xaxis log off minimum 0 maximum 22 ...
label "X-Axis" inside on yaxis log off minimum 0 ...
maximum 14 label "Y-Axis" inside on
program continue command

Syntax
program continue
Resume processing after a program pause.
Note
As with all program commands, use of the command word program is optional; program continue and continue are both valid.
This command allows the user to resume reading a data file after a program pause has been used in the data file to interrupt processing. After the program pause, the
input focus is put at the command prompt; program continue will resume reading the data file on the next line. The program return command can also be used to
resume processing after a program pause.
program customer-title-1 command

Syntax
program customer-title-1 s
Set the first line of customer information. This line is displayed by default in the lower-left corner of the legend of all plot views.
Note
As with all program commands, use of the command word program is optional; program customer-title-1 and customer-title-1 are both valid.
If s contains spaces, then it must be enclosed by quotes, in which case any occurrence of a single quote or backslash character must be preceded by a backslash
character.
program customer-title-2 command

Syntax
program customer-title-2 s
Set the second line of customer information. This line is displayed in the lower-left corner of the legend of all plot views by default.
Note
As with all program commands, use of the command word program is optional; program customer-title-2 and customer-title-2 are both valid.
If s contains spaces, then it must be enclosed by quotes, in which case any occurrence of a single quote or backslash character must be preceded by a backslash
character.
program directory command

Syntax
program directory keyword
Set the working directory. This setting defaults to the location of the current project file.
Note
As with all program commands, use of the command word program is optional; program directory and directory are both valid.
custom s
The working directory is set to s.
engine
Set the working directory to the location of the main engine module (dll).
executable
Set the working directory to the executable directory, or the directory where the application is stored.
input
Set the working directory to the location of the current input data file.
project
The working directory is set to the location of the current project directory. This is the default.
program echo command

Syntax
program echo keyword
Set the echo state.
Note
As with all program commands, use of the command word program is optional; program echo and echo are both valid.
If activated, each command sent to the command processor is displayed in the console. If logging has been activated with the program log-file command, output is
also saved to the log file. By default, the echo mode is active.
The following options are available:
Turns echo on and off.
suppress
If this keyword is given, then the output is suppressed for the current input source; such as the current data file or the current command/endcommand block in
FISH.
program echo-line command

Syntax
program echo-line s
Specify output to echo to the console.
Note
As with all program commands, use of the command word program is optional; program echo-line and echo-line are both valid.
Even if the global echo state has been set to off (via program echo) or the suppress keyword has been given with the program call command, the string s is output to
the console when this command is used. This is useful for posting status information while processing long data files.
program exit command

Syntax
program exit
Close the program.
Note
As with all program commands, use of the command word program is optional; program exit and exit are both valid.
All information will be lost unless a model save command is issued prior to the program exit command. This command is a synonym for program quit and program
stop.
program list command
Syntax
program list keyword
Primary keywords:
cycle-sequence | directory | key-information | information | memory | module | plugins | principal | security | serial | version
Print program information.
Note
As with all program commands, use of the command word program is optional; program list and list are both valid.
Program information is printed to the screen. This information can be captured in a log file with the program log-file command.
cycle-sequence
List the doubles indicating the cycle point and names of the cycle entries in the cycle sequence. This information is useful when installing FISH callback events
with the fish callback command. The following table lists the reserved cycle points:
Cycle Point Cycle Operation

-10 Validate the data structures
0 Determine a stable timestep
10 Equations of motion (or thermal bodies update)
15 Body coupling between processes
20 Increment time
30 Update the cell space
35 Create/delete contacts
40 Force-Displacement law (or thermal contact update)
42 Accumulate deterministic quantities
45 Contact coupling between processes
60 Second pass of equations of motion
70 Thermal calculations
80 Fluid calculations
directory
List the current working directory and the application directory.
key-information
Look for a valid Itasca security key directly connected to the computer and report all of the information on it. The key does not have to contain a valid license for
this code, it may be for any Itasca code.
information
General program settings and status, including the customer title and the number of target threasds to use.
memory
List the amount of memory that is actively being used.
module
List the module DLLs that are loaded.
plugins
List the plugin DLLs that are loaded.
principal keyword
List the six components of a stress tensor given principal values and directions. All three principal values must be given. Two directions are required:
intermediate f <keyword> ...
Specify the intermediate value. You may specify the intermediate direction with the following keywords:
azimuth f
The direction being specified as the normal to a plane given by azimuth and plunge, in degrees.
dip f
The direction being specified as the normal to a plane given by dip and dip-direction, in degrees.
dip-direction f
normal v
The direction specified direction as a normal vector.
plunge f
trend f
A synonym to azimuth
minimum f <keyword> ...
Specify the minimum value. You may specify the intermediate direction with the following keywords:
azimuth f
dip f
dip-direction f
normal v
plunge f
trend f
maximum f <keyword> ...
Specify the maximum value. You may specify the intermediate direction with the following keywords:
azimuth f
dip f
dip-direction f
normal v
plunge f
trend f
security
Look for a valid license (using the current configuration settings) and report the contents of the license if found. The license may direct (local key) or network
(network key).
serial
List the serial number of the security key.
version
List the full program version information. This information should be reported if a problem arises while using the code.
Usage Example
The following example illustrates how program list can be used. The example shows the use of the principal keyword which requires that all three stress components be
supplied, with two direction keywords supplied for each.
program list principal intermediate 1.1 dip 22.2 dip-direction 80 &

minimum 2.2 normal 1,3,1 &
maximum 3.3 azimuth 80 plunge 22.2
program load command

Syntax
program load keyword
Load a compatible DLL.
Note
As with all program commands, use of the command word program is optional; program load and load are both valid.
The DLLs can be a user-defined FISH function, contact model, constitutive model for zones or structural elements, framework module, or a framework GUI module.
The type of module being loaded must be specified with either the cmodel, contactmodelmechanical, function, guimodule, module or plotitem keywords.
Plugins are loaded into the program, and remain available until program shutdown. The list of currently loaded plugins is available by executing the program list
plugins command.
The "Tools/Plugins" menu of the user interface provides a general plugin manager dialog.
cmodel [keywordblock]
Load constitutive model DLLs. The plugin file prefix is model. The additional model will appear in the list of available models by executing the zone cmodel
list command in FLAC3D.
contactmodelmechanical [keywordblock]
Load mechanical contact model DLLs. The plugin file prefix is contactmodelmechanical3d in 3d and contanctmodelmechanical2d in 2d. As these contact models
apply to contacts between balls, pebbles, and wall facets, the PFC module must first be loaded (see the module keyword).
function [keywordblock]
Load one or more FISH function DLLs. The plugin file prefix is fish. A FISH function DLL may create one or more FISH intrinsics, that will appear in the list
available by executing the fish list intrinsics command.
guimodule [keywordblock]
Load framework GUI module DLLs. The plugin file prefix is guimodule3d in 3d and guimodule2d in 2d. In general, an engine module exists to drive each GUI
module and an engine module must be loaded before a GUI module (see the module keyword).
module [keywordblock]
Load framework engine [DR: provide definition of this term to CS; CS: put defintion into terminology scheme] module DLLs. The plugin file prefix is module3d
in 3d and module2d in 2d. The module will appear in the list available by executing the program list module command.
plotitem [keywordblock]
Load framework plot item DLLs. The plugin file prefix is plotitem3d in 3d and plotitem2d in 2d.
Keyword Block
The following keywords are available to affect how plugins of a given type are loaded.
Load the plugin DLL file named s. Either the full file name can be given, or the code will attempt to find a name matching the pattern "prefixname005.dll"
where s = name and the prefix matches the plugin type. If a full path is not given, the code will look in the executable directory and all subdirectories as
well as the current directory and all subdirectories for a match.
automatic
Attempt to load all plugins found matching "prefixname005.dll" where prefix matches the plugin type and name matches anything available. By default this
will scan the "exe64/plugins" directory of the installation location, and all subdirectories. This can be overruled with the directory keyword.
directory sd
Specify the directory to scan when using automatic. All subdirectories will also be scanned. The default directory is "exe64/plugins" directory of the
installation location.
program log command

Syntax
program log b <keyword>
Turn on/off logging. By default this setting is off.
Note
As with all program commands, use of the command word program is optional; program log and log are both valid.
If not explicity set, the program will put log output in a file named flac3d.log in the current directory. Information output to the console is logged in this ASCII file. Use
the program log-file command to specify a different log file name. See the program echo command for details on what information is output to the console.
If the log file is opened, then the following keywords are available to control what happens to any existing file with that name.
append
Information is added to the end of the log file. This is the default behavior.
truncate
Any existing log file is cleared before new information is added.
program log-file command

Syntax
program log-file s <keyword>
Specify the log file by name.
Note
As with all program commands, use of the command word program is optional; program log-file and log-file are both valid.
Logging must be activated with the program log on command [DR: check previous commmand is correct] to activate writing. If logging is active and the program.log-
file command is given, then the previous log file (if any) is closed and the new file s is opened.
If the log file is opened, then the following keywords are available to control what happens to any existing file with that name.
append
Information is added to the end of the log file. This is the default behavior.
truncate
Any existing log file is cleared before new information is added.
program mail command

Syntax
program mail keyword
Compose and send email messages.
Note
As with all program commands, use of the command word program is optional; program mail and mail are both valid.
This facility allows data files and FISH functions to send notification emails upon completion of notable tasks. FISH access to the mail facility is detailed in Mail
Utilities.
Email account settings provided with this command may also be specified in the "Email" section of the "Tools/Options" dialog.
account s
Set the user account name in the SMTP settings. For example, me@mycompany.com. This is the account information fo logging into your email account. This
information is stored for this user on this computer.
add keyword
Add an item to the email.
attachment s
Add the file s as an attachment.
bcc s
Add a "bcc" recipient.
cc s
Add a "cc" recipient.
to s
Add a "to" recipient.
body keyword
Set the email body.
file s
Set the message body by importing s.
string s
Set the message body to s.
clear
Clear the current mail variables, including body, recipient list and attachment list.
domain s
Set the company domain name. For example, smtp.mycompany.com or 192.197.32.6. This information is stored for this user on this computer.
from s
Set the address corresponding to the email account. In many cases this is the same information as the account login information (given with the account
keyword); in those cases the from address does not need to be specified.
host s
Set the SMTP host name. For example, mycompany.com. This information is stored for this user on this computer.
password
Set the user password for the email account. A special prompt will be given, without normal keyboard echo. This information is encrypted and stored for this user
on this computer.
port i
Set the SMTP port. The default value is 25. This information is stored for this user on this computer.
remove keyword
Remove an item from the email.
attachment s
Remove the attached file s.
bcc s
Remove a "bcc" recipient.
cc s
Remove a "cc" recipient.
to s
Remove a "to" recipient.
send
Validate the mail settings, compose the message, and send the message.
subject s
Set the message subject.
program notice command

Syntax
program notice b
Set the notice state.
Note
As with all program commands, use of the command word program is optional; program notice and notice are both valid.
By default, informational messages are written to the console to inform the user of the status of specific operations. By disabling notices, these messages are not output.
program pagination command

Syntax
program pagination b
Set the pagination state.
Note
As with all program commands, use of the command word program is optional; program pagination and pagination are both valid.
Pagination, or dividing output written to the console to another page, occurs when the information to be written surpasses the space allotted for the console. By default,
pagination is active.
program pause command

Syntax
program pause <keyword>
Pause command processing.
Note
As with all program commands, use of the command word program is optional; program pause and pause are both valid.
If no options are specified, then processing of a data file will stop at the point where the program.pause command is encountered, and the program will enter interactive-
command mode, in which commands can be typed on the keyboard at the command prompt in the Console Pane. When the program continue command is typed,
processing of the data file will resume.
The following options are also available.
key
Processing of the data file will stop at the point where the program.pause command was encountered, and the program will wait for the user to press a key. When
any key (except Shift + Esc) is pressed, processing of the data file will resume. If Shift + Esc is pressed, all processing will be aborted (including the processing
of any data files that had been paused), and the program will enter interactive-command mode.
time f
If the optional keyword time is specified, processing of the data file will stop for f seconds and then resume. If Shift + Esc is pressed before f seconds have
elapsed, all processing will be aborted (including the processing of any data files that had been paused), and the program will enter interactive-command mode. If
the space bar is pressed, processing of the data file will continue.
program playback command

Syntax
program playback s
Play back a record file.
Note
As with all program commands, use of the command word program is optional; program playback and playback are both valid.
When supplying s, if no extension is specified, then ".record" will be assumed.
An ASCII record file representing a "playback" of input to the model is read, theoretically exactly duplicating the steps taken to create the model state from which the
record file was derived.
Record files may be generated in a number of ways.
l They are generated by the "Bundle Pack" command on the "Tools" menu.
l They may be copied from the output of a model list record commands command
l They may be copied or saved State Record pane.
l They may be stripped from the header of a save file.
program quit command

Syntax
program quit
Close the program.
Note
As with all program commands, use of the command word program is optional; program quit and quit are both valid.
All information will be lost unless a model save command is issued prior to the program.quit command. This is a synonym for program stop and program exit.
program return command

Syntax
program return
Return program control.
Note
As with all program commands, use of the command word program is optional; program return and return are both valid.
If the call stack is more than one level deep (that is, the file currently being processed was called by another file), then command processing returns to the calling file. If
the call stack is only one level, command processing is returned to the command prompt in the Console Pane. The program return command is assumed to be present at
the end of any data file.
The program return command will also cause an exit from a command/end command section in a FISH function.
program stop command

Syntax
program stop
Close the program.
Note
As with all program commands, use of the command word program is optional; program stop and stop are both valid.
All information will be lost unless a model save command is issued prior to the program.stop command. This is a synonym for program quit and program exit.
program system command

Syntax
program system keyword ...
Send commands to DOS.
Note
As with all program commands, use of the command word program is optional; program system and system are both valid.
This command allows the user to access the underlying command-driven operating system (DOS, under Windows). The contents of s and other string tokens are passed
directly to the system, and the text output is redirected to the screen. Some common commands used in place of s are dir, copy, del, etc. The following optional
keywords apply.
s ...
If a string is given, this will be passed directly to DOS. Multiple strings will be concatenated and passed as multiple tokens.
clone s ...
If the clone keyword is given, then a clone of the current program is spawned, and the contents of s are passed as arguments.
timeout i
If the timeout keyword is given, i is the number of seconds the code will wait for the process to complete before shutting down the process and moving on. If i = -
1, the code will wait forever. If i = 0, the code will spawn the process and move on immediately, leaving the process to run in parallel. In this last case, text output
from the program will not be captured. This option can be used with either the s option or the clone option.
Warning
Do not use these commands to modify files that FLAC3D is currently reading.
program threads command

Syntax
program threads <keyword>
Set the number of threads for calculations and plotting.
Note
As with all program commands, use of the command word program is optional; program threads and threads are both valid.
automatic
The number of threads reported by the operating system is used. Note that if hyper-threading is active, this can be twice the actual number of processors and cores
available. This setting is stored across runs — if modified the given setting will be used the next time the code is launched.
Use i processors.
program undo command

Syntax
program undo 
Undo commands.
Note
As with all program commands, use of the command word program is optional; program undo and undo are both valid.
If possible, this command undoes the last i lines of commands sent to the command processor. These could be commands typed at the command prompt or commands
issued via the user interface. The undo operation is performed by "playing back" the record of interactive commands recorded since the last model reset or save state,
minus the last i step(s). i is optional and defaults to 1 if omitted.
A call to a data file is interpreted as a single line by undo (that is, it is not "expanded" into its component commands for the purposes of undo). During playback,
commands that caused an error previously will not halt processing, though error reporting will still occur as before. [DR: review previous description; discuss with CS if
improvement/correction is needed]
If a model save file has been created from an allowed state, undo will start by restoring that file by executing a model restore. You can therefore not undo past that
point.
Note
undo is not always available.
l Commands that were interrupted in an unsafe way will prevent the undo playback.
l You cannot undo past a model restore.
l It is possible for undo to fail or result in a different model state if the execution environment has changed.
l Save states created during states when the model new command is not allowed (for example, while processing a FISH command/end.command) cannot be used
as a starting point for an undo.
l Be aware that if you are using this command directly (by typing undo at the command prompt), no check is made to see how long the playback will take.
program warning command

Syntax
program warning b
Set the warning state.
Note
As with all program commands, use of the command word program is optional; program warning and warning are both valid.
By default, warnings are shown in the console and also raise a "Warnings" dialog box to inform the user that the operations undertaken may have unintended
consequences; the user should be aware of the circumstances. By disabling the warning state, these messages are not output.
Project
This group of commands control the current project state. The project state is not affected by the model new or model restore commands. Plots are stored in the project
along with the list of data files. The project is saved in a project file which is separate from the model save file.
l Commands
Commands
These commands examine or modify the general project state. The project state is distinct from the model state (information cleared or reset on a model new command) and
the program state (information that remains throughout this instance of the program). Project information is saved and restored as part of the project file. Changes to the model
state does not affect the project state. Some project settings are stored and will persist to the next program execution, but they will be overwritten by any saved project
restored.
Project Commands
project execute
Execute the current project.
project list
List project information.
project new
Clear program-state information.
project restore
Restores the project file name s .
project save
Save the current project to a file.
project save-plugins
Save the currently loaded plugins with the project file.
l project execute command

l project list command
l project new command
l project restore command
l project save command
l project save-plugins command
project execute command

Syntax
project execute <suppress>
Execute the current project. This command is specific to the Itasca user interface, as described below.
The user interface will automatically target any data file whose name begins with the substring master. These files are presumed to be the(s) driver of the entire project
to be called on a project execute. A data file called projectmaster will be created that calls all master data files, and this will be called by the system.
The suppress keyword can be used to suppress echo while processing this file, as with the program call command.
project list command

Syntax
project list information
List project information. This information includes: the project file name and location, the log status, and echo status.
project new command

Syntax
project new <force>
Clear program-state information. Project information is cleared but the model information remains unchanged. The optional force keyword suppresses the confirmation
dialog and automatically resets the project if it has changed since the last time it was saved.
project restore command

Syntax
project restore s
Restores the project file name s. If a file extension is not specified, the extension f3prj will be assumed. This will clear the current project (including the current model
state) and load the specified project.
project save command

Syntax
project save s
Save the current project to a file. The current model state will not be saved automatically with the command, just the current project state. If the filename given is not
the same as the current project, the current project will become s.
project save-plugins command

Syntax
project save-plugins b
Save the currently loaded plugins with the project file. This is a global setting that is set in the registry. It also impacts loading loaded gui plugins - if set the false gui
plugins are not loaded on a restore as well. The default value is true. In general it is advisable to save plugins in the project file and load gui plugins.
Range
Ranges are command constructs, or sub-structures that are used within commands to filter the objects to which the commands are applied. They are presented in detail in this
section, while the documentation of all range elements are given here.
Table
The table logic supports the creation and manipulation of tables, which are indexed arrays of pairs of floating-point numbers (denoted for convenience as x and y). Each table
entry (or (x,y) pair) also has a sequence number (integer in the range [1, 2, . . . , N], where N is the number of items in the table).
Multiple tables may be defined via multiple commands. Each table has a unique ID number. In addition, each table also has a string representing the table name, which can be
used in place of the table ID for most commands that operate upon tables.
The contents of a history may be copied to a table via the history export command. Also, the contents of an ASCII file may be copied to a table via the history import
command.
l Commands
l FISH Functions
Commands
Tables are essentially a named list of (x,y) value pairs. These pairs can be in any order and looked up by index. It is more common for these pairs to be ordered by increasing x
values, in which case an efficient general lookup of a y value based on an x value can be performed by linearly interpolating between given values.
Tables are used in many constitutive models to specify general material behavior as a function of an evolution parameter. They can also be used to store data for later display.
Table Commands
table add
Add an entry to the end of table s .
table clear
Remove all entries of from table s .
table delete
Delete table s .
table export
The contents of the specified table are output to file...
table import
Read file sfile into table s .
table insert
Insert an entry into table s , sorted by its x-value.
table label
Set a label for table s .
table list
List table information.
table position
Substitute the specified (x,y) pair for the stored x- and...
table sort
Cause all entries in table s to be sorted in...
l table add command

l table clear command
l table delete command
l table export command
l table import command
l table insert command
l table label command
l table list command
l table position command
l table sort command
table add command

Syntax
table s add v2 ...
Add an entry to the end of table s. The x- and y- values of the entry are the x- and y- components of the two-dimensional vector v2. Any number of two-dimensional
vectors can be specified.
table clear command

Syntax
table s clear
Remove all entries of from table s.
table delete command

Syntax
table s delete
Delete table s.
table export command

Syntax
table s export sfile <keyword> ...
Primary keywords:
append | truncate | csv
The contents of the specified table are output to file sfile, with default file extension ".tab". The format of the output is compatible with the table import command.
The output assumes that the x-increment is irregular so that the values are output as (x,y) pairs. If the file s already exists, data will be appended to the end of the file
(default behavior or when the optional keyword append is given). The file will be overwritten if the optional keyword truncate is used. In addition, the format can be
changed to comma-separated value format with the csv keyword.
append
Data appended to the end of the file. append is the default option.
truncate
Any previously existing file is replaced.
csv
The exported table is formatted in standard CSV format, for easy import into other applications.
table import command

Syntax
table s import sfile
Read file sfile into table s.
The file must be formatted as described below, and has the ".tab" extension by default. The files contents are added to any existing table data.
The file sfile must be formatted and organized as follows:
Line 1 - This line will be taken as the label of the table, and can be of any length.
Line 2 - Give two white space separated values, namely the number of points followed by the assumed interval between them. If the interval is specified as 0.0, then
unevenly spaced pairs are assumed to follow.
Line 3 - Give the table y-value. The x-value is calculated as equally spaced values of time based on the step input from line 2. If the step is specified as 0.0, then it is
assumed that the step is not constant, and the values for the remaining lines are read as pairs separated by white space.
table insert command

Syntax
table s insert v2 ...
Insert an entry into table s, sorted by its x-value.
If an entry is to be inserted with an identical x-value to an existing table x-value, the table entry is replaced with the new entry. The x- and y- values of the entry are the
x- and y- components of the two-dimensional vector v2. Any number of two-dimensional vectors can be specified.
table label command

Syntax
table s label slabel
Set a label for table s.
The table identifier is not changed. The table label is used during output and plotting for a more verbose description of the table contents.
table list command

Syntax
table <s > list
List table information.
If no table identifier is provided a list of all tables is output. Otherwise the contents of the specified table are output.
table position command

Syntax
table s position i v2
Substitute the specified (x,y) pair for the stored x- and y-values in the i th entry of table s.
If the i th entry does not exist, then sufficient entries to encompass the given sequence number are appended to the table and the given (x,y) pair is installed.
table sort command

Syntax
table s sort
Cause all entries in table s to be sorted in order of increasing x-value.
FISH Functions
l Table Utilities
Table Utilities
table(INT/STR/TAB_PNT,FLT)
Get/set a table entry.
table.clear(INT/STR/TAB_PNT)
Clear a table.
table.create(INT/STR)
Create an empty table.
table.delete(INT/STR/TAB_PNT)
Delete a table.
table.find(INT/STR)
Find a table.
table.get(INT/STR)
Get a table.
table.id(INT/STR/TAB_PNT)
Get the table ID.
table.label(INT/STR/TAB_PNT)
Get/set the table label.
table.name(INT/STR/TAB_PNT)
Get the table name.
table.size(INT/STR/TAB_PNT)
Get the table size.
table.value(INT/STR/TAB_PNT,INT)
table.x(INT/STR/TAB_PNT,INT)
Get/set the x -value of a table entry.
table.y(INT/STR/TAB_PNT,INT)
Get/set the y -value of a table entry.
l table
l table.clear
l table.create
l table.delete
l table.find
l table.get
l table.id
l table.label
l table.name
l table.size
l table.value
l table.x
l table.y
table
Syntax
fy = table(t,fx)
table(t,fx) = fy
When getting a table entry, the table t is consulted, and a y-value corresponding to the given value of x is found by interpolation. If x is less than or greater than any x-
value in the table, then the y-value associated with the least or greatest x-value is returned. The result of this function is not defined if the table is not sorted by
increasing x-value.
When setting a table entry, an (x,y) pair is inserted into the first appropriate place in the table t (i.e., the new item is inserted between two existing items with x-values
that bracket the given value of x). The new item is placed at the beginning of the table or appended to the end if the given x is less than the lowest x or greater than the
greatest x, respectively. The number of items in the table is increased by one following execution of this statement. If table t does not exist, it is created, and the given
item is taken as the first entry. If the given x is identical to the stored x of an (x,y) pair, then the y-value is updated instead of a new pair inserted.
Note
A new table is created if a unique integer or string name is given as the first argument.
Returns: fy - y-value
Accepts: fy - y-value
Arguments: t - integer name, string name or table pointer
fx - x-value
table.clear
Syntax
v = table.clear(t)
Clear a table.

Arguments: t - integer name, string name, or table pointer
table.create
Syntax
tr = table.create(t)
Create an empty table.
Returns: tr - table pointer

Arguments: t - integer or string name
table.delete
Syntax
v = table.delete(t)
Delete a table.

table.find
Syntax
tr = table.find(t)
Find a table. A null pointer may be returned if the table does not exist. This differs from table.get where a table is created if the specified table does not exist.

table.get
Syntax
tr = table.get(t)
Get a table. If the table does not exist, a new table is created. This differs from table.find where a null pointer is returned if the table does not exist.

table.id
Syntax
i = table.id(t)
Get the table ID. A new table is created if a unique integer or string name is given.
Returns: i - table ID
table.label
Syntax
s = table.label(t)
table.label(t) = s
Get/set the table label. The label is assigned to the table name when the table is created and can be subsequently modified. The table label is used during output and
plotting for a more verbose description of the table contents. A new table is created if a unique integer or string name is given as an argument.
Returns: s - table label

Accepts: s - table label
table.name
Syntax
s = table.name(t)
Get the table name. The table name cannot be modified and is assigned when the table is created. A new table is created if a unique integer or string name is given as an
argument. The table label can be modified, on the other hand (see table.label).
Returns: s - table name

Accepts: s - table name
table.size
Syntax
i = table.size(t)
Get the table size. A new table is created if a unique integer or string name is given as an argument.
Returns: i - table size

table.value
Syntax
v = table.value(t,i)
table.value(t,i) = v
Get/set a table entry. A 2D vector must be supplied, or it is returned and entries are created if i is greater than table.size. A new table is created if a unique integer or
string name is given as the first argument.
Returns: v - vector of x/y value

Accepts: v - vector of x/y value
i - index of table entry
table.x
Syntax
f = table.x(t,i)
table.x(t,i) = f
Get/set the x-value of a table entry. i is the index of the table entry to be read or modified. Entries are created if i is greater than table.size.
Returns: f - x-value of a table entry

Accepts: f - x-value of a table entry
table.y
Syntax
f = table.y(t,i)
table.y(t,i) = f
Get/set the y-value of a table entry. i is the index of the table entry to be read or modified. Entries are created if i is greater than table.size.
Returns: f - y-value of a table entry

Accepts: f - y-value of a table entry
Structural Elements
An important aspect of geomechanical analysis and design is the use of structural support to stabilize a rock or soil mass. Structures of arbitrary geometry and properties, and
their interaction with a rock or soil mass, can be modeled with FLAC3D. This section describes the types of structural-support members (beams, cables, piles, shells, geogrids
and liners), or structural elements, available in FLAC3D, as well as the numerical formulation that supports the structural-element logic.
The structural elements can either be independent of, or coupled to, the grid representing the solid continuum. The structural-element logic is implemented with the same
explicit, Lagrangian solution procedure as the rest of the code (as opposed to an implicit, matrix-inversion procedure): the full dynamic equations of motion are solved, even
for modeling processes that are essentially static. Large displacements, including geometric nonlinearity, can be accommodated by specifying a large-strain solution mode;
and the full dynamic response of the system in the time domain can also be obtained with the dynamic-analysis option.
This overview section is organized as follows. We begin with a brief description of the six types of structural-support members provided by FLAC3D. This is followed, in
Terminology, by a high-level introduction describing the relevant terminology. The means by which structural elements are created and joined to one another is discussed next
(in Geometry Creation} and Joining Structural Elements). The discussion includes a description of how particular physical entities (e.g., physical beams) that are composed of
a collection of beam structural elements and nodes can be referred to — for purposes of plotting and specification of property and boundary conditions — as a single unit. The
general procedures are also described for specification of boundary and initial conditions (in Specifying Boundary and Initial Conditions), stresses in shells (in Stresses in
Shells), coordinate systems and sign conventions (in Local Systems and Sign Conventions), damping conditions (in Specifying Damping and Timestep Conditions), thermal
expansion (in Thermal Expansion in Structural Elements) and material properties (in Material Properties).
It is helpful to discuss the various conditions that can be prescribed at structural nodes before describing each of the types of structural elements in FLAC3D. This is done in
Structural Element Nodes. This section also includes a summary of the commands associated with nodes.
Each type of structural element is then described in detail in Beam, Cable, Pile, Shell, Geogrid, and Liner Structural Elements. This includes a description of the mechanical
behavior, the required properties and associated commands. Finally, simple examples are included at the end of each section, illustrating the application of each structural-
element type.
A detailed discussion of the general formulation of the structural-element logic in FLAC3D is provided in General Formulation of Structural-Element Logic. Users wishing to
implement more complex interaction between structural elements and the grid should consult this section to gain an understanding of the implementation procedure.
[\q \lceil\quad\ \{\q \lfloor\quad\

Throughout this section, matrices and vectors will be denoted by boldface type. The mathematical symbols , rfloor , uad and rfloor
will designate a rectangular matrix, diagonal matrix, column vector and row vector, respectively. Also, structure and element matrices will be described by uppercase and
[\ [
lowercase English alphabet characters. For example, b and \ designate structure and element stiffness matrices, respectively.
Types of Structural Elements
Six forms of structural-support members can be specified. Each of these members can be joined to one another and/or the grid.
1. Beam Structural Elements — Beam structural elements are two-noded, straight, finite elements with six degrees of freedom per node: three translational
components, and three rotational components. A physical beam (i.e., an arbitrarily curved, beam structure of isotropic material and bisymmetrical cross-
section) can be modeled as a collection of beam elements. Each element behaves as a linearly elastic material with no failure limit; however, it is possible
to introduce a limiting plastic moment, or even a plastic hinge (across which discontinuity in rotation may develop), between elements. Beam elements may
be rigidly connected to the grid such that forces and bending moments develop within the beam as the grid deforms, and they may be loaded by point or
distributed loads. Beam elements are used to model structural-support members in which bending resistance and limited bending moments occur, including
support struts in an open-cut excavation and general framed structures loaded by point or distributed loads.
2. Cable Structural Elements — Cable structural elements are two-noded, straight, finite elements with one axially oriented translational degree-of-freedom
per node. A physical cable (i.e., an arbitrarily curved, cable structure of isotropic material) can be modeled as a collection of cable elements. Each element
can yield in tension or compression, but cannot resist a bending moment. A shear-directed (parallel with the cable axis) frictional interaction occurs
between the cable and the grid. A cable may be anchored at a specific point in the grid, or grouted so that force develops along its length in response to
relative motion between the cable and the grid. Cables may also be point-loaded or pretensioned. Cable elements are used to model a wide variety of
structural-support members for which tensile capacity is important, including cable bolts and tiebacks.
3. Pile Structural Elements — Pile structural elements are two-noded, straight, finite elements with six degrees of freedom per node. A physical pile can be
modeled as a collection of pile elements. The stiffness matrix of a pile element is identical to that of a beam element; however, in addition to providing the
structural behavior of a beam, both a normal-directed (perpendicular to the pile axis) and a shear-directed (parallel with the pile axis) frictional interaction
occurs between the pile and the grid. In this sense, piles offer the combined features of beams and cables. In addition to skin-friction effects, end-bearing
effects can also be modeled (see Axially Loaded Pile). Piles may be loaded by point or distributed loads. Pile elements are used to model structural-support
members, such as foundation piles, for which both normal- and shear-directed frictional interaction with the rock or soil mass occurs.
A special material model is also available as an extension to the pile element to simulate the behavior of rockbolt reinforcement. This model includes
the ability to account for changes in confining stress around the reinforcement, strain-softening behavior of the material between the structural
element and the grid, and tensile rupture of the element.
4. Shell Structural Elements — Shell structural elements are three-noded, flat finite elements. Five finite-element types (2 membrane elements, 1 plate-
bending element and 2 shell elements) are available. A physical shell (i.e., an arbitrarily curved, shell structure of either isotropic or orthotropic material)
can be modeled as a faceted surface composed of a collection of shell elements. The structural response of the shell is controlled by the finite-element type
(to resist membrane loading only, bending loading only, or both membrane and bending loading). Each shell element behaves as an isotropic or orthotropic,
linearly elastic material with no failure limit; however, one can introduce a plastic-hinge line (across which a discontinuity in rotation may develop) along
the edges between elements, using the same double-node procedure as is applied to beams. Shell elements may be rigidly connected to the grid such that
stresses develop within the shell as the grid deforms, and they may be loaded by point loads or surface pressures. Shell elements are used to model the
structural support provided by any thin-shell structure in which the displacements caused by transverse-shearing deformations can be neglected.
5. Geogrid Structural Elements — Geogrid structural elements are three-noded, flat, finite elements that are assigned a finite-element type that resists
membrane but does not resist bending loading. A physical membrane can be modeled as a collection of geogrid elements. The geogrid elements behaves as
an isotropic or orthotropic, linearly elastic material with no failure limit. A shear-directed (in the tangent plane to the geogrid surface) frictional interaction
occurs between the geogrid and the FLAC3D grid, and the geogrid is slaved to the grid motion in the normal direction. A geogrid can be anchored at a
specific point in the FLAC3D grid, or attached so that stress develops along its surface in response to relative motion between the geogrid and the FLAC3D
grid. The geogrid can be thought of as the two-dimensional analog of a one-dimensional cable. Geogrid elements are used to model flexible membranes
whose shear interaction with the soil are important, such as geotextiles and geogrids.
6. Liner Structural Elements — Liner structural elements are three-noded, flat finite elements that can be assigned any of the five finite-element types
available for shell elements. A physical liner can be modeled as a collection of liner elements that are attached to the surface of the FLAC3D grid. In
addition to providing the structural behavior of a shell, a shear-directed (in the tangent plane to the liner surface) frictional interaction occurs between the
liner and the FLAC3D grid. Also, in the normal direction, both compressive and tensile forces can be carried, and the liner may break free from (and
subsequently come back into contact with) the grid. Liner elements are used to model thin liners for which both normal-directed compressive/tensile
interaction and shear-directed frictional interaction with the host medium occurs, such as shotcrete-lined tunnels or retaining walls.
An option that allows interaction with the FLAC3D grid on both sides of the liner is available with the liner element.
Terminology
With the addition of structural-element logic, FLAC3D can model the structural response of a mechanical system that is composed of a solid continuum and a framework of
load-carrying members. The solid continuum is represented by a collection of polyhedral-shaped zones, each of which is associated with a set of gridpoints. The framework is
represented by a collection of structural elements, each of which is associated with a set of nodes. The framework interacts with the solid continuum by means of links which
connect nodes to zones (not simply to gridpoints) or to other nodes.
Six degrees of freedom, composed of three translational components and three rotational components, are associated with each node. Each node also has its own local
orthogonal coordinate system. The node-local system provides the directions in which the equations of motion for the node are solved, and also defines the directions in which
the node can be attached to a target entity via a link. A link supports the following three attachment conditions, which are specified independently for each local direction of
its source node: free, rigid and deformable. See Structural-Element Links for a detailed description of structural-element links.
For most modeling situations, it is not necessary to specify link properties; instead, it is sufficient to create, position and assign properties to the desired structural elements.
Nodes (and links, if necessary) will be created automatically, and will inherit necessary information from the structural elements that use them.
Geometry Creation
The six types of structural elements provide the building blocks, or components, needed to model six types of physical items: beams, cables, piles, shells, geogrids and liners.
Each physical item is associated directly with a collection of component objects of the same type. For example, a cable is associated with a collection of cable elements,
whereas a liner is associated with a collection of liner elements. The association between physical items and their corresponding component objects is implemented by storing
two distinct identification numbers for each structural element:
1. id — The ID number refers to the physical item.

2. component-id — The component-ID number refers to the component object itself.
Properties may be specified for each type of physical item, and will be inherited automatically by the associated component objects. For example, the command
struct cable property grout-friction=30.0 range id=3
will assign a grout friction angle of 30 degrees to all cable elements thar are part of the cable with an ID number of 3, whereas the command
struct cable property grout-friction=30.0 range component-id=3
will assign a grout friction angle of 30 degrees to the single cable element with a component-ID number of 3.
The Beam, Cable, Pile, Shell, Geogrid, and Liner plot items allows one to view the six different element types, as well as the nodes and the links.
Beam, Cable and Pile Structural Elements
The geometry of beams, cables and piles is defined by their corresponding collection of component objects. The creation commands for all three of these types are identical,
and for simplicity the following examples will be for cable elements, but they will work just as well for pile or beam elements.
A single cable forming a straight line (made up of a number of individual elements) can be created using the structure cable create command, in one of three ways:
1. By specifying the two end locations (structure cable create by-line),

2. By specifying the ID numbers of two nodes at each end (structure cable create by-nodeids), or
3. By specifying a starting point, a direction, and a length (structure cable create by-ray).
Each create command takes an optional ID argument to denote the ID of the item to be created. If no ID is provided, the next available ID will be used. New nodes are created
automatically at uniformly spaced internal points along the line. If a node already exists at one of the end locations and is used by a element with the same ID as that given in
the command, a new node is not created at this location; otherwise, a new node is created.
A group of cables may be created from external geometric information, using the structure cable import command. For each line segment in the imported data, one or
more cable elements will be created. Current, data can be imported in one of three ways:
1. From an existing geometry set (structure cable import from-geometry). See the Geometry for details of creating a geometric set.
2. From a compatible CAD file (structure cable import from-file). The currently compatible file types are DXF, STL, and the Itasca Geometry format.
3. From an extruder set (structure cable import from-extruder). See the Extrude for how to use the 2D Extruder.
The following example, depicted in Figure 1, illustrates the association mechanism between nodes and structural elements. The nodes are not drawn in these plots. Instead, the
cable elements are drawn at 90% of their true length. Consider a curved cable, identified by an id of 5, that is composed of a collection of 7 elements and 8 nodes. Each
element stores the cable id of 5, as well as its own unique component-id. This can be seen by moving the mouse over an element and examining the information window. In
this way, the 7 elements are combined to form a complex, arbitrarily curved cable that can be referred to by the single id of 5.
../../../../../_images/overview-geom.png
Figure 1: Representation of a single curved cable identified by an ID of 5
The commands necessary to produce the model are shown in Figure 1 are given in selexample1-1.f3dat.
selexample1-1.f3dat: Creating a single curved cable identified by an ID of 5
model new
struct cable create by-line (0.0,4.0,0.0) (3.0,4.0,0.0) segments=2 id=5
There is no restriction that requires the end locations to lie within the FLAC3D grid; in fact, it is not necessary to have a grid at all. (Recall that the structural elements can
either be independent of, or coupled to, the grid representing the solid continuum.) When using the structure cable create command, if any of the nodes used by the
newly created elements lie within zones, these nodes will be linked to these zones, and the link properties will be set consistent with the corresponding element behavior
described in Beam, Cable, and Pile Structural Elements.
The most common reason to specify more than one segment between end locations is to improve accuracy, especially with piles and cables that are interacting with the host
medium. In this case, the distribution of shear forces along each pile or cable is a function, to some extent, of the number of nodes. The following rules-of-thumb have been
used to determine the number of nodes to use when modeling cables:
1. Try to provide approximately one node in each FLAC3D zone. The reasoning here is that since the zones are constant-stress regions, it is not necessary to
have more than one interaction point within a zone.
2. Try to provide two to three cable element within the development length of the cable. The development length of the cable is determined by dividing the
specified yield strength, , by the grout cohesive strength, . By following this procedure, failure by "pull-out" can occur if such conditions
arise. If the cable elements are too long, then only the yield failure mode of each element is possible. (This reasoning also applies to pile elements if used to
simulate the behavior of rockbolts.)
Shell, Geogrid and Liner Structural Elements
The geometry of shells, geogrids and liners is defined by their corresponding collection of component objects. The creation commands for all three of these types are identical,
and for simplicity the following examples will be for shell elements, but they will work just as well for geogrid or liner elements.
A single shell surface (made up of a number of individual elements) can be created using the structure shell create command, in one of four ways:
1. By specifying a set of surface zone faces, on which elements will be created (structure shell create by-face).
2. By specifying four existing structural nodes, forming a quadrilateral (structure shell create by-nodeids).
3. By specifying four points in space, forming a quadrilateral (structure shell create by-quadrilateral).
4. By specifying three points in space, forming a triangle (structure shell create by-triangle).
A shell surface may also be created from external geometric information, using the structure shell import command. For each line segment in the imported data, one or
more shell elements will be created. Current, data can be imported in one of two ways:
1. From an existing geometry set (structure shell import from-geometry). See the Geometry for details of creating a geometric set.
2. From a compatible CAD file (structure shell import from-file). The currently compatible file types are DXF, STL, and the Itasca Geometry format.
The most common way that shell-type elements are created in FLAC3D is with the structure shell create by-face command, which places them on zone faces. As an
example below, the geometry logic is used to create a 45 degree arc surface of shell elements. The command used as listed in selexample1-2.f3dat.
The geometry edge create by-arc command is used to create a 45 arc section in 8 segments. Then the geometry generate from-edges command is used to extrude
those edges in the y-direction into 8 segments. This description is then used by the structure shell import from-geometry command to create two triangular shell
elements per quadrilateral in the geometric description. Figure 2 shows the resulting shell elements.
model new
geometry select 'cyl'
geometry edge create by-arc origin (0,0,0) start (0,0,1) end (0.707,0,0.707) segments 8
geometry generate from-edges extrude (0,1,0) segments 8
struct shell import from-geometry 'cyl'
../../../../../_images/overview-cyl.png
Figure 2: Representation of a curved shell created by generating shell elements using a geometry description
Joining Structural Elements to One Another and to the Grid
Structural elements can be joined to one another either by sharing a node or by having one of their nodes linked to either another node or to a zone (see Terminology). If two
or more structural elements share a node, all forces and moments are transferred between the elements at the node. If it is necessary to limit or eliminate specific forces and/or
moments that are transferred between elements, then two separate nodes may be created and connected by a node-to-node link, and the appropriate attachment conditions set.
For example, if it is necessary to join two beams with a ball-joint, a node-to-node link can be added between the two beam end nodes, and the attachment conditions set in all
translational and rotational directions to be rigid and free, respectively. The same procedure can be applied when joining elements to the grid, except that in this case, a node-
to-zone link must be established between the node and the zone in which it lies. Node-to-node and node-to-zone linkage is controlled via the structure link command, and the
linkage conditions are described in Structural-Element Links.
The element creation commands ( structure cable create, structure beam create, etc.) are designed to maintain a clear separation between different physical items
being modeled. For example, if modeling two separate piles lying end-to-end, issue two separate structure pile create commands and specify two separate IDs (e.g., 1
and 2). This will result in the creation of two nodes lying in the same geometric location: one is used by pile-1; one is used by pile-2. Forces and moments will not be
transferred between the adjoining pile elements; instead, only forces will be transmitted into the surrounding zone at the common location. This mimics two separate piles
lying end-to-end. If a single pile is desired, then issue two separate structure pile create commands, but this time specify the same ID for each. This will result in the
creation of a single node that is shared by the pile element on each side of the common location. Forces and moments will be transferred between the adjoining elements. In
most modeling situations, the default link attachment conditions that are set by the element creation commands should not be modified, because these attachment conditions
produce the desired element-grid interaction for each particular element type.
Specifying Boundary and Initial Conditions
All boundary and initial conditions (with the exception of distributed loads applied to beam and pile surfaces, pressure loads applied to shell, liner, and geogrid surfaces, and
pretension forces applied to cables) are specified with the structure node command. The nodal conditions include
1. velocity-fixity conditions,
2. current velocity components, and
3. applied point loads (forces and/or moments).
There are two coordinate systems associated with each node: the global system and the node-local system. The node-local system is used to specify attachment conditions that
control how the node interacts with the grid. Also, the equations of motion are solved in these local directions. Therefore, one may fix or free velocities in these directions
only. The orientation of the node-local system is set automatically at the start of a set of cycles based on the type of elements that use the node. (See the structure node
command for a full description of these two systems.)
Velocities and rotations at nodes are fixed and freed in the node-local system using the structure node fix and structure node free commands. Velocities and rotations
are initialized to specified values in the global system using the structure node initialize command. Point loads are applied at nodes in either the global or the node-
local system using the structure node apply command.
Distributed loads are applied to elements using the structure cable apply (for example). Linear elements (beam, cable, or pile) can apply distributed loads in the element
local y and z directions. Planar elements (shell, geogrid, or liner) can apply pressure normal to the element surface. Note that in large-strain mode, the applied loads remain
aligned with the corresponding element system directions, which may rotate as the element location changes.
Pretension forces are applied to cables using the structure cable apply tension command. A positive pretension force places the cable into tension. See Pretensioning
for additional information.
Stresses in Shells
This section provides a brief introduction to shell behavior. Much of the information in this section is taken from Cook et al. (1989). Consult that text for a more complete
discussion.
A shell forms a curved surface in space. Usually a shell is thin in comparison with its span. Geometrically, a shell is described by its thickness, t, and the shape of the shell
mid-surface. If the mid-surface is flat, then the shell is called a plate. In general, a shell simultaneously displays bending stresses and membrane stresses. Bending stresses in a
shell correspond to bending stresses in a plate and produce bending and twisting moments and transverse-shear forces. Membrane stresses correspond to stresses in a plane-
stress problem: they act tangent to the mid-surface, and produce mid-surface tangent forces. These moments and forces per unit length are called stress resultants. There are a
total of eight stress resultants, which can be divided into those that arise from bending action and those that arise from membrane action. These will be described in the
following two sections.
Bending Action
We can account for the bending action of a shell in terms of plate-bending theory, which extends beam theory from one dimension to two as follows. Define a surface
coordinate system xyz such that x and y are orthogonal coordinates in the mid-surface and z is a direction normal to the mid-surface. Approximate the tangent plane to the
shell mid-surface as a flat plate subjected to "plate bending," meaning that external loads have no components parallel to the xy-plane and that σxx = σyy = σxy = 0 on the
mid-surface z=0. Such a flat plate, like a straight beam, supports transverse loads by bending action. Figure 3 shows stresses that act on cross sections of a plate whose
material is homogeneous and linearly elastic, subjected to plate-bending loading. Normal stresses σxx and σyy vary linearly with z, and are associated with bending moments
Mx and My. Shear stress σxy also varies linearly with z, and is associated with twisting moment Mxy. Normal stress σzz is considered negligible in comparison with σxx, σyy
and σxy. Transverse shear stresses σyz and σxz vary quadratically with z. Lateral load q includes surface load and body force, both in the z-direction.
../../../../../_images/bending-
action.png
Figure 3: Bending action in a shell showing: (a) stresses that act on a differential element of a homogeneous, linearly elastic plate subjected to plate-bending loading; and (b)
stress resultants corresponding with these stresses. (Stress resultants are drawn acting in their positive sense.)
Stresses in Figure 3 produce the bending stress resultants
M_x &= \int_{-t/2}^{+t/2} \sigma_{xx}

z \,dz
M_y &= \int_{-t/2}^{+t/2} \sigma_{yy}

z \,dz
(1)
and the transverse-shear stress resultants
Q_x &= \int_{-t/2}^{+t/2} \sigma_

{zx} \,dz
(2)
The bending resultants are moments per unit length, and the transverse-shear resultants are forces per unit length. Differential total moments and forces are Mxdy, Qxdy, and
so on, as shown in Figure 3. The following stress distributions are consistent with the assumptions of plate-bending theory, and satisfy (1) and (2):
\sigma_{xx} &= {12 M_{x} z \over t^3}
\sigma_{yy} &= {12 M_{y} z \over t^3}
\sigma_{zz} &\approx { 0 }
\sigma_{xy} &= {12 M_{xy} z \over t^3}
\sigma_{xz} &= {3 Q_x \over 2t} \biggl( 1 - \bigl( {2z/t} \bigr)^2

\biggr)
(3)
z=
Stresses σxx, σyy and σxy are largest at the surface \pm , whereas transverse-shear stresses, σxz and σyz, are largest at the mid-surface. Two points should be noted:
1. The differential equations of equilibrium for a plate element under a general state of stress indicate that σzz varies as a cubic parabola over the thickness of
the plate (Ugural 1981). But this stress, according to the assumptions of plate-bending theory, is negligible compared with the other stress components —
this assumption becomes unreliable in the vicinity of highly concentrated transverse loads.
2. σxz and σyz, according to the assumptions of plate-bending theory, are negligible compared with the other stress components; however, when these stresses
are integrated through the thickness, they produce transverse-shear stress resultants, Qx and Qy, that are of the same order of magnitude as the surface
loading and moments.
Membrane Action
We can account for the membrane action of a shell in terms of plane-stress conditions. Define a surface coordinate system xyz such that x and y are orthogonal coordinates in
the mid-surface, and z is a direction normal to the mid-surface. Approximate the tangent plane to the shell mid-surface as a flat plate subjected to plane-stress conditions,
meaning that the plate is loaded in its own plane. Such a flat plate supports these loads by membrane action. Figure 4 shows stresses that act on cross sections of a plate whose
material is homogeneous and linearly elastic, subjected to plane-stress loading. Normal and shear stresses σxx, σyy and σxy are constant through the thickness.
../../../../../_images/membrane-
action.png
Figure 4: Membrane action in a shell showing: (a) stresses that act on a differential element of a homogeneous, linearly elastic plate subjected to plane-stress loading; and (b)
stress resultants corresponding with these stresses. (Stress resultants are drawn acting in their positive sense.)
Stresses in Figure 4 produce the membrane stress resultants
N_{x} &= \int_{-t/2}^{+t/2} \sigma_{xx}

\,dz
N_{y} &= \int_{-t/2}^{+t/2} \sigma_

{yy} \,dz
(4)
The membrane resultants are forces per unit length. Differential total forces are Nxdy, Nydx and so on, as shown in Figure 4. The following stress distributions are consistent
with the plane-stress assumptions and satisfy (4):
\sigma_{xx} &= {N_{x}

\over t}
\sigma_{yy} &= {N_{y}

\over t}
\sigma_{xy} &= {N_{xy}

\over t}
\sigma_{zz} &= 0
(5)
General Shell Stresses
A shell structure simultaneously displays bending stresses and membrane stresses. The stresses and stress resultants acting in a general shell consist of a superposition of these
two loading modes (see Bending Action and Membrane Action). We can express these stress quantities in terms of a surface coordinate system xyz, where x and y are
orthogonal coordinates in the shell mid-surface and z is a direction normal to the mid-surface. The eight stress resultants can be divided into bending (Mx, My, and Mxy),
transverse-shear (Qx and Qy) and membrane (Nx, Ny and Nxy) stress resultants (see (1), (2), and (4)). The distribution of stress through the shell thickness follows from the
particular plate or shell theory used to model structural behavior. For both the Kirchhoff (thin-shell) and Reissner (thick-shell) theories, the stress distributions correspond
with a superposition of (3) and (5):
\sigma_{xx} &= {N_{x} \over t} + {12 M_{x} z \over t^3}
\sigma_{yy} &= {N_{y} \over t} + {12 M_{y} z \over t^3}
\sigma_{xy} &= {N_{xy} \over t} + {12 M_{xy} z \over t^3}
\sigma_{zz} &= 0
\sigma_{zx} &= {3 Q_x \over 2t} \biggl( 1 - \bigl( {2z/t} \bigr)^2

\biggr)
(6)
The stresses and stress resultants are sketched in Figure 3 and Figure 4, which also provide the sign convention for the stress resultants.
Stress Recovery Procedure
General shell stresses are computed in FLAC3D as follows. Refer to Stress Recovery Procedure for a more detailed description of the stress-recovery procedure. Each shell-
type structural element (shell, geogrid, and liner) has an associated finite-element stiffness matrix that defines the structural response (see Finite Element Stiffness Matrices).
Each shell-type element stores an internal force vector containing the generalized nodal forces acting on the element. During each timestep, the internal force vector is updated
by multiplying the element stiffness matrix with the incremental nodal displacements (nodal velocities multiplied by timestep). Note that shell stresses are not computed
during each timestep. Shell stresses are only computed by invoking a stress-recovery procedure that uses the internal force vector and the stiffness matrix to first compute
stress resultants, and then compute stresses using (6). These stress resultants are in equilibrium with the generalized nodal forces acting on the element.
The structural properties of shell-type elements include material properties (e.g., and for an isotropic material) and thickness. These properties are embodied in
the element stiffness matrix. If a structural property is modified during a simulation, then: (1) the generalized nodal forces and the stress resultants will remain the same; and
(2) the stresses will change only if the thickness is altered (see (6) and note that a change in thickness will affect the stresses even if the stress resultants do not change).
Note that the same procedure is used for all shell-type structural elements, shell, geogrid, and liner. The command and FISH examples below use shell, but any of the shell-
type keywords can be substituted.
The stress-recovery procedure requires that a consistent surface coordinate system be established prior to recovering any stress quantities. The surface coordinate system, xyz,
establishes x and y as orthogonal coordinates in the shell mid-surface, and z as normal to the mid-surface. The stress resultants are expressed in terms of this system. The
surface coordinate system is stored at each node, and can be set with the structure shell recover surface command and the FISH function
struct.node.system.surface. It can be printed with the structure node list system-surface command and plotted with the Shell, Geogrid, and Liner plot items.
After establishing the surface coordinate system over a patch of shell-type elements, stress resultants and stresses can be recovered for these elements with the structure
shell recover resultants and structure shell recover stress commands. These values can be queried, sampled as histories, and viewed as colored contours:
1. The values can be queried with the structure shell list resultant, structure shell list stress, and structure shell list stress-
principal commands, and the FISH functions struct.shell.resultant, struct.shell.stress, and struct.shell.stress.prin.
2. The values can be sampled as histories with the structure shell history command.
3. The values can be plotted as color contours with the Shell, Geogrid, or Liner plot item. Note that by default the plot items calculate an up-to-date value of
the resultants and stresses, but they can be set to show the current engine values in the plot item attributes.
The stress resultants and stresses become invalid after any step is taken, or if the surface coordinate system is altered; also, the stresses become invalid if the depth factor is
altered. In these cases, the values must be recovered again.
The stress-recovery procedure involves two steps: (1) creation of a consistent surface coordinate system; and (2) recovery of stress quantities. Both of these steps can be
limited to only apply to a range of shell-type elements. This allows one to control whether nodal averaging will occur between shell-type elements that use the same node. For
example, suppose that one wished to recover stresses throughout a capped cylindrical pressure vessel. The curvature across the cap edge is not continuous, and some of the
stresses across this edge are also not continuous. We could recover stresses separately in the cap and in the cylinder walls by performing two separate recovery operations for
the shell-type elements in these regions. When doing so, the z-direction of the surface coordinate system for the nodes along the edge would be different in each case.
Local Systems and Sign Conventions
Each element has its own local coordinate system. For beams and piles, this system is used to specify both the cross-sectional moments of inertia and applied distributed
loading. For shells, geogrids and liners, this system is used to specify orthotropic material properties and applied pressure loading.
Each node has its own node-local coordinate system. This system is used to specify attachment conditions that control how the node interacts with the grid, and also defines
the directions in which the equations of motion are solved. The orientation of the node-local system is set automatically at the start of a set of cycles based on the type of
elements that use the node (see the structure node command).
Responses are computed for nodes and for each type of element. Nodal responses include forces and moments, as well as translational and rotational velocities and
displacements. Forces and translational velocities are positive in the direction of the positive coordinate axes (either global or node-local) at the node. Positive moments and
rotational velocities follow the "right-hand rule": With the thumb pointing in the direction of the positive coordinate axis, the fingers are curled in the positive direction of
rotation. The double arrows in Figure 3 indicate the direction of the right-hand thumb to define the positive moment and rotation.
Responses for each type of element, and the associated sign conventions, are described in the sections named "Response Quantities" associated with each element type (later
in this chapter). The sign convention for force and moment distributions in beams and piles is shown in Beam Sign Conventions and Pile Sign Conventions, and the sign
convention for stress resultants in shells, geogrids and liners is shown in Bending Action and Membrane Action, where the xyz-axes correspond with the surface coordinate
system used during stress recovery (see Stress Recovery Proceture).
Specifying Damping and Timestep Conditions
The same damping conditions applied to the FLAC3D grid for static and dynamic analysis can also be applied to the structural elements. Note that the damping conditions
specified with the zone mechanical damping and zone dynamic damping command only apply to the zones, and the structure damping command must be used to
specify damping conditions for the structural elements.
The structure damping command can be used to change the damping condition, and the structure node damping-local command can be used to change the damping
constants at nodes for either local damping or combined damping. The timestep used for either static or dynamic analysis can be adjusted by using the structure safety-
factor command. Also, the computation of the rotational degree-of-freedom masses during dynamic analysis can be controlled by the structure scale-rotational-mass
command.
Thermal Expansion in Structural Elements
The effect of linear thermal expansion is implemented in the structural element formulation in FLAC3D. The temperature change occurs as a result of either heat conduction
or temperature re-initialization in the FLAC3D zones (for model configure thermal).
The effect of heat conduction in the structural element is not considered. It is assumed that the zone temperature is communicated instantaneously to the structural elements.
The temperature change generates thermal expansion/contraction in the structural element axial direction. The effect of the lateral expansion in the element is neglected, and
no other coupling takes place.
The incremental axial force generated by thermal expansion in the element is calculated using the formula (note that compression is positive for axial forces)
\Delta F = E A \alpha
\Delta T
\ \D
where E is the Young's modulus of the element, A is the cross-sectional area, is the linear thermal expansion coefficient, and elt is the temperature
increment for the element.
The structural-element nodal temperature increment is determined by interpolation of nodal temperature increments in the host zone, and stored in a structural node offset. For
a 1D structural element (i.e., beam, cable or pile), the temperature change is calculated as the average of values at the two nodes. The thermal strain increment of a 1D element
is computed as the product of the thermal linear expansion coefficient, temperature change for the step, and element length. For a 2D structural element (i.e., shell, geogrid or
liner), the temperature change is calculated as the average of values at the three nodes. The thermal strain increment of a 2D element is computed as the product of the thermal
linear expansion coefficient, temperature change for the step, and the lengths of the vectors from the element centroid to each node. (There are three of these vectors.) Thermal
strains, thermal strain increments and temperatures at structural nodes are not stored.
Note that when a large temperature increment is specified for cables, it is advisable to assign nonzero compressive yield strength to the cables in order to avoid compressive
yielding during the thermal expansion stage.
Material Properties
Properties are assigned to structural elements with the structure shell property command (or the equivalent for beam, cable, pile, geogrid, or liner elements). The range
logic can be used to limit the property settings to only those elements within the specified range. The properties for each structural-element type are described in detail in the
following sections. Note that all quantities must be given in a consistent set of units (see Table 1).
Table 1: Systems of units for some structural element properties

Property Unit SI Imperial
area length2 m2 m2 m2 cm2 ft2 in2
axial or shear stiffness force/disp N/m kN/m MN/m Mdynes/cm lbf/ft lbf/in
exposed perimeter length m m m cm ft in
moment of inertia length4 m4 m4 m4 cm4 ft4 in4
plastic moment force-length N-m kN-m MN-m Mdynes-cm ft-lbf in-lbf

yield strength force N kN MN Mdynes lbf lbf
Young's modulus stress Pa kPa MPa bar lbf/ft2 psi
where, 1 bar = 106 dynes/cm2 = 105 N/m2 = 105 Pa.
Type Specific Information
The following sections detail each type of structural element.
l Structural Element Nodes

l Structural Element Links
l Beam Structural Elements
l Cable Structural Elements
l Pile Structural Elements
l Shell-Type Structural Elements
l Shell Structural Elements
l Geogrid Structural Elements
l Liner Structural Elements
l General Formulation of Structural-Element Logic
l References
General Commands & FISH

l Commands
l FISH Functions
Structural Element Nodes

Mechanical Behavior
Six degrees of freedom, composed of three translational components and three rotational components, are associated with each node. All mass associated with the structural
elements is lumped at the nodes; each node inherits mass from the structural elements that use it.
There are two coordinate systems (the global system and the node-local system) associated with each node:
1. The global system can be used to specify generalized velocity and displacement boundary conditions, nodal positions, and applied loads. The global system
does not change throughout the course of a simulation.
2. The node-local system is used to specify attachment conditions that control how the node interacts with the grid. Also, the equations of motion are solved in
these local directions. Therefore, one may fix or free velocities in these directions only.
The orientation of the node-local system is set automatically at the start of a set of cycles (or when the model cycle 0 command is executed), based on the type of elements
x
that use the node. For beams and shells, the local system is aligned with the global system. For cables and piles, the local system is oriented such that (1) the -axis is
y
aligned with the average axial direction of all cable or pile elements using the node, and (2) the -axes
z are arbitrarily oriented in the cable or pile cross-sectional plane.
For geogrids and liners, the local system is oriented such that (1) the -axis is aligned with the average normal direction of all geogrid or liner elements using the node,
and (2) the -axes are arbitrarily oriented in the geogrid or liner tangent plane. When running in large-strain mode, the orientation of the node-local system is updated
automatically, based on the motion of the elements that use the node (unless this behavior is inhibited by the structure node system-local command).
In general, geometry creation is carried out as described in Geometry Creation. In addition, individual nodes can be repositioned by using the structure node initialize
position command. Any elements that are moved as a result of moving nodes will retain their default attachment conditions.
Accumulated displacement and rotation at nodes can be assigned initial values with the structure node initialize command. For example, these components can be
initialized to zero at any stage of analysis. Note that displacement values are not used as part of the computation cycle. Instead, incremental displacements are computed by
multiplying the nodal velocity by the timestep.
When selecting with the group range element, nodes are considered to be a member of a group by default if either they or any element the node is connected to is a member of
that group. The by keyword may be used to restrict this to a specific type of object.
Response Quantities
Nodal responses include displacement, velocity, position, and out-of-balance force. These quantities can be expressed in either the global or node-local coordinate system. The
nodal responses can be accessed via FISH and
l printed with the structure node list command;

l monitored with the structure node history command; and
l plotted with the various structural element plot items.
Commands & FISH

l Commands
l FISH Functions
Commands
Operations on structural element nodes.
Nodes are locations where elements interact, and where forces, masses are lumped for equations of motion. All six element types share the same node list. Unlike FLAC3D
gridpoints, nodes track six degrees-of-freedom (three rotational ones in addition to three translational).
Node Commands
structure node apply

Set generalized point loads for all nodes in the range.
structure node create
Create a structural node at location v .
structure node damping-local
Sets the local-damping factor to f for all nodes in...
structure node delete
Delete all nodes in the range.
structure node fix
Fix conditions for all nodes in the range, thereby preventing...
structure node free
Free fixed conditions for all nodes in the range.
structure node group
Assign all nodes in the range to the group with...
structure node hide
This command hides or un-hides all nodes in the range.
structure node history
Samples nodal responses.
structure node initialize
Initialize quantities on all structure nodes in the range.
structure node join
This command creates node-to-node links on all nodes in the...
structure node list
Show information about structural element nodes in the range.
structure node select
This commands selects or de-selects all structural nodes in the...
structure node system-local
Set the orientation of the node-local system for all nodes...
l structure node apply command

l structure node create command
l structure node damping-local command
l structure node delete command
l structure node fix command
l structure node free command
l structure node group command
l structure node hide command
l structure node history command
l structure node initialize command
l structure node join command
l structure node list command
l structure node select command
l structure node system-local command
structure node apply command

Syntax
structure node apply keyword <range>
Primary keywords:
force | force-edge | moment | remove | system
Set generalized point loads for all nodes in the range. Generalized point loads consist of an applied force and an applied moment. Pressure loading can be applied to
shell surfaces using the commands structure shell apply, structure geogrid apply, or structure liner apply. Distributed loads can be applied to beam and
pile surfaces using the command structure beam apply or structure pile apply. The following keywords are available to define generalized point loads.
force v <keyword>
applied force vector (in terms of system defined by the system keyword). You can use one of the following keywords to modify how v is applied to the node:
add
the vector v is added to the existing applied force vector at that node
multiply
the vector v is multiplied to the existing applied force vector at that node in a component by component multiplication
force-edge v <add>
the vector v is added as a force-per-unit-length to all edges that join nodes in the range. The forces assigned due to the edge will be lumped at the two nodes, with
each node receiving half. These forces are always in the global system and will set the nodes to the global system as with the structure node apply system
global command.
by default, these forces will overwrite the previous applied forces at the node; however, the add keyword can be given to add them to those currently present.
Note that if this changes the system they were applied under, the previous forces will not be corrected for the system change.
moment v <keyword>
applied moment vector (in terms of system defined by the system keyword). The following keywords can be used to modify how v is applied to the node:
add
the vector v is added to the existing applied moment vector at that node
multiply
the vector v is multiplied to the existing applied moment vector at that node in a component by component multiplication
remove keyword
an applied condition remains in effect until it is removed with this command. The following keywords are available to choose which applied condition is
removed:
force
removes any applied force condition on the node
moment
removes any applied moment condition on the node
system keyword
set the coordinate system in which the force and moment vectors are expressed. The default system is global. If the system is set to local, then in large-strain
mode, the force and moment vectors will remain aligned with the local system as it rotates.
local
global
structure node create command

Syntax
structure node create v <group s1 <slot s2 >>
Create a structural node at location v. Individually created nodes may be used to create elements using the by-nodeids command form (for example structure beam
create by-nodeids). When other command forms are used (for instance, by-line or by-ray), it is not necessary to separately create nodes when creating elements—
they are created automatically as the element is created.
There are two coordinate systems associated with each node: the global system and the local system.
1. The global system can be used to specify generalized velocity and displacement boundary conditions, nodal positions, and applied loads. The global system does
not change throughout the course of a simulation.
2. The local system is used to specify attachment conditions that control how the node interacts with the grid. The local system can also be used to specify velocity
boundary conditions. Also, the equations of motion are solved in these local directions; therefore, one may fix or free velocities in these directions only. Also note
that any degrees-of-freedom of a node with a rigid attachment condition (such as the node-local y- and z-axes of a node used by a cable, which are rigidly
attached to the zone in which the cable is embedded) cannot be fixed or freed, because the velocity of these degrees-of-freedom comes from the entity to which it
is attached.
The orientation of the local system is set automatically at the start of a set of cycles (or when the model cycle 0 command is executed) based on the type of elements
that use the node. For beams and shells, the local system is aligned with the global system. For cables and piles, the local system is oriented such that: 1) the x-axis is
aligned with the average axial direction of all elements using the node; and 2) the yz-axes are arbitrarily oriented in the cable or pile cross-sectional plane (see the first
figure below). For geogrids and liners, the local system is oriented such that: 1) the z-axis is aligned with the average normal direction of all elements using the node;
and 2) the xy-axes are arbitrarily oriented in the geogrid or liner tangent plane (see the second figure below).
Figure 1: Orientation of the node-local system for a node used by cables or piles
2d node
orientation
Figure 2: Orientation of the node-local system for a node used by geogrids or liners
(If more than one type of element is using a node, then the orientation of the local system will correspond with the first element type in the following list: liner, geogrid,
pile, cable, shell, and beam. Thus, if a node is being used by both a geogrid and a cable, then the orientation of the local system will correspond with that of a geogrid.)
When running in large-strain mode, the orientation of the local system is updated automatically based on the motion of the element that uses the node (unless this
behavior is inhibited by the structure node fix system-local keyword).
The optional keyword group may be used to assign a group name to the created node. The keyword slot may be used to specify what slot the group is assigned in; if not
specified, the group will be assigned to slot Default. Use of the group logic is described in Group.
structure node damping-local command

Syntax
structure node damping-local f <range>
Sets the local-damping factor to f for all nodes in the range (see the structure damping command). By default, f equals to 0.8.
structure node delete command

Syntax
structure node delete <range>
Delete all nodes in the range. FLAC3D will not allow nodes that are connected to structural elements to be deleted.
structure node fix command

Syntax
structure node fix keyword <range>
Primary keywords:
rotation | rotation-x | rotation-y | rotation-z | system-local | velocity | velocity-x | velocity-y | velocity-z
Fix conditions for all nodes in the range, thereby preventing these values from changing. If any translational/rotational velocity component is fixed, then all three
components of the translational/rotational velocity should also be specified in the local coordinate system via the structure node initialize command. If a fixed
displacement is required, the appropriate velocities should be initialized to zero. Degrees-of-freedom with a rigid attachment condition cannot be fixed; the rigid
condition overrides the fix condition.
rotation
rotational velocity in all three degrees-of-freedom (node local system)
rotation-x
rotational velocity about x-axis (node-local system)
rotation-y
rotational velocity about y-axis (node-local system)
rotation-z
rotational velocity about z-axis (node-local system)
system-local
inhibits automatic updating of the node-local system based on the elements that use the node. The default behavior is free.
velocity
translational velocity in all three degrees-of-freedom (node local system)
velocity-x
translational velocity in x-direction (node-local system)
velocity-y
translational velocity in y-direction (node-local system)
velocity-z
translational velocity in z-direction (node-local system)
structure node free command

Syntax
structure node free keyword <range>
Primary keywords:
rotation | rotation-x | rotation-y | rotation-z | system-local | velocity | velocity-x | velocity-y | velocity-z
rotation
rotational velocity in all three degrees-of-freedom (node-local system)
rotation-x
rotational velocity about x-axis (node-local system)
rotation-y
rotational velocity about y-axis (node-local system)
rotation-z
rotational velocity about z-axis (node-local system)
system-local
allows automatic updating of the node-local system based on the elements that use the node. This is the default behavior.
velocity
translational velocity in all three degrees-of-freedom (node local system)
velocity-x
translational velocity in x-direction (node-local system)
velocity-y
translational velocity in y-direction (node-local system)
velocity-z
translational velocity in z-direction (node-local system)
system-local
Is this finished? Should system-local be indented & not have a description?
structure node group command

Syntax
structure node group s1 <keyword> <range>
Primary keywords:
slot | remove
Assign all nodes in the range to the group with the name s1. Use of the group logic is described in Group. A node may only belong to one group in a given slot.
Assigning a node to a new group in that slot will cause it to be removed from its current group assignment. The command structure node list command lists the
existing node group names.
Both the group and the slot can be encoded into the single string s. To do this, use the composition 'slotname=groupname', where the name to the left of the equals sign
will be the slot and the name to the right will be the group.
slot s2
If supplied, the slot s2 keyword assigns the group to slot s2; if omitted, the group is assigned to the slot named Default.
remove
Remove all nodes in the range from the group named s. If no slot is specified, then that group will be removed from all slots in which it is found.
structure node hide command

Syntax
structure node hide <keyword>
Primary keywords:
b | undo
This command hides or un-hides all nodes in the range. By default, commands that use a range filter will skip hidden objects. This can be overruled with the use-hidden
keyword in the range specification.
if a boolean type is specified and if on, it hides all nodes in the range. If off, it un-hides (or shows) all elements in the range, and the use-hidden keyword is
applied to the range implicitly. on is the default if no keyword is given.
undo
this will reverse the operation of the last structure node hide command. FLAC3D keeps a maximum undo stack of size 12.
structure node history command

Syntax
structure node history <name s > keyword
Primary keywords:
displacement-x | displacement-y | displacement-z | displacement-rotational-x | displacement-rotational-y | displacement-rotational-z | force-x | force-y | force-z |

moment-x | moment-y | moment-z | position-x | position-y | position-z | velocity-x | velocity-y | velocity-z | velocity-rotational-x | velocity-rotational-y | velocity-
rotational-z
Samples nodal responses. These include displacement, velocity, position, and out-of-balance force.
If the optional name keyword is used, then the history can be supplied with a name to identify it later. If a name is not supplied, then one will be assigned automatically
based on the internally created ID number of the history object.
The particular node must be identified either by coordinates (position v) or by node ID (component-id i).
The sampled quantity is expressed in the global system, unless the optional keyword local is specified, in which case it is expressed in the node-local system. The local
keyword is not available for the position histories (position-x, position-y, position-z); these are always expressed in the global system.
translational displacement (x-component, global or node-local system)
translational displacement (y-component, global or node-local system)
translational displacement (z-component, global or node-local system)
displacement-rotational-x [keywordblock]
rotational displacement (x-component, global or node-local system)
displacement-rotational-y [keywordblock]
rotational displacement (y-component, global or node-local system)
displacement-rotational-z [keywordblock]
rotational displacement (z-component, global or node-local system)
force-x [keywordblock]
translational out-of-balance force (x-component, global or node-local system)
force-y [keywordblock]
translational out-of-balance force (y-component, global or node-local system)
force-z [keywordblock]
translational out-of-balance force (z-component, global or node-local system)
moment-x [keywordblock]
out-of-balance moment (x-component, global or node-local system)
moment-y [keywordblock]
out-of-balance moment (y-component, global or node-local system)
moment-z [keywordblock]
out-of-balance moment (z-component, global or node-local system)
position-x [keywordblock]
current position (x-component, global system)
position-y [keywordblock]
current position (y-component, global system)
position-z [keywordblock]
current position (z-component, global system)
translational velocity (x-component, global or node-local system)
translational velocity (y-component, global or node-local system)
translational velocity (z-component, global or node-local system)
velocity-rotational-x [keywordblock]
rotational velocity (x-component, global or node-local system)
velocity-rotational-y [keywordblock]
rotational velocity (y-component, global or node-local system)
velocity-rotational-z [keywordblock]
rotational velocity (z-component, global or node-local system)
Keyword Block
The initialization values specified with the structure node initialize command may be optionally modified with the keywords below. They apply (except where
noted with regard to the local keyword), to all of the major keywords of the command: displacement-rotational-x, displacement-rotational-y, displacement-
rotational-z, displacement-x, displacement-y, displacement-z, force-x, force-y, force-z, moment-x, moment-y, moment-z, position-x, position-y,
position-z, velocity-rotational-x, velocity-rotational-y, velocity-rotational-z, velocity-x, velocity-y and velocity-z.
component-id i
the particular node is identified by the component ID number. If this keyword is used, position should not be used.
local
specifies that the value will be taken in the local node coordinate system. By default, the value will be taken in the global coordinate system.
position v
the particular node is identified by (v) coordinates (the nearest node is taken). If this keyword is used, component-id should not be used.
structure node initialize command

Syntax
structure node initialize keyword <range>
Primary keywords:
displacement | displacement-x | displacement-y | displacement-z | displacement-rotational | displacement-rotational-x | displacement-rotational-y | displacement-

rotational-z | position | position-x | position-y | position-z | ratio-target | velocity | velocity-x | velocity-y | velocity-z | velocity-rotational-x | velocity-rotational-y |
velocity-rotational-z
Initialize quantities on all structure nodes in the range. Note that positions can only be specified in the global system.
Be aware that in the structural element logic, node velocities and displacements are stored in the local system. This means that changes to the local system can change
the values in the global system. This is particularly important because the node local system is not calculated for a given structural element system until the first cycle or
step, until then the node system is the default, which corresponds to the global system. When the first cycle command occurs, the node local system is adjusted and any
values of velocity that have been assigned will likely change their direction in the global system.
The best way to handle this is to emit a model cycle 0 command before assigning velocities to nodes—this will cause the local node system to be updated.
displacement v <[keywordblock]>
translational displacement
displacement-x f <[keywordblock]>
translational displacement (x-component)
displacement-y f <[keywordblock]>
translational displacement (y-component)
displacement-z f <[keywordblock]>
translational displacement (z-component)
displacement-rotational v <[keywordblock]>
rotational displacement
displacement-rotational-x f <[keywordblock]>
rotational displacement (x-component)
displacement-rotational-y f <[keywordblock]>
translational displacement (y-component)
displacement-rotational-z f <[keywordblock]>
translational displacement (z-component)
position v <[keywordblock]>
position of node (global system). This is used for positioning of a structural element grid; must be used after creating the node, but before executing any cycles.
Any node that is moved into a zone (see the structure link list command) will have its link deleted (if one is present) and will have a new link created with
attachment conditions corresponding to the type of structural element using the node (see this table). If more than one element type is using the node, then the
attachment condition will correspond with the first element type in the following list: liner, geogrid, pile, cable, shell, and beam. Thus, if a node is being used by
both a geogrid and a cable, then the attachment condition after moving this node will correspond with that of a geogrid.
position-x f <[keywordblock]>
x-coordinate of node (global system). See position above.
position-y f <[keywordblock]>
y-coordinate of node (global system). See position above.
position-z f <[keywordblock]>
z-coordinate of node (global system). See position above.
ratio-target f <[keywordblock]>
Sets the target local force ratio that is considered to be converged for mechanical calculations. The default value is 1e-4. A local force ratio of this value will
result in a convergence value of 1.0 for the node. See the convergence keyword in the model solve command.
velocity v <[keywordblock]>
translational velocity
velocity-x f <[keywordblock]>
translational velocity (x-component)
velocity-y f <[keywordblock]>
translational velocity (y-component)
velocity-z f <[keywordblock]>
translational velocity (z-component)
velocity-rotational-x f <[keywordblock]>
rotational velocity (x-component)
velocity-rotational-y f <[keywordblock]>
rotational velocity (y-component)
velocity-rotational-z f <[keywordblock]>
rotational velocity (z-component)
Keyword Block
The initialization values specified with the structure node initialize command may be optionally modified with the keywords below. They apply (except where
noted with regard to the local keyword), to all of the major keywords of the command: displacement, displacement-rotational, displacement-rotational-x,
displacement-rotational-y, displacement-rotational-z, displacement-x, displacement-y, displacement-z, position, position-x, position-y,
position-z, ratio-target, velocity, velocity-rotational-x, velocity-rotational-y, velocity-rotational-z, velocity-x, velocity-y and velocity-z.
add
the existing value of the parameter (of all nodes in the range) is set to its current value plus the given value. For example, one can add 0.1 to all node x-
displacements with the command structure node initialize displacement-x 0.1 add.
multiply
the existing value of the parameter (of all nodes in the range) is multiplied by the given value rather than being set to the given value. For example, one can
multiply all node x-displacements by a factor of 1.5 with the command structure node initialize displacement-x 1.5 multiply.
local
specifying the supplied value will initialize the node in local coordinates. This keyword may not be used with position (position, position-x, etc.).
gradient v
the value installed in each node in the range is valf = v + xgx + ygy + zgz, where the gradient keyword is given immediately after the the supplied value (val
here), and (x, y, z) are the components supplied by v, which specifies the reference position of the node. If the multiply keyword is also present, then the given
gradient is applied to the multiplier.
structure node join command

Syntax
structure node join <keyword> <range>
Primary keywords:
group | range-target | side
This command creates node-to-node links on all nodes in the range by attempting to find another node in the range that is at the same position. If found, and if the node
does not already possess a node-to-node link, then any existing link is deleted and a new node-to-node link is created. The new link is rigidly attached in all six degrees-
of-freedom to the target node.
Any links that exist on the target node are not modified.
The following keywords are available to modify the link creation process:
group s <slot s>
Specify a group assignment that will be made to all links created with this command. The slot keyword can be used to specify the slot used, otherwise the slot will
be Default. Use of the group logic is described in Group.
range-target keyword ...
Specify a range (as with the <range> phrase) that is used to select target nodes. Target nodes must fall within this range to be considered. Note that both a range-
target and a range may be given at the same time.
side i
Specify that any links created will be in side i of the element. This only applies to nodes attached to liner elements created with the embedded keyword. By
default, links are created in side 1.
structure node list command

Syntax
structure node list keyword <range>
Primary keywords:
apply | connectivity | damping-local | displacement | fixity | unbalanced-force | link | mass | position | stiffness | system-local | system-surface | velocity
apply <keyword>
list values of applied conditions on the node. One of the following keywords can be supplied to specify which apply condition is listed.
force
applied force on the node in the local system. This is the default if no keyword is specified.
moment
applied moments on the node in the local system
connectivity
lists the component-id numbers of all elements that are connected to this node
damping-local
local-damping factor of the node
displacement <keyword>
list both the translation and rotational (angular) displacements of the node. The following keywords, if present, allow the selection of the coordinate system these
are displayed in:
global
displays values in the global coordinate system
local
displays values in the local coordinate system; this is the default if not specified
fixity
velocity fixity in terms of nodal local coordinate system
unbalanced-force
unbalanced force and moment is displayed in terms of the nodal local coordinate system
link
lists the component-id numbers of any links that are attached to the node
mass
translational and rotational (angular) components are displayed in terms of the nodal local coordinate system
position <keyword>
position of the nodes in the range. There are two different position values possible; the following keywords (if present) allow you to select which position is
displayed. By default, the reference position is used.
current
the current position of the node, which is updated from the starting (or reference) position even in small strain mode
reference
the reference position of the node, which is updated only in large-strain mode. In small-strain mode, this is the starting location of the node and does not
change.
stiffness
translational and rotational (angular) components are displayed in terms of the nodal local coordinate system
system-local
the directions of the local coordinate system used by the nodes are displayed
system-surface
the directions of the surface coordinate system used during stress recovery are displayed. This is calculated with the structure shell recover surface,
structure geogrid recover surface, or structure liner recover surface commands.
velocity <keyword>
translational and rotational (angular) velocities are in terms of the global or nodal local (default) coordinate systems. The following keywords, if present, allow
the selection of the coordinate system these are displayed in:
global
displays values in the global coordinate system
local
displays values in the local coordinate system; this is the default if not specified
structure node select command

Syntax
structure node select <keyword> <range>
Primary keywords:
b | new | undo
This commands selects or de-selects all structural nodes in the range. Selected objects can be specified in a range filter by using the selected keyword. Objects that are
not selected can be specified in a range filter by using the deselected keyword.
if a boolean type is specified, and if on, it selects all nodes in the range. If off, it de-selects all elements in the range. on is the default if no keyword is given.
new
implies on. This will select nodes in the range and automatically de-select nodes not in the range.
undo
this will reverse the operation of the last structure node select command. FLAC3D keeps a maximum undo stack of size 12.
structure node system-local command

Syntax
structure node system-local keyword <range>
Primary keywords:
x|y|z
Set the orientation of the node-local system for all nodes in the range.
At the start of a set of cycles, the orientation of the node-local system is set automatically based on the type of elements that use the node; however, this behavior can be
overridden by setting the orientation of the node-local system with the structure node system-local command, and then using the structure node fix system-
local command.
At least two directions must be given. The third direction will be calculated to be perpendicular to the first two. Of the two directions given, the higher degree-of-
freedom will be corrected to ensure it is perpendicular to the other two.
xv
specifies the local x-direction
yv
specifies the local y-direction
zv
specifies the local z-direction
FISH Functions
FISH functions operating on extrusion nodes. The type specifiers used in the FISH function signatures are given in the FISH Type Index section.
Structural Node Functions
struct.node.acc.global(STRUCT_NODE_PNT<,INT>)
Get the acceleration of structure node expressed in a global...
struct.node.acc.local(STRUCT_NODE_PNT<,INT>)
Get the acceleration of structure node expressed in a local...
struct.node.apply(STRUCT_NODE_PNT<,INT>)
Get/set the generalized applied force expressed in a system defined by...
struct.node.apply.local(STRUCT_NODE_PNT)
Get whether the coordinate system in which generalized applied forces...
struct.node.convergence(STRUCT_NODE_PNT)
Returns the gridpoint convergence value, defined as the ratio of...
struct.node.damp.local(STRUCT_NODE_PNT)
Get/set the local damping factor of the structure node.
struct.node.disp.global(STRUCT_NODE_PNT<,INT>)
Get the displacement of structure node expressed in a global...
struct.node.disp.local(STRUCT_NODE_PNT<,INT>)
Get the displacement of structure node expressed in a local...
struct.node.extra(STRUCT_NODE_PNT<,INT>)
Get/set the value stored in the i th extra variable array...
struct.node.find(INT)
Get the structural node with internally assigned component-ID number i .
struct.node.fix(STRUCT_NODE_PNT,INT)
Get velocity-fixity flag expressed in the node-local system (degree-of-freedom component i1 ...
struct.node.fix.local(STRUCT_NODE_PNT)
Get/set the boolean flag for the local coordinate system fixity.
struct.node.force.unbal.global(STRUCT_NODE_PNT<,INT>)
Get the unbalanced force of structure node expressed in a...
struct.node.force.unbal.local(STRUCT_NODE_PNT<,INT>)
struct.node.group(STRUCT_NODE_PNT<,STR>)
Get/set the group name assigned to structure node sn in...
struct.node.group.remove(STRUCT_NODE_PNT,STR)
Remove the group s from structure node sn in all...
struct.node.head
Get the first structure node in the list of all...
struct.node.id(STRUCT_NODE_PNT)
Get the structural node ID number.
struct.node.id.component(STRUCT_NODE_PNT)
Get the structural node component-ID number.
struct.node.isgroup(STRUCT_NODE_PNT,STR<,STR>)
Check if the group name s is associated with the...
struct.node.link(STRUCT_NODE_PNT<,INT>)
Get the link associated with structure node sn .
struct.node.list
Get the list of all structure nodes in the model.
struct.node.mark(STRUCT_NODE_PNT)
Get/set the mark flag.
struct.node.mass.added(STRUCT_NODE_PNT<,INT>)
Get/set the extra mass in addition to the inertial mass...
struct.node.mass.local(STRUCT_NODE_PNT<,INT>)
Get the mass at the degree-of-freedom i ∈ {1, 2,...
struct.node.maxid
Get the maximum component-ID number assigned to any structural node...
struct.node.near(VEC+)
Get the structure node nearest v .
struct.node.next(STRUCT_NODE_PNT)
Get the next structure node after sn in the list...
struct.node.num
Get the total number of structure nodes in the model.
struct.node.pos(STRUCT_NODE_PNT<,INT>)
Get the current position vector for the structure node.
struct.node.pos.reference(STRUCT_NODE_PNT<,INT>)
Get the reference position vector for the structure node.
struct.node.ratio(STRUCT_NODE_PNT)
Get the local gridpoint mechanical convergence ratio.
struct.node.ratio.target(STRUCT_NODE_PNT)
Get/set the target mechanical force ratio in the node.
struct.node.resultant(STRUCT_NODE_PNT<,INT>)
Get stress resultants last calculated for the elements connected to...
struct.node.stiff.local(STRUCT_NODE_PNT<,INT>)
Get the stiffness of structure node expressed in a local...
struct.node.surface.valid(STRUCT_NODE_PNT)
Get a boolean flag for surface system validity; true if the...
struct.node.surface.xdir(STRUCT_NODE_PNT,VEC)
Set the orientation of the surface system of node sn such...
struct.node.system.local(STRUCT_NODE_PNT<,INT><,INT>)
Get the local coordinate system of the structure node.
struct.node.system.surface(STRUCT_NODE_PNT<,INT><,INT>)
Get/set the surface coordinate system of the structure node.
struct.node.temp.increment(STRUCT_NODE_PNT)
Get/set the the temperature increment that will be applied to...
struct.node.typeid
Get an identifier that uniquely determines the type of object.
struct.node.vel.global(STRUCT_NODE_PNT<,INT>)
Get the velocity of a structure node expressed in a...
struct.node.vel.local(STRUCT_NODE_PNT<,INT>)
l struct.node.acc.global
l struct.node.acc.local
l struct.node.apply
l struct.node.apply.local
l struct.node.convergence
l struct.node.damp.local
l struct.node.disp.global
l struct.node.disp.local
l struct.node.extra
l struct.node.find
l struct.node.fix
l struct.node.fix.local
l struct.node.force.unbal.global
l struct.node.force.unbal.local
l struct.node.group
l struct.node.group.remove
l struct.node.head
l struct.node.id
l struct.node.id.component
l struct.node.isgroup
l struct.node.link
l struct.node.list
l struct.node.mark
l struct.node.mass.added
l struct.node.mass.local
l struct.node.maxid
l struct.node.near
l struct.node.next
l struct.node.num
l struct.node.pos
l struct.node.pos.reference
l struct.node.pos.x
l struct.node.pos.y
l struct.node.pos.z
l struct.node.ratio
l struct.node.ratio.target
l struct.node.resultant
l struct.node.stiff.local
l struct.node.surface.valid
l struct.node.surface.xdir
l struct.node.system.local
l struct.node.system.surface
l struct.node.temp.increment
l struct.node.typeid
l struct.node.vel.global
l struct.node.vel.local
struct.node.acc.global
Syntax
m = struct.node.acc.global(sn<,i>)
Get the acceleration of structure node expressed in a global system.
Returns: m - matrix of acceleration with all degrees-of-freedom if the argument i is not assigned, or acceleration at the ith degree-of-freedom if the argument i is
assigned.
Arguments: sn - pointer to the structure node
i - degree-of-freedom, i ∈ {1, 2, . . . , 6}. The default is 1.
struct.node.acc.local
Syntax
m = struct.node.acc.local(sn<,i>)
Get the acceleration of structure node expressed in a local system.
Returns: m - matrix of acceleration with all degrees-of-freedom if the argument i is not assigned, or acceleration at the ith degree-of-freedom if the argument i is
assigned.
struct.node.apply
Syntax
m = struct.node.apply(sn<,i>)
struct.node.apply(sn<,i>) = m
Get/set the generalized applied force expressed in a system defined by struct.node.apply.local (degree-of-freedom i ∈ {1, 2, . . . , 6}). If the argument i is not
specified, a matrix is assigned/returned for all degrees-of-freedom.
Returns: m - matrix of apply with all degrees-of-freedom if the argument i is not assigned, or apply value at the ith degree-of-freedom if the argument i is assigned.
Accepts: m - matrix of apply with all degrees-of-freedom if the argument i is not assigned, or apply value at the ith degree-of-freedom if the argument i is assigned.
i - degree-of-freedom, i ∈ {1, 2, . . . , 6}.
struct.node.apply.local
Syntax
b = struct.node.apply.local(sn)
Get whether the coordinate system in which generalized applied forces are expressed is a local system.
Returns: b - boolean value

struct.node.convergence
Syntax
f = struct.node.convergence(sn)
Returns the gridpoint convergence value, defined as the ratio of the currenct local force ratio (struct.node.ratio), to the target force ratio
(struct.node.ratio.target). A value of 1 or less is therefore considered "converged".
Returns: f - local node mechanical convergence

Arguments: sn - a structural node pointer
struct.node.damp.local
Syntax
f = struct.node.damp.local(sn)
struct.node.damp.local(sn) = f
Returns: f - value of the local damping factor

Accepts: f - value of the local damping factor
struct.node.disp.global
Syntax
m = struct.node.disp.global(sn<,i>)
Get the displacement of structure node expressed in a global system.
Returns: m - matrix of displacement with all degrees-of-freedom if the argument i is not assigned, or displacement at the ith degree-of-freedom if the argument i is
assigned.
struct.node.disp.local
Syntax
m = struct.node.disp.local(sn<,i>)
Get the displacement of structure node expressed in a local system.
Returns: m - matrix of displacement with all degrees-of-freedom if the argument i is not assigned, or displacement at the ith degree-of-freedom if the argument i is
assigned.
struct.node.extra
Syntax
a = struct.node.extra(sn<,i>)
struct.node.extra(sn<,i>) = a
Get/set the value stored in the ith extra variable array of structure node sn.
Returns: a - value stored in extra variable slot i for structure node sn

Accepts: a - value to store in extra variable slot for structure sn
Arguments: sn - a pointer to the structure node
i - extra variable index to use. If not provided, index 1 is assumed.
struct.node.find
Syntax
sn = struct.node.find(i)
Get the structural node with internally assigned component-ID number i.
Returns: sn - pointer to the structure node with component-ID number i, or null if none was found
Arguments: i - structure node component-ID number
struct.node.fix
Syntax
i2 = struct.node.fix(sn,i1)
Get velocity-fixity flag expressed in the node-local system (degree-of-freedom component i1 ∈ {1, 2, . . . , 6}). Return value {1, 2, 3} denotes free, fixed, or slaved to
target velocity, respectively. Slaved conditions arise from rigid attachment conditions; degrees-of-freedom that are slaved cannot be fixed.
Returns: i2 - integer value

Arguments: sn - structure node pointer
i1 - degree-of-freedom component i1 ∈ {1, 2, . . . , 6}
struct.node.fix.local
Syntax
b = struct.node.fix.local(sn)
struct.node.fix.local(sn) = b
Returns: b - boolean flag: true for fixed node-local system, false for free node-local system
struct.node.force.unbal.global
Syntax
m = struct.node.force.unbal.global(sn<,i>)
Get the unbalanced force of structure node expressed in a global system.
Returns: m - matrix of unbalanced force with all degrees-of-freedom if the argument i is not assigned, or unbalanced force at the ith degree-of-freedom if the
argument i is assigned
struct.node.force.unbal.local
Syntax
m = struct.node.force.unbal.local(sn<,i>)
Get the unbalanced force of structure node expressed in a local system.
Returns: m - matrix of unbalanced force with all degrees-of-freedom, if the argument i is not assigned; or, unbalanced force at the i th degree-of-freedom, if the
argument i is assigned.
struct.node.group
Syntax
s = struct.node.group(sn<,slot>)
struct.node.group(sn<,slot>) = s
Get/set the group name assigned to structure node sn in slot slot. Use of the group logic is described in Group.
Returns: s - name of the group in slot slot. Will return None if no group has been assigned in that slot.
Accepts: s - name of the group in slot slot
Arguments: sn - pointer to a structure node
slot - optional name of the slot used. If not given, the slot name Default will be used.
struct.node.group.remove
Syntax
b = struct.node.group.remove(sn,s)
Remove the group s from structure node sn in all slots in which it is found.
Returns: b - true if the group was removed from one or more slots of the structure node, false if the group was not found in the structure node.
s - name of the group to remove
struct.node.head
Syntax
sn = struct.node.head
Get the first structure node in the list of all structure nodes. This function should be considered deprecated; it is provided mostly for backwards compatibility with old
data files. Instead, see the fish_statement_loopforeach statement and the struct.node.list function. See also the struct.node.next function.
Returns: sn - structure node pointer

Arguments: it - structure pointer
struct.node.id
Syntax
i = struct.node.id(sn)
Get the structural node ID number. This is defined as the ID number of the first element connected to the node and is not to be confused with the
component-ID number.
Note
Unlike other objects in FLAC3D, ID numbers for structural objects (elements, links, and nodes) refer to collections of elements and associated objects created together
and representing a single overall structure. For structural objects, the unique, internally assigned ID number associated with the object is called the component-ID
number. See the struct.node.id.component function.
Returns: i - structure node ID number

struct.node.id.component
Syntax
i = struct.node.id.component(sn)
Get the structural node component-ID number. This is a unique value assigned internally at creation, not to be confused with the ID number.
Note
number. See the struct.node.id function.
Returns: i - structure node component-ID number

struct.node.isgroup
Syntax
b = struct.node.isgroup(sn,s<,slot>)
Check if the group name s is associated with the zone gridpoint sn. By default, will check if there is a match in any slot; if the slot argument is specified, it will return a
match only in that slot. Use of the group logic is described in Group.
Returns: b - true if a match was found; false otherwise.
s - group name to check against
slot - an optional slot specification; if not given, the slot Default is assumed
struct.node.link
Syntax
l = struct.node.link(sn<,i>)
Get the link associated with structure node sn. Returns null if no link is associated with the structure node.
Returns: l - link pointer

i - Optional side indicator. Liner elements may optionally have links on two sides. If not specified this value defaults to 1, but for nodes attached to
embedded liners you may also give the value 2 to specify the link on the second side.
struct.node.list
Syntax
l = struct.node.list
Get the list of all structure nodes in the model. This is primarily used in the fish_statement_loopforeach statement.
Returns: l - a pointer to the list of all structure node
struct.node.mark
Syntax
b = struct.node.mark(sn)
struct.node.mark(sn) = b
Get/set the mark flag. Note that the SEL logic may modify this flag during command processing, cycling, and plotting.
Returns: b - boolean flag: true if the mark flag is on, false if the mark flag is off
Accepts: b - boolean flag: true if the mark flag is on, false if the mark flag is off
struct.node.mass.added
Syntax
f = struct.node.mass.added(sn<,i>)
struct.node.mass.added(sn<,i>) = f
Get/set the extra mass in addition to the inertial mass at the degree-of-freedom i ∈ {1, 2, . . . , 6} of in the node-local system.
Returns: v - extra mass at the degree-of-freedom

Accepts: v - extra mass at the degree-of-freedom
struct.node.mass.local
Syntax
f = struct.node.mass.local(sn<,i>)
Get the mass at the degree-of-freedom i ∈ {1, 2, . . . , 6} of in the node-local system.
Returns: v - mass mass at the degree-of-freedom

struct.node.maxid
Syntax
i = struct.node.maxid
Get the maximum component-ID number assigned to any structural node in this model. The next structural node created will be assigned this value plus one.
Note
number. See the struct.node.id.component function.
Returns: i - maximum component-ID number of any structural node in the model
struct.node.near
Syntax
sn = struct.node.near(v)
Get the structure node nearest v. Will return null if there are no structure nodes in the model.
Returns: sn - the pointer to the structure node closest to v

Arguments: v - a point in space
struct.node.next
Syntax
snnext = struct.node.next(sn)
Get the next structure node after sn in the list of all structure nodes in the model. Will return null if no more structure nodes follow. This function should be considered
deprecated; it is provided mostly for backwards compatibility with old data files. Instead, see the fish_statement_loopforeach statement and the struct.node.list
function. See also the struct.node.head function.
Returns: snnext - structure node pointer

struct.node.num
Syntax
i = struct.node.num
Returns: i - the total number of structure nodes in the model
struct.node.pos
Syntax
v = struct.node.pos(sn<,i>)
Get the current position vector for the structure node. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component
value.
Returns: v - current position vector or component
i - optional vector component, from 1 to 3
Component Access
f = struct.node.pos.x(sn)
Get the x-component current position vector of the structure node.
Returns: f - x-component current position vector

f = struct.node.pos.y(sn)
Get the y-component current position vector of the structure node.
Returns: f - y-component current position vector

f = struct.node.pos.z(sn)
Get the z-component current position vector of the structure node.
Returns: f - z-component current position vector

struct.node.pos.reference
Syntax
v = struct.node.pos.reference(sn<,i>)
Get the reference position vector for the structure node. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component
value.
Returns: v - reference position vector or component

Component Access
f = struct.node.pos.reference.x(sn)
Get the x-component reference position vector of the structure node.
Returns: f - x-component reference position vector

f = struct.node.pos.reference.y(sn)
Get the y-component reference position vector of the structure node.
Returns: f - y-component reference position vector

f = struct.node.pos.reference.z(sn)
Get the z-component reference position vector of the structure node.
Returns: f - z-component reference position vector

struct.node.pos.x
Syntax
f = struct.node.pos.x(sn)
Get the x-component position vector of the structure node.
Returns: f - x-component position vector

struct.node.pos.y
Syntax
f = struct.node.pos.y(sn)
Get the y-component position vector of the structure node.
Returns: f - y-component position vector

struct.node.pos.z
Syntax
f = struct.node.pos.z(sn)
Get the z-component position vector of the structure node.
Returns: f - z-component position vector

struct.node.ratio
Syntax
f = struct.node.ratio(sn)
Get the local gridpoint mechanical convergence ratio. This is the ratio of unbalanced force to force applied to the node.
Returns: f - local node mechanical convergence ratio

struct.node.ratio.target
Syntax
f = struct.node.ratio.target(sn)
struct.node.ratio.target(sn) = f
Get/set the target mechanical force ratio in the node. The default value is 1e-4. A local force ratio (struct.node.ratio) below this value is considered converged. See
struct.node.convergence.
Returns: f - target mechanical convergence ratio

Accepts: f - target mechanical convergence ratio
Arguments: sn - a structural node pointer
struct.node.resultant
Syntax
m = struct.node.resultant(p<,ires>)
Get stress resultants last calculated for the elements connected to this node.
Will return a 1x6 matrix of the stress resultants in this order: { Mx, My, Mxy, Nx, Ny, Nxy, } URGENT: DR: previous braced expression was flagged like this: :flag2:-
{ M_x,M_y,M_xy,N_x,N_y,N_xy }- : why?]. Note that the Qx and Qy1 terms are not valid at nodes because they are constant over an element.
Stress resultants are expressed in the node surface system; see the structure shell recover surface, structure geogrid recover surface, and structure
liner recover surface commands.
If the optional argument ires is provided, then the function will return that specific stress resultant (indexed as the order above) as a single value.
Note that stress resultants must be calculated with the structure shell recover, structure geogrid recover, and structure liner recover command. See
also the struct.shell.resultant.valid function.
Returns: m - a 1x6 matrix of all stress resultants, or a single value of a specific resultant
Arguments: p - a pointer to a structural element node
ires - an optional argument indicating a specific resultant index, from 1 to 6
struct.node.stiff.local
Syntax
m = struct.node.stiff.local(sn<,i>)
Get the stiffness of structure node expressed in a local system.
Returns: m - matrix of stiffness with all degrees-of-freedom if the argument i is not assigned, or stiffness at the ith degree-of-freedom if the argument i is assigned.
struct.node.surface.valid
Syntax
b = struct.node.surface.valid(sn)
Get a boolean flag for surface system validity; true if the surface system is valid, false if not. The surface system can be made valid by issuing a structure recovery
command.
Returns: b - boolean flag; true if the mark flag is on, false if the mark flag is off
struct.node.surface.xdir
Syntax
b = struct.node.surface.xdir(sn,v)
Set the orientation of the surface system of node sn such that the x-direction is aligned with the projection of the surface vector v onto the normal plane, which is
defined by the z-direction. This operation can only be performed upon nodes that have a valid surface system (to ensure that the z-direction always corresponds with the
average normal direction of at least one of the shell-type SELs using the node). A return value of true indicates success and false indicates failure.
Returns: b - boolean flag: true indicates success, and false indicates failure
v - vector
struct.node.system.local
Syntax
m = struct.node.system.local(sn<,i1><,i2>)
Get the local coordinate system of the structure node. The return value can be a matrix if both i1 and i2 are omitted, a vector if both i1 is assigned but i2 is omitted, or a
value if both i1 and i2 are assigned.
Returns: m - a matrix, vector, or value dependent on the arguments

i1 - degree-of-freedom, i1 ∈ {1, 2, 3}
struct.node.system.surface
Syntax
m = struct.node.system.surface(sn<,i1><,i2>)
struct.node.system.surface(sn<,i1><,i2>) = m
Get/set the surface coordinate system of the structure node. The return value can be a matrix if both i1 and i2 are omitted, a vector if both i1 is assigned but i2 is
omitted, or a value if both i1 and i2 are assigned.
Note that if the surface system is assigned, the system will be marked as valid. No check or correction is made to ensure the system is ortho-normal, this is the
responsibility of the user. A system that is not ortho-normal or is perpendicular to the elements will produce incorrect and unreliable results.
Returns: m - a matrix, vector, or value dependent on the arguments

struct.node.temp.increment
Syntax
f = struct.node.temp.increment(sn)
struct.node.temp.increment(sn) = f
Get/set the the temperature increment that will be applied to the structural node in the next timestep, causing elements connected to it to see changes in stress due to
thermal expansion. This value is cleared to zero after every step when thermal expansion stresses are applied.
Returns: f - temperature increment

Accepts: f - temperature increment
struct.node.typeid
Syntax
i = struct.node.typeid
Get an identifier that uniquely determines the type of object. For structure node, this will always return 1283546106.
This can be used with the type.pointer.id intrinsic to identify the object type a pointer refers to.
Returns: i - an identifier that determines the type of object
struct.node.vel.global
Syntax
m = struct.node.vel.global(sn<,i>)
Get the velocity of a structure node expressed in a global system.
Returns: m - matrix of velocity with all degrees-of-freedom if the argument i is not assigned, or velocity at the ith degree-of-freedom if the argument i is assigned
struct.node.vel.local
Syntax
m = struct.node.vel.local(sn<,i>)
Get the velocity of a structure node expressed in a local system.
Returns: m - matrix of velocity with all degrees-of-freedom if the argument i is not assigned, or velocity at the ith degree-of-freedom if the argument i is assigned
Structural Element Links

Introduction
A link is an object that links a source node to a target. Currently that target may be either another structural node or a zone, although more targets may be added in the future.
Each link utilizes the local system of its source node, and all link properties are specified with respect to this local system. Links implement the interactions that occur
between the different types of elements and the grid. In most cases it will not be necessary to create or modify links, because they will be created and their properties set
automatically by the elements that utilize them.
However, if one wishes to introduce a plastic hinge with full rotational freedom (such that two different rotation angles can develop on each side of the hinge point), then one
must create two separate nodes at this point, and create a node-to-node link between them and specify a normal-yield spring in the appropriate rotational degree-of-freedom,
and set the stiffness and yield strength of this spring equal to that of the plastic hinge. For these, and other more complex situations, we provide the following interface to the
link logic.
Each link contains six different possible attach conditions for each of the six degrees-of-freedom (three translational, and three rotation). The possible conditions are free (no
force transmitted), rigid (rigidly connected to the target location), and deformable (forces generated by a one-dimensional force-displacement law based on relative motion).
The behavior of a deformable condition is governed by a link model, of which there are currently four options: linear, shear-yield, normal-yield, and pile-yield. Note that a
link can only have one condition or model for each degree-of-freedom. Recursive chaining of rigid connections is allowed.
For the specific case of embedded liners, two links per node are possible. In this case, only one rigid connection per degree-of-freedom across all links is allowed.
Note that link model properties are, by default, assigned automatically based on the properties of the elements that are connected to their host nodes. Unless the interaction
type is incompatible, this will override any properties set manually via the command line or FISH. This happens any time the code performs a "geometry update," which is at
the start of cycling, and, if in large strain mode, at the start of every update interval during cycling. Because of this, the easiest way to customize link properties is to set the
properties in the elements attached to their host node. Otherwise, the user must make certain to override the default values after every update occurs by using a properly timed
FISH callback (see the fish callback command).
When selecting with the group range element, links are considered to be a member of a group by default if either they, the node they are connected to, or any element the node
is connected to is a member of that group. The by keyword may be used to restrict this to a specific type of object.
Whenever a link attempts to establish a connection to a target zone, it will search for a non-null zone for which the source node lies within a distance d of the zone’s
boundary. The value of d is obtained from the global value of zone tolerance (see the structure link tolerance-contact command) multiplied by zone size, where zone
size is the maximum x-, y-, or z-dimension of the zone bounding box. But note that such a nearby zone will be used only if the source node does not lie within or on the
boundary of any non-null zone. If the source node lies within the d-boundary of a zone, then the weighting functions used to transfer information from the link to the zone will
correspond with the location on the zone surface that is nearest to the node location.
Link Model Properties

Structural link deformable models are, by default, created automatically when links are created. The default type used in each degree-of-freedom depends on the element type
(see Default link attachment conditions for element types). Properties of deformable models are also, by default, set during initialization based on the properties of the
elements they are connected to. However, it is possible to override these defaults, both by changing the model and by changing the properties of existing models — see the
structure link attach and structure link property commands. The following properties are available to each of the currently available deformable link models.
Table 1: Properties available to each deformable link model

name properties
Linear area, stiffness
Normal Yield area, gap, stiffness, yield-compression, yield-tension
Pile Yield area, cohesion, friction, gap, stiffness
Shear Yield area, cohesion, cohesion-table, confinement-table, friction, friction-table, incremental-confinement-flag, perimeter, stiffness
Compression vs. Tension Direction

The Normal-Yield model properties can be somewhat confusing. In the context of the link model, the tension limit refers to the limiting positive value of the link force, and
the compression limit refers to the limiting negative value of the link force. Positive link forces are generated by positive relative incremental displacement, which is defined
as the difference between the target incremental displacement and the source incremental displacement (target minus source). This distinction occurs in the node-local
coordinate system. The result is that, depending on the local system and the model configuration, the "compression" limit might not refer to what one would instinctively think
of as compression when viewed from the element perspective.
For example, in general liner elements assign a nodal system with the z-direction pointing away from the zones. This means that the liner structure liner property
coupling-yield-normal property will map to the structure link property yield-compression property in the normal-yield deformable model. Figure 1 illustrates the
system.
../../../../../../_images/link-tension-compression.png
Figure 1: Mapping of liner coupling-yield-normal property to link model yield-compression property.
Manually setting link properties

As stated above, deformable link model properties are set automatically by FLAC3D during a geometry update, which happens during the validation stage of a cycle on the
first cycle taken and if in large strain mode at every update interval. Properties that have been set manually may be overridden at this time. It is currently not possible to keep
this from happening. You can, however, use FISH to restore your intended manual properties after each global update has occurred.
The fish callback command can be used to insert a FISH call during each cycle, in this case the callback should be after time index -2 but before -1 (see program list
cycle-sequence for a full list). The struct.was.updated FISH intrinsic can be used to determine if an actual full geometry update occurred at the start of that cycle.
Commands & FISH

l Commands
l FISH Functions
Commands
Operations on structural element links.
Links are how the structural element logic tracks interactions with surrounding objects. Links come in two types depending on what object they are interacting with. Currently
the structural element logic supports node->node links and node->zone links, but more interaction types will be added in the future.
Each link supports a different interaction in all six degrees-of-freedom—the coordinate system of a link is always the local coordinate system of the host node.
Link properties and interaction details are by default supplied by the element they are connected to.
Link Commands
structure link attach

Set attachment conditions for the specified link directions.
structure link create
Creates new links on structure nodes in the range.
structure link delete
Delete all links in the range.
structure link group
Assign all links in the range to the group with...
structure link hide
This commands hides or un-hides all links in the range.
structure link history
Samples relative displacement or force from a single degree-of-freedom in...
structure link list
List values and information about link objects in the range.
structure link property
List a property of a deformable force-displacement model in the...
structure link select
This commands selects or de-selects all links in the range.
structure link slide
Set the large-strain sliding flag.
structure link tolerance-contact
Set the tolerance used when establishing node-to-zone links.
structure link tolerance-node
Set the tolerance used when establishing node-to-node links.
structure link tolerance-slide
Set the tolerance used when updating node-to-zone links in response...
l structure link attach command

l structure link create command
l structure link delete command
l structure link group command
l structure link hide command
l structure link history command
l structure link list command
l structure link property command
l structure link select command
l structure link slide command
l structure link tolerance-contact command
l structure link tolerance-node command
l structure link slide-tolerance command
structure link attach command

Syntax
structure link attach keyword ... <range>
Primary keywords:
x | y | z | rotation-x | rotation-y | rotation-z
Set attachment conditions for the specified link directions. The current attachment condition will be replaced by the condition specified here. Conditions are specified in
keyword pairs, the first (keyword) being the degree-of-freedom and the second ([keywordblock]) being the type of condition to use. The following keywords are
available to specify the degree-of-freedom:
x [keywordblock]
translational x-direction, also degree-of-freedom 1
y [keywordblock]
translational y-direction, also degree-of-freedom 2
z [keywordblock]
translational z-direction, also degree-of-freedom 3
rotation-x [keywordblock]
rotational x-direction, also degree-of-freedom 4
rotation-y [keywordblock]
rotational y-direction, also degree-of-freedom 5
rotation-z [keywordblock]
rotational z-direction, also degree-of-freedom 6
Keyword Block
The attachment condition is given by the following values, which are applied to: rotation-x, rotation-y, rotation-z, x, y and z.
free
free
linear
deformable linear spring
normal-yield
deformable normal-yield spring
pile-yield
pile yield spring. This is only available in the x or y translational degrees-of-freedom, and the dependent model is automatically installed in y or z, respectively.
rigid
rigid
shear-yield
shear yield deformable spring (only available in translational degrees-of-freedom)
structure link create command

Syntax
structure link create keyword <range>
Primary keywords:
default-attach | on-nodeid | offset | side | target | group
Creates new links on structure nodes in the range. If the node already has a link associated with it, this will be ignored. Existing links can be removed with the
structure link delete command. If source and target ID numbers are not supplied, then the command will automatically look for valid targets on all potential new
links in the range.
default-attach b
By default a new link created with this command is given rigid connections in all six degrees-of-freedom if created on side on, and free connection in all six if
created on side two. By setting this keyword to true, links created will be given the default attachment conditions associated with the first element their host node
is connected to. This is not compatible with target node. Please note that this is required for elements to pass property values to the link models in individual
degrees-of-freedom. If not done, this will not happen even if the link models match those expected by the element.
on-nodeid i
Specify a specific node component-id number on which to create a link. If this keyword is used, the range phrase is not used. If the target keyword is used with a
specific id supplied, on-nodeid must be used to specify the source node.
offset v
When a specific target has not been specified, an offset vector can be used to search for a node or zone that does not lie in the location of the source node. The
location checked will be the source node position plus the offset vector v. Note that if a zone is the target and an offset is used, then the large strain sliding update
should be turned off using the sliding property of the element.
side i
Specify on which side of a node attached to an embedded liner element the link should attach to. The default is side 1. Must be 1 or 2.
target keyword
Identify the target entity. The default target zone will be used if target is not supplied.
zone 
Specify the link(s) should look for a zone target. If i is not specified, then a non-null zone that is within a distance δ of the source node is utilized. If i is
specified, then that zone is used if it is non-null and the source node is within a distance δ of its boundary. (See the preceding discussion for a definition of
δ.)
node 
Specify that the link(s) should look for a node target. If i is not specified, then a node that is within a distance δ of the source node is utilized. If i is
specified, then the two nodes must be near to each other for a link to be created. Near is defined as being within a distance δ of one another, where δ is the
global value of node tolerance (see the structure link tolerance-contact command). The attachment conditions of the new link are set to “rigid” for
all six directions if the link is on side 1, and "free" if the link is on side 2.
group s1 <slot s2 >
Assign the created link to the group named s1. If the optional slot s2 is supplied, the group is assigned to the slot named s2; if omitted, the group is assigned to the
slot named Default. Use of the group logic is described in Group.
Usage Example
The following example will create a link to zones on all links on side 2 of nodes connected to liner elements that have been assigned the group name First.
structure link create target zone side 2 range group 'First'
The following example will create a link to nodes, if there is another node at that location, for all nodes associated with the group name Connection.
structure link create target node range group 'Connection`
The following example will create a link between the node with component-id 5 and the first node found within a tolerance of its location.
structure link create on-nodeid 5 target node
The following example will create a link between the node with component-id 5 and the node with component-id 16.
structure link create on-nodeid 5 target node 16
structure link delete command

Syntax
structure link delete <range>
structure link group command

Syntax
structure link group s1 <keyword> <range>
Primary keywords:
slot | remove
Assign all links in the range to the group with the name s. Use of the group logic is described in Group. A link may only belong to one group in a given slot. Assigning
an element to a new group in that slot will cause it to be removed from its current group assignment. The structure link list command lists the existing link group
names.
slot s
Assign the group to slot s. If omitted, the group is assigned to the slot named Default.
remove
The specified group is removed from the specified slot. If no slot is specified, then the group will be removed from any and all slots it is in.
structure link hide command

Syntax
structure link hide <keyword> <range>
Primary keywords:
b | undo
This commands hides or un-hides all links in the range. By default, commands that use a range filter will skip hidden objects. This can be overruled with the use-hidden
keyword in the range specification.
if a boolean type is specified, and if on, it hides all links in the range. If off, it un-hides (or shows) all links in the range, and the use-hidden keyword is applied to
the range implicitly. on is the default if no keyword is given.
undo
this will reverse the operation of the last structure link hide command. FLAC3D keeps a maximum undo stack of size 12.
structure link history command

Syntax
structure link history <name s > keyword
Primary keywords:
displacement-x | displacement-y | displacement-z | displacement-rotational-x | displacement-rotational-y | displacement-rotational-z | force-x | force-y | force-z |

moment-x | moment-y | moment-z
Samples relative displacement or force from a single degree-of-freedom in a structural element link.
If the optional name keyword is used, then the history can be supplied with a name to identify it later. If a name is not supplied, then one will be assigned automatically
based on the internally created ID number of the history object.
The particular link must be identified either by coordinates (position v) or by ID (component-id i). In the case of coordinates, the closest available node to that location
is found, and the link associated with that node is used.
relative displacement in the local x degree-of-freedom
relative displacement in the local y degree-of-freedom
relative displacement in the local z degree-of-freedom
displacement-rotational-x [keywordblock]
relative angular displacement in the local x degree-of-freedom
displacement-rotational-y [keywordblock]
relative angular displacement in the local y degree-of-freedom
displacement-rotational-z [keywordblock]
relative angular displacement in the local z degree-of-freedom
force in the local x degree-of-freedom
force in the local y degree-of-freedom
force in the local z degree-of-freedom
moment in the local x degree-of-freedom
moment in the local y degree-of-freedom
moment in the local z degree-of-freedom
Keyword Block
The following keywords are available to specify which link will be used to take a history. displacement-rotational-x, displacement-rotational-y,
displacement-rotational-z, displacement-x, displacement-y, displacement-z, force-x, force-y, force-z, moment-x, moment-y and moment-z.
component-id i
the particular link is identified by the component ID number. If this keyword is used position should not be used.
position v
the particular link is identified by (v) coordinates (the nearest node is taken). If this keyword is used, component-id should not be used.
side i
specifies which side of the node indicated in position should be used to find the link. By default, side 1 is used.
structure link list command

Syntax
structure link list keyword <range>
Primary keywords:
attach | displacement | force | property | slide | slide-tolerance | source-node | state | target
attach
attachment conditions
displacement
relative displacement in each degree-of-freedom
force
force being exerted in each degree-of-freedom
property <s >
list link property associated with the current model. The value of s corresponds to the desired property. [DR: help to sort out what to do with next statement]
See :flag2:-Link to discussion of the link force-displacement models available here- for a list of properties associated with each of the deformable models
available.
slide
sliding flag
slide-tolerance
sliding tolerance
source-node
source node — node from which the link emanates
state
the failure state associated with each degree-of-freedom that has a deformable force-displacement model
target
link type: node-to-zone or node-to-node and the component-id of the specific target of this link
structure link property command

Syntax
structure link property keyword ... <range>
Primary keywords:
x | y | z | rotation-x | rotation-y | rotation-z
List a property of a deformable force-displacement model in the link at the degree-of-freedom specified in keyword. A list of properties available to each link
constitituve model is found in Structural Element Link Properties.
x <[keywordblock]>
translational x-direction, also degree-of-freedom 1
y <[keywordblock]>
translational y-direction, also degree-of-freedom 2
z <[keywordblock]>
translational z-direction, also degree-of-freedom 3
rotation-x <[keywordblock]>
rotational x-direction, also degree-of-freedom 4
rotation-y <[keywordblock]>
rotational y-direction, also degree-of-freedom 5.
rotation-z <[keywordblock]>
rotational z-direction, also degree-of-freedom 6.
Keyword Block
The following keywords refer to property names available in one or more link constitutive model. The data type used as property values will vary. In general it will be a
single real value, but it may be more than one value, or it may be another type entirely. The available property names are: rotation-x, rotation-y, rotation-z, x, y
and z.
area f
The area associated with the link connection. The default value is :fllt:`1.0`. This value applied to all current deformable link models.
cohesion f
Limiting force per unit area, when confining stress is zero. The default value is 0.0. This value applies to the shear-yield and pile-yield models.
cohesion-table s
Name of a table used to relate cohesion to relative displacement. The default value is null, indicating table lookup of cohesion is inactive. This value applies to the
shear-yield model.
confinement-table s
Name of a table used to relate a confinment adjustment factor to the amount of shear in the confining stress. The default value is null, indicating table lookup of
confinement is inactive. This value applies to the shear-yield model.
friction f
Friction angle (in degrees) that modifies the limiting force as a function of confining stress. The default value is 0.0. This value applies to the shear-yield and pile-
yield models.
friction-table
Name of a table used to relate friction to relative displacment. The default value is null, indicating table lookup of friction is inactive. This value applies to the
shear-yield model.
gap b
Flag indicating that gap tracking will affect behavior. The default value is off. This value applied to the normal-yield and pile-yield models.
incremental-confinement-flag
Flag indicating incremental confinement - confinment will be calculated as a difference from the initial stress state. The default value is off. This value applies to
the shear-yield model.
perimeter f
The effective perimeter of the structure connected to the link for the purposes of calculating properties. The default value is 0.0 This value applies to the shear-
yield model.
stiffness f
The stiffness of the spring. The default value is 1.0. This value applied to all current deformable link models.
yield-compression f
The limiting negative value of force, generated by negative relative displacement (target - source). The default value is 0.0. This value applies to the normal-yield
model.
yield-tension f
The limiting positive value of force, generated by negative relative displacement (target - source). The default value is 0.0. This value applies to the normal-yield
model.
structure link select command

Syntax
structure link select <keyword>
Primary keywords:
b | new | undo
This commands selects or de-selects all links in the range. Selected objects can be specified in a range filter by using the selected keyword. Objects that are not selected
can be specified in a range filter by using the deselected keyword.
if a boolean type is specified, and if on, it selects all links in the range. If off, it de-selects all links in the range. on is the default if no keyword is given.
new
implies on. This will select links in the range and automatically de-select links not in the range.
undo
this will reverse the operation of the last structure link select command. FLAC3D keeps a maximum undo stack of size 12.
structure link slide command

Syntax
structure link slide b <range>
Set the large-strain sliding flag. The flag will be set for all links within the specified range. [DR: help to sort out what to do with next statement] See :flag2:-Linky!!!!!-
for a discussion of large-strain sliding behavior.
structure link tolerance-contact command

Syntax
structure link tolerance-contact f
Set the tolerance used when establishing node-to-zone links. A node is considered to be in a zone if it is within a distance d of the zone boundary, where δ equals f times
zone size (taken as the maximum x-, y-, or z-dimension of the zone bounding box). Nodes that are used by elements with their sliding flag on will utilize structure
link tolerance-slide instead of f when attempting to update the zone interpolation point of an existing link. By default, f equals 1 × 10-5.
structure link tolerance-node command

Syntax
structure link tolerance-node f
Set the tolerance used when establishing node-to-node links. A node-to-node link can only be established if the distance between the two nodes is less than f. By
default, f equals 1 × 10-5.
structure link slide-tolerance command

Syntax
structure link tolerance-slide f <range>
Set the tolerance used when updating node-to-zone links in response to large-strain motion. A node is considered to be in a zone if it is within a distance d of the zone
boundary, where δ equals f times zone size (taken as the maximum x-, y-, or z-dimension of the zone bounding box). By default, f equals 1 × 10-5.
FISH Functions
FISH functions operating on structural links. The type specifiers used in the FISH function signatures are given in the FISH Type Index section.
Structural Link Functions
struct.link.attach(STRUCT_LINK_PNT,INT)
Get the attached condition used by the link in degree-of-freedom...
struct.link.delete(STRUCT_LINK_PNT)
Delete the structural link.
struct.link.extra(STRUCT_LINK_PNT<,INT>)
Get/set the FISH parameter value stored at index i of...
struct.link.find(INT)
Get the link with internally assigned component-ID number i .
struct.link.group(STRUCT_LINK_PNT<,STR>)
Get/set the group name assigned to link p in slot...
struct.link.group.remove(STRUCT_LINK_PNT,STR)
Remove the group s from structural link p in all...
struct.link.head
Get the first zone in the list of all structural...
struct.link.id(STRUCT_LINK_PNT)
Get the structural link ID number.
struct.link.id.component(STRUCT_LINK_PNT)
Get the structural link component-ID number.
struct.link.isgroup(STRUCT_LINK_PNT,STR<,STR>)
Check if the group s is associated with the structural...
struct.link.list
Get the list of all structural links in the model.
struct.link.maxid
Get the maximum component-ID number assigned to any structural link...
struct.link.model(STRUCT_LINK_PNT,INT)
Get the name of the 1-D force-displacement model used in...
struct.link.model.area(STRUCT_LINK_PNT<,INT>)
Get/set the area associated with the force-displacement model.
struct.link.model.compression(STRUCT_LINK_PNT<,INT>)
Get/set the compressive yield force associated with the force-displacement model.
struct.link.model.disp(STRUCT_LINK_PNT<,INT>)
Get the relative displacement between the node and the target...
struct.link.model.force(STRUCT_LINK_PNT<,INT>)
Get the current force in each 1-D force-displacement model.
struct.link.model.gap(STRUCT_LINK_PNT)
Get/set the flag indicating whether gap calculations are active in...
struct.link.model.gap.neg(STRUCT_LINK_PNT<,INT>)
Get the negative (compressive) gap component of each 1-D force-displacement...
struct.link.model.gap.pos(STRUCT_LINK_PNT<,INT>)
Get the positive (tensile) gap component of each 1-D force-displacement...
struct.link.model.prop(STRUCT_LINK_PNT,INT,STR)
Get/set a property of the deformable model in degree-of-freedom idof ...
struct.link.model.stiffness(STRUCT_LINK_PNT<,INT>)
Get/set the stiffness used by each 1-D force-displacement model.
struct.link.model.tension(STRUCT_LINK_PNT<,INT>)
Get/set the tensile yield force associated with the force-displacement model.
struct.link.model.yield(STRUCT_LINK_PNT,INT)
Get the yield state indicator in the 1-D force displacement...
struct.link.next(STRUCT_LINK_PNT)
Get the next link after p in the list of...
struct.link.node(STRUCT_LINK_PNT)
Get a pointer to the node hosting the structural link.
struct.link.num
Get the total number of structural links in the model.
struct.link.side(STRUCT_LINK_PNT)
Get the side number of the link.
struct.link.slide(STRUCT_LINK_PNT)
Get/set the large-strain sliding DR: previous wants to be a...
struct.link.slide.tol(STRUCT_LINK_PNT)
struct.link.target(STRUCT_LINK_PNT)
Get the ID (or component-ID) of the target.
struct.link.type(STRUCT_LINK_PNT)
Get the name of the link target type.
struct.link.typeid
struct.link.used.by(STRUCT_LINK_PNT)
Get the name of the type of structural element with...
l struct.link.attach
l struct.link.delete
l struct.link.extra
l struct.link.find
l struct.link.group
l struct.link.group.remove
l struct.link.head
l struct.link.id
l struct.link.id.component
l struct.link.isgroup
l struct.link.list
l struct.link.maxid
l struct.link.model
l struct.link.model.area
l struct.link.model.compression
l struct.link.model.disp
l struct.link.model.force
l struct.link.model.gap
l struct.link.model.gap.neg
l struct.link.model.gap.pos
l struct.link.model.prop
l struct.link.model.stiffness
l struct.link.model.tension
l struct.link.model.yield
l struct.link.next
l struct.link.node
l struct.link.num
l struct.link.side
l struct.link.slide
l struct.link.slide.tol
l struct.link.target
l struct.link.type
l struct.link.typeid
l struct.link.used.by
struct.link.attach
Syntax
i = struct.link.attach(p,idof)
Get the attached condition used by the link in degree-of-freedom idof (from 1 to 6).
The return value will be an integer with one of three values: 1 = free; 2 = rigid; and 3 = deformable.
If the condition is deformable, see the struct.link.model function (and associated functions) for details.
Returns: i - an integer indicating the basic attachment condition used by this link in degree-of-freedom idof
Arguments: p - a pointer to a structural link
idof - the degree-of-freedom, from 1 to 6
struct.link.delete
Syntax
i = struct.link.delete(p)
Delete the structural link. The return value is ignored.
Returns: i - the integer 0

Arguments: p - a pointer to a structural link, which will be invalidated (and set to null) after deletion
struct.link.extra
Syntax
a = struct.link.extra(p<,i>)
struct.link.extra(p<,i>) = a
Get/set the FISH parameter value stored at index i of the extra array associated with the structural link.
Returns: a - the value of the variable stored at the index

Accepts: a - the value of the variable stored at the index
Arguments: p - a pointer to a link
i - an optional index from 1 to 128. If not specified 1 is assumed.
struct.link.find
Syntax
p = struct.link.find(i)
Get the link with internally assigned component-ID number i.
Returns: p - the pointer to the link with component-ID number i, or null if none was found
Arguments: i - a component-ID number
struct.link.group
Syntax
s = struct.link.group(p<,slot>)
struct.link.group(p<,slot>) = s
Get/set the group name assigned to link p in slot slot. Use of the group logic is described in Group.
Returns: s - the name of the group in slot slot. Will return None if no group has been assigned in that slot.
Accepts: s - the name of the group in slot slot
slot - the optional name of the slot used. If not given, the slot name Default will be used.
struct.link.group.remove
Syntax
b = struct.link.group.remove(p,s)
Remove the group s from structural link p in all slots it is found.
Returns: b - true if the group was removed from one or more slots of the link; false if the group was not found in the link
s - the name of the group in slot s to be removed
struct.link.head
Syntax
p = struct.link.head
Get the first zone in the list of all structural links in the model. This function should be considered deprecated; it is provided mostly for backwards compatibility with
old data files. Instead, see the fish_statement_loopforeach statement and the zone.list function. See also the zone.next function.
Returns: p - a pointer to the first structural link in the list of all links in the model
struct.link.id
Syntax
i = struct.link.id(p)
Get the structural link ID number. This is defined as the ID number of the first element connected to the link host node and is not to be confused with the component-ID
number.
Note
number. See the struct.link.id.component function.
Returns: i - the structural link ID number

struct.link.id.component
Syntax
i = struct.link.id.component(p)
Get the structural link component-ID number. This is a unique value assigned internally at creation, not to be confused with the ID number.
Note
and representing a single overall structure. For structural objects, the unique internally assigned ID number associated with the object is called the component-ID
number. See the struct.link.id function.
Returns: i - the structural link component-ID number

struct.link.isgroup
Syntax
b = struct.link.isgroup(p,s<,slot>)
Check if the group s is associated with the structural link. Will return true if a match is found in any slot. If the optional third argument slot is provided, then it will only
check that slot.
Returns: b - true if the group was found in that link

s - a group name
slot - an optional slot specification. If not provided, the check will occur on all slots that have been assigned to the link.
struct.link.list
Syntax
l = struct.link.list()
Get the list of all structural links in the model. This is primarily used in the fish_statement_loopforeach command.
Returns: l - a pointer to the list of all links
struct.link.maxid
Syntax
i = struct.link.maxid()
Get the maximum component-ID number assigned to any structural link in this model. The next link created will be assigned this value plus one.
Note
number. See the struct.link.id.component function.
Returns: i - maximum component-ID number of any structural link in the model
struct.link.model
Syntax
s = struct.link.model(p,idof)
Get the name of the 1-D force-displacement model used in degree-of-freedom idof. If the link attached condition is free or rigid, then this function will return an empty
string (see the struct.link.attach function). The currently available models are linear, normal-yield, shear-yield, and pile-yield.
Returns: s - the name of the model used in degree of freedom idof, or an empty string if none is being used
idof - the degree-of-freedom, from 1 to 6
struct.link.model.area
Syntax
m = struct.link.model.area(p<,idof>)
struct.link.model.area(p<,idof>) = m
Get/set the area associated with the force-displacement model. This is either returned as a 1x6 matrix or as a single value representing the area in degrees-of-freedom
idof if provided.
Returns: m - a 1x6 matrix with the areas of all degrees-of-freedom, or the area of a single specific degree-of-freedom
Accepts: m - a 1x6 matrix with the areas of all degrees-of-freedom, or the area of a single specific degree-of-freedom
idof - an optional integer indicating a specific degree of freedom to query, from 1 to 6
struct.link.model.compression
Syntax
m = struct.link.model.compression(p<,idof>)
struct.link.model.compression(p<,idof>) = m
Get/set the compressive yield force associated with the force-displacement model. Returns or assigns a 1x6 matrix representing the values in all degrees-of-freedom, or
if the optional idof argument is specified, a single value in that degree-of-freedom.
The compressive yield force is a limit to how negative the force in the link can be (entered as a positive value). Note that compression is defined relative to the node-
local coordinate system, and, thus, depending on the coordinate systems involved, the definition of compression and tension may not match those used by the element
connected to the host node. See the struct.link.model.force function.
Returns: m - a 1x6 matrix representing the values in all degrees-of-freedom, or a single value for a specific degree-of-freedom
Accepts: m - a 1x6 matrix representing the values in all degrees-of-freedom, or a single value for a specific degree-of-freedom
Arguments: p - a structural link pointer
idof - an optional argument indicating a specific degree of freedom, from 1 to 6
struct.link.model.disp
Syntax
m = struct.link.model.disp(p<,idof>)
Get the relative displacement between the node and the target used by each 1-D force-displacement model. Will return a 1x6 matrix with the values in all six degrees-
of-freedom, or if the optional idof argument is provided, the value in one specific degree-of-freedom.
Note that displacements are with respect to the node-local coordinate system. The relative displacement is defined as the displacement of the link target minus the the
displacement of the link host node in the node local coordinate system.
Returns: m - a 1x6 matrix representing the relative displacement seen by each force-displacement model, or a single value in a specific degree-of-freedom
idof - an optional degree-of-freedom, from 1 to 6
struct.link.model.force
Syntax
m = struct.link.model.force(p<,idof>)
Get the current force in each 1-D force-displacement model. Will return a 1x6 matrix with the values in all six degrees-of-freedom, or if the optional idof argument is
provided, the value in one specific degree-of-freedom.
The force is calculated by the 1-D force-displacement model in an incremental fashion from the incremental relative displacement of the link target and the host node
(target minus node). See the struct.link.model.disp function.
Returns: m - a 1x6 matrix representing the current force seen by each force-displacement model, or a single value in a specific degree-of-freedom
struct.link.model.gap
Syntax
b = struct.link.model.gap(p,idof)
struct.link.model.gap(p) = idof
Get/set the flag indicating whether gap calculations are active in the 1-D force-displacement model used in degree-of-freedom idof. See the
struct.link.model.gap.neg and struct.link.model.gap.pos functions.
Returns: b - true if gap calculations are active in degree-of-freedom idof

Accepts: b - true if gap calculations will be active in degree-of-freedom idof
idof - the degree-of-freedom to use, from 1 to 6
struct.link.model.gap.neg
Syntax
m = struct.link.model.gap.neg(p<,idof>)
Get the negative (compressive) gap component of each 1-D force-displacement model. Will return a 1x6 matrix with the values in all six degrees-of-freedom, or if the
optional idof argument is provided, the value in one specific degree-of-freedom.
This value will only affect force calculations if the gap-use flag is on; see the struct.link.model.gap function. The relative displacement is defined as the
displacement of the link target minus the displacement of the link host node in the node local coordinate system. See the struct.link.model.disp function.
Returns: m - a 1x6 matrix representing the negative gap component of each 1-D force-displacement model, or a single value in a specific degree-of-freedom
struct.link.model.gap.pos
Syntax
m = struct.link.model.gap.pos(p<,idof>)
Get the positive (tensile) gap component of each 1-D force-displacement model. Will return a 1x6 matrix with the values in all six degrees-of-freedom, or if the optional
idof argument is provided, the value in one specific degree-of-freedom.
This value will only affect force calculations if the gap-use flag is on; see the struct.link.model.gap function. The relative displacement is defined as the
displacement of the link target minus the displacement of the link host node in the node local coordinate system. See the struct.link.model.disp function.
Returns: m - a 1x6 matrix representing the positive gap component of each 1-D force-displacement model, or a single value in a specific degree-of-freedom
struct.link.model.prop
Syntax
a = struct.link.model.prop(p,idof,s)
struct.link.model.prop(p,idof,s) = a
Get/set a property of the deformable model in degree-of-freedom idof in the structural elemenet link p.
On get, if that degree-of-freedom does not have a deformable model or the property name is not recognized, the return value will be an error string. On set in those cases
nothing happens.
Keyword matching is used to compare s with a property name, with the first valid match being used in the list of properties associated with the model.
Returns: a - the model property

Accepts: a - the model property - if the type is not what is expected an error will occur.
idof - a degree-of-freedom from 1 to 6
s - a string represengint the name of a property used by the model.
struct.link.model.stiffness
Syntax
m = struct.link.model.stiffness(p<,idof>)
struct.link.model.stiffness(p<,idof>) = m
Get/set the stiffness used by each 1-D force-displacement model. Will return a 1x6 matrix with the values in all six degrees-of-freedom, or if the optional idof argument
is provided, the value in one specific degree-of-freedom.
Returns: m - a 1x6 matrix representing the stiffness used by each force-displacement model, or a single value in a specific degree-of-freedom
struct.link.model.tension
Syntax
m = struct.link.model.tension(p<,idof>)
struct.link.model.tension(p<,idof>) = m
Get/set the tensile yield force associated with the force-displacement model. Returns or assigns a 1x6 matrix representing the values in all degrees-of-freedom, or if the
optional idof argument is specified, a single value in that degree-of-freedom.
The tensile yield force is a limit to how positive the force in the link can be. Note that tension is defined relative to the node-local coordinate system, and, thus,
depending on the coordinate systems involved, the definition of compression and tension may not match those used by the element connected to the host node. See the
struct.link.model.force function.
Returns: m - a 1x6 matrix representing the values in all degrees-of-freedom, or a single value for a specific degree-of-freedom
Accepts: m - a 1x6 matrix representing the values in all degrees-of-freedom, or a single value for a specific degree-of-freedom
idof - an optional argument indicating a specific degree of freedom, from 1 to 6
struct.link.model.yield
Syntax
i = struct.link.model.yield(p,idof)
Get the yield state indicator in the 1-D force displacement model in degree-of-freedom idof. This is returned as an integer where 0 = never yielded, 1 = yielding now,
and 2 = yielded in past.
Returns: i - a yield indicator from 0 to 2

idof - a degree-of-freedom from 1 to 6
struct.link.next
Syntax
pnext = struct.link.next(p)
Get the next link after p in the list of all structural links in the model. Will return null if no more links follow. This function should be considered deprecated; it is
provided mostly for backwards compatibility with old data files. Instead, see the fish_statement_loopforeach statement and the struct.link.list function. See also
the struct.link.head function.
Returns: pnext - the next structural link in the list, or null

struct.link.node
Syntax
node = struct.link.node(p)
Returns: node - a pointer to a structural node hosting the link

struct.link.num
Syntax
i = struct.link.num()
Returns: i - the total number of structural links in the model
struct.link.side
Syntax
i = struct.link.side(p)
Get the side number of the link. Unless the host node of the link is attached to an embedded liner, this will always return 1. If the host node is part of an embedded liner,
it may be 2, indicating the link is being used on side 2 of the liner.
Returns: i - the side number of the link, from 1 to 2

struct.link.slide
Syntax
b = struct.link.slide(p)
struct.link.slide(p) = b
Get/set the large-strain sliding DR: previous wants to be a link to... where? flag for the link. This function only applies to node-to-zone links; it has no meaning for
node-to-node links.
Returns: b - true if the large-strain sliding flag is active on the link

Accepts: b - true if the large-strain sliding flag will be active on the link
struct.link.slide.tol
Syntax
f = struct.link.slide.tol(p)
struct.link.slide.tol(p) = f
Get/set the large-strain sliding DR: previous wants to be a link to... where? tolerance for the link. This function only applies to node-to-zone links; it has no meaning for
node-to-node links.
Returns: f - the large-strain sliding tolerance

Accepts: f - the large-strain sliding tolerance
struct.link.target
Syntax
i = struct.link.target(p)
Get the ID (or component-ID) of the target. For a node-to-node link, this will the node component-ID number. For a node-to-zone link, this will be the zone ID number.
Returns: i - the ID number of the target

struct.link.type
Syntax
s = struct.link.type(p)
Get the name of the link target type. A node-to-node link will return Structure Node. A node-to-zone link will return Zone.
Returns: s - the name of the link target type

Accepts: p - a structural element link
struct.link.typeid
Syntax
i = struct.link.typeid()
Get an identifier that uniquely determines the type of object. This function will return 1283546109, indicating a general structural link.
Note that for node-to-node links, the typeid is 1283546111. For node-to-zone links, the typeid is 1283545600.
This can be used with the type.pointer.id intrinsic to identify the object type to which a pointer refers.
struct.link.used.by
Syntax
s = struct.link.used.by(p)
Get the name of the type of structural element with which this link is associated. This only applies to node-to-zone links, otherwise the return is a null string. The type
string will be one of beam, cable, pile, shell, geogrid, or liner. If the attach conditions and models assigned to the link are not compatible with those elements (generally
because they have been changed), then a null string is returned.
Returns: s - a name indicating the type of element with which the link is associated
Beam Structural Elements

Mechanical Behavior
Each beam structural element is defined by its geometric and material properties. A beam element is assumed to be a straight segment of uniform bisymmetrical cross-
sectional properties lying between two nodal points. An arbitrarily curved structural beam can be modeled as a curvilinear structure composed of a collection of beam
elements. By default, each beam element behaves as an isotropic, linearly elastic material with no failure limit; however, one can specify a limiting plastic moment or
introduce a plastic-hinge location (across which a discontinuity in rotation may develop) between beam elements (see Plastic Hinge Formation in a Beam Structure ). The
general properties of the finite element used by each beam element are described in Beam Finite Element. Beam elements are suitable for modeling structural beams in which
the displacements caused by transverse-shearing deformations and out-of-plane (longitudinal) warping of the cross section can be neglected.
Like all structural elements (and unlike zones), individual elements are identified by their component-id numbers. Groups of beams are identified by id numbers. Individual
structural nodes and links are also identified by component-id numbers. Nodes and links can also be selected by the id number of the elements they are attached to.
Each beam element has its own local coordinate system, shown in Figure 1. This system is used to specify both the cross-sectional moments of inertia and applied distributed
loading, and to define the sign convention for force and moment distributions across beam elements that make up a single beam (see Figure 2). The beam element coordinate
system is defined by the locations of its two nodal points (labeled 1 and 2 in Figure 1), and by the vector . The beam element coordinate system is defined such that
1. the centroidal axis coincides with the -axis,

x
2. the -axis is directed from node-1 to node-2, and
y \
3. the -axis is aligned with the projection of b onto the cross-sectional plane (i.e., the plane whose normal is directed along the -axis).
../../../../../../_images/coordinate-
system.png
Figure 1: Beam element coordinate system and 12 active degrees-of-freedom of the beam finite element
../../../../../../_images/sign-
convention.png
Figure 2: Sign convention for forces and moments at the ends of a beam element (Axes show beam element coordinate system, ends 1 and 2 correspond with order in nodal
connectivity list, and all quantities are drawn acting in their positive sense.)
\
The beam element coordinate system can be modified with the structure beam property direction-y command. (If b is not specified, or is parallel with the local
y x
-axis, then defaults to the global - or -direction, whichever is not parallel with the local -axis.) The beam element coordinate system can be
viewed with the Beam plot item and printed with the structure beam list system-local command. The nodal connectivity can be printed with the structure beam
list information command.
The 12 active degrees-of-freedom of the beam finite element are shown in Figure 1. For each generalized displacement (translation and rotation) shown in the figure, there is a
corresponding generalized force (force and moment). The stiffness matrix of the beam finite element includes all six degrees of freedom at each node to represent axial, shear
and bending action within a beam structure.
Response Quantities
Beam responses include force and moment vectors that act at the end of each beam element. These quantities can be expressed in the global system or in the beam element
coordinate system. The beam responses can be accessed via FISH and
1. printed with the structure beam list command, using the subsequent keywords force-node or force-end,
2. monitored with the structure beam history command, and
3. visualized with the Beam plot item.
The sign convention in Figure 2 provides a continuous description of force and moment distributions across beam elements that make up a single beam. It assumes that the set
of beam elements making up the beam are oriented consistently, such that their local coordinate systems form a continuous description of the beam orientation. Such will be
the case if the beam is created using the structure beam create command. The nodes of each beam element so created will be ordered such that the overall beam direction
goes from the first point to the second point specified. The nodal connectivity can be printed with the structure beam list information command.
Properties
Each beam element has 10 properties:
\
1. density, mass density, (optional — needed if dynamic mode or gravity is active) [M/L3]
2. young, Young's modulus, [F/L2]

\
3. poisson, Poisson's ratio,
\
4. plastic-moment, plastic moment capacity, (optional — if not specified; is assumed to be infinite) [F L]
\alpha_t
5. thermal-expansion, thermal expansion coefficient , [1/T] (optional — used for thermal analysis)
A
6. cross-sectional-area, cross-sectional area, [L2]
y
7. moi-y, second moment with respect to beam element -axis; [L4]
8. moi-z, second moment with respect to beam element -axis; [L4]
J
9. moi-polar, polar moment of inertia, [L4]
10. direction-y, vector whose projection onto the beam element cross-section defines the element -axis (optional — if not specified,
y x
defaults to the global - or -direction, whichever is not parallel with the element -axis)
The material behavior is described by properties 1-5, and the cross-sectional geometry is described by properties 6-10. For the general beam element cross-section shown in
x
Figure 3, the polar moment of inertia, , and second moments, and , are defined in the element coordinate system by the integrals
J &= \int_A r^2

\,dA
I_y &= \int_A z^2

\,dA
I_z &= \int_A y^2

\,dA
y z
in which the two principal axes of the cross section are defined by the beam element - and -axes.
../../../../../../_images/cross-
section.png
Figure 3: General beam element cross-section in the element yz-plane
Beam properties are easily calculated, or obtained from handbooks. For example, typical values for structural steel are 200 GPa for Young's modulus, and 0.3 for Poisson's
ratio. For concrete, typical values are 25 to 35 GPa for Young's modulus, 0.15 to 0.2 for Poisson's ratio, and 2100 to 2400 kg/m3 for mass density. Composite systems, such as
reinforced concrete, should be based on the transformed section.
h
If a plastic moment is specified, the value may be calculated as follows. Consider a flexural member of width, , and height, . If the member is composed of a
material that behaves in an elastic-perfectly plastic manner, the elastic and plastic resisting moments can be computed. The moment necessary to produce yield stress,
\sig
, in the outer fibers is defined as the elastic moment, , and is calculated as
M^E\ =\ \sigma_y\ {bh^2

\over{6}}
For yielding to occur throughout the section, the yield stress must act on the entire section, and the location of the resultant force on one-half of the section must be
from the neutral surface. The resisting moment, defined as the plastic moment, , is
M^P\ =\ \sigma_y\ {bh^2

\over {4}}
The section at which the plastic moment occurs can continue to deform without inducing additional resistance after it reaches . The plastic-moment capacity limits the
internal moment carried by each beam element.
In order to limit the moment that is transmitted between beam elements, the moment capacity at the nodes must also be restricted. The condition of increasing deformation
with a limiting resisting moment that results in a discontinuity in the rotational motion is called a plastic hinge. Potential plastic-hinge locations can be defined by creating
double nodes at each hinge location, adding a node-to-node link between these nodes, and then specifying appropriate link attachment conditions. If the limiting moment is
reached at beam element connected by such a plastic hinge double-node, then a discontinuity in the rotational motion will develop. See Plastic Hinge Formation in a Beam
Structure for an example application of plastic hinges modeled with both single and double nodes.
The preceding discussion assumes a section that is symmetric about the neutral axis. However, if the section is not symmetric (for example, a T-section), or if the stress-strain
relations for tension and compression differ appreciably (for example, reinforced concrete), the neutral axis shifts away from the fibers that yield first, and it is necessary to
relocate the neutral axis before the resisting moment can be evaluated. The neutral axis may be found by integrating the stress profile over the section and solving for the
location of the axis at which stress is zero. In some cases, the integral can be expressed in terms of one unknown (in which case, the solution may not be difficult). However, if
the stress-strain relation for the material does not resemble an ideal elasto-plastic diagram, the solution may involve a number of trials. Nearly all texts on reinforced concrete
or steel design provide procedures and examples for calculating plastic moments.
The present formulation in FLAC3D assumes that beam elements behave elastically until they reach the plastic moment. This assumption is reasonably valid for symmetric
rolled-steel sections, because the difference between and is not large. However, for reinforced concrete, the plastic moment may be as much as an order of
magnitude greater than the elastic moment.
Example Applications
Simple examples are given to illustrate the use of beams.
l Tutorial: Braced Support of a Vertical Excavation

l Simple Beam — Two Equal Concentrated Loads — Beam Elements
l Cantilever Beam with Applied Moment at Tip — Beam Elements
l Buckling of an Axially Loaded Beam
l Plastic Hinge Formation in a Beam Structure
A complete list of examples that use beam elements is available in Structural Beam Examples.
Commands & FISH

l Commands
l FISH Functions
Tutorial: Braced Support of a Vertical Excavation

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ‣ Examples.... Choose "Structure/Beam/BracedSupport" and select "BracedSupport.f3prj" to load. The main
data files used are shown at the end of this example. The remaining data files can be found in the project.
This example examines a trench that is supported with one strut bracing the excavation walls at the top. The following command sequence is for the simple case in which the
brace is placed immediately upon excavation. The strut is represented as a single beam composed of two elements, and is created using the structure beam create by-
line command. Use of this command ensures that the two ends of the beam are attached to the grid such that the translational degrees-of-freedom are rigidly connected and
the rotational degrees-of-freedom are free.
Figure 1 shows the position of the brace, and Figure 2 illustrates the reduced displacements in the excavation walls. [CS: again, the following used to link back to "simple
tutorial"], compared to that shown in :flag2:-defcrossrefFilename{ftd127}ref{127F1001}- in defcrossrefFilename{ftd127}ref{127S1001}volI.
../../../../../_images/bracedsupport-geom.png
Figure 1: Braced excavation supported with a beam.
../../../../../_images/bracedsupport-disp.png
Figure 2: Displacement contours and axial force in strut for braced excavation.
Data File
BracedSupport.f3dat
model new
model title "Braced support with a beam of a vertical excavation"
; Create simple brick
zone create brick size 6 8 8
zone face skin ; label boundaries
; Assign material model and properties
zone cmodel assign mohr-coulomb
zone property bulk 1e8 shear 0.3e8 friction 35
zone property cohesion 1e10 tension 1e10 density 1000
; Gravity and boundary conditions
zone face apply velocity-normal 0 range group 'East' or 'West'
zone face apply velocity-normal 0 range group 'North' or 'South'
zone face apply velocity-normal 0 range group 'Bottom'
; Initial conditions
model gravity 9.81
zone initialize-stresses ratio 0.3
model solve ratio-local 1e-5
model save 'initial'
; Reduce zone strength, excavate
zone property cohesion 1.25e3 tension 1e3
zone cmodel assign null range position (2,2,5) (4,6,10)
model largestrain on
zone gridpoint initialize displacement (0,0,0)

; Create beam brace
struct beam create by-line ( 2, 4, 8) ( 4, 4, 8) segments=2
struct beam prop young=2.0e11 poisson=0.30
struct beam prop cross-sectional-area=6e-3 moi-z=200e-6 moi-y=200e-6 moi-polar=0.0
model save 'final'
Simple Beam — Two Equal Concentrated Loads — Beam Elements

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Beam/ConcentratedLoads" and select "ConcentratedLoads.f3prj" to load.
The main data files used are shown at the end of this example . The remaining data files can be found in the project.
A simply supported beam is loaded by two equal concentrated loads, symmetrically placed as shown in Figure 1. The shear and moment diagrams for this configuration are
V M_
also shown in the figure. The shear force magnitude, , is equal to the applied concentrated load, . The maximum moment, {ma , occurs between the two
\Delta_{\rm
loads and is equal to . The maximum deflection of the beam, max} , occurs at the center and is given by AISC (1980, p. 2-116) as
\Delta_{\rm max}\ =\ {P a \over {24 E I}} (3L^2 - 4

(1) a^2)
where: E = Young's modulus; and

I
= second moment of inertia ( = = ).
../../../../../_images/beamloads-
diagram.png
Figure 1: Simply supported beam with two equal concentrated loads (distance in units of meters).
Several properties are used in this example:
A 0.006 m3
Cross-sectional area ( )
200 GPa
Young's modulus ( )
0.30
Poisson's ratio ( )
y 200 × 10-6 m4
Second moment with respect to local -axis (I )
200 × 10-6 m4
Second moment with respect to local -axis (I )
0.0
Polar moment of inertia ( )
Point loads of = 10,000 N are applied at the two locations shown in Figure 1.
The FLAC3D model consists of 10 beam elements and 11 nodes, as shown in Figure 2. The beam is created by issuing three separate structure beam create by-line (all
with an ID of 1) to ensure that nodes will lie exactly at the beam third points. Also, four elements are created in the middle third to ensure that a node will lie at the exact beam
\Delta_{\rm
center, so that the displacement of this node can be compared with max} . Boundary conditions corresponding to beam-theory behavior are imposed on all the
nodes; namely, no translation in the z-direction, and no rotation about the x- and y-axes. Simple supports are specified at the beam ends by restricting translation in the y-
direction. Two point loads acting in the negative y-direction are applied at the beam third points.
../../../../../_images/beamloads-geom.png
Figure 2: FLAC3D model for simple beam problem.
The displacement field is shown in Figure 3. The maximum displacement occurs at the beam center and equals 6.469×10-3 m, which corresponds exactly with the theoretical
value of equation (1).
An alternative means of visualizing the displacement field for a small-strain simulation is to use the Beam plot item and specify a nonzero value for the deformation
magnification factor. Figure 4 shows both the undeformed and deformed shapes.
../../../../../_images/beamloads-disp.png
Figure 3: Displacement field of simple beam.
../../../../../_images/beamloads-deform.png
Figure 4: Deformed (magnification of 100) and undeformed shapes of simple beam.
Figure 5 and Figure 6 show the shear force and moment distributions, which correspond exactly with the theoretical solutions. These two plot items display these quantities in
the element coordinate system using the Beam sign conventions. In this model, all element systems are aligned with the global system. Thus, the shear force and moment act
in the element y- and z-directions, respectively.
x
The evolution of moment at is shown in Figure 7 to reach a steady-state value of 10,000 N-m. In this plot, we overlay two histories: one has sampled the moment
acting at the right end of element 1 and the other has sampled the moment acting at the left end of element 2. If expressed in a consistent system, these two values should be
identical, and the plot demonstrates that they are. This is the case because the elements making up the beam have a consistent orientation (having been created using the
structure beam create command). Note that if we print the moment acting on each element in terms of the global system with the command
structure beam list force-node global range component-id 1 2
we find that the moment acting on the right end of element 1 is positive, while the moment acting on the left end of element 2 is negative. This is the correct behavior that
satisfies equilibrium.
../../../../../_images/beamloads-shear.png
Figure 5: Shear force distribution in simple beam.
../../../../../_images/beamloads-moment.png
Figure 6: Moment distribution in simple beam.
../../../../../_images/beamloads-momhis.png
Figure 7: Evolution of moment at x = 1 in simple beam.
Reference
AISC. Manual of Steel Construction, Eighth Edition. Chicago: American Institute of Steel Construction Inc. (1980).
Data File
ConcentratedLoads.f3dat
model new
model title "Simple Beam --- Two Equal Concentrated Loads Symmetrically Placed"
; Create the beams; Ensure nodes will exist at the three points
struct beam create by-line ( 0, 0, 0) ( 3, 0, 0) id=1 segments=3
; Assign beam properties
struct beam property young=2e11 poisson=0.30 cross-sectional-area=6e-3 moi-polar=0.0 moi-y=200e-6 moi-z=200e-6
; Specify model boundary conditions (including applied loads)
struct node fix velocity-z rotation-x rotation-y ; restrict all non-beam modes
struct node fix velocity-y range union position-x=0 position-x=9 ; rollers at beam ends
struct node apply force=(0.0,-1e4,0.0) range union position-x=3 position-x=6 ; apply point loads
; Setup histories for monitoring behavior.
struct beam history name='mom1' moment-z end 2 position (0.5,0,0) ; moment, right of element 1
struct beam history name='mom2' moment-z end 1 position (1.5,0,0) ; moment, left of element 2
; Bring the problem to equilibrium
model solve ratio-local=1e-7
model save 'ConcentratedLoads'
Cantilever Beam with Applied Moment at Tip — Beam Elements

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ? Examples.... Choose "Structure/Beam/Cantilever" and select "Cantilever.f3prj" to load. The main data files
used are shown at the end of this example. The remaining data files can be found in the project.
A cantilever beam is subjected to an applied moment at its tip, as shown in Figure 1. This problem is an example of geometric nonlinearity, whereby deformations
significantly alter the location of loads, so that equilibrium equations must be written with respect to the deformed geometry. Such problems can be solved by running
y
FLAC3D in large-strain mode. The large-strain -direction deflection at the beam tip (assuming that the material remains linearly elastic) is given by Cook et al. (1989,
pp. 529-531) as
{v_{\rm tip}\ =\ {E I \over {M}} \left(1 - \cos \biggl({M L \over E I}\biggr)

(1) \right)}
where: = Young's modulus; and
= second moment of inertia ( = = ).

../../../../../_images/cantilever-
diagram.png
Figure 1: Cantilever beam with applied moment at tip.
Several properties and loading conditions are used in this example:
0.006 m3
cross-sectional area ( )
200 GPa
Young's modulus ( )
0.30
Poisson's ratio ( )
_ 200 × 10-6 m4
second moment with respect to local -axis (I )
_ 200 × 10-6 m4
second moment with respect to local -axis (I )
0.0
polar moment of inertia ( )
10 m
beam length ( )
5 × 106 N-m
applied moment at tip ( )
v_
For these conditions, the theoretical tip deflection, {\rm , is given by equation (1) to be 5.477 m.
The FLAC3D model consists of 10 beam elements and 11 nodes. Boundary conditions corresponding to beam-theory behavior are imposed on all the nodes: namely, no
z
translation in the z-direction, and no rotation about the x- and y-axes. The left end is fully fixed in all six degrees of freedom. And a moment vector aligned with the -
direction is applied to the node at the beam tip.
The final structural configuration is shown in Figure 2. The y-direction deflection at the beam tip equals 5.497 m, which is within 0.36% of the analytical solution.
../../../../../_images/cantilever-geom.png
Figure 2: Final structural configuration.
Reference
Cook, R. D., D. S. Malkus and M. E. Plesha. Concepts and Applications of Finite Element Analysis, Third Edition. New York: John Wiley & Sons Inc. (1989).
Data File
Cantilever.f3dat
model new
model title 'Cantilever beam, applied moment of 5e6 at tip (large-strain solution)'
; Create beam and assign properties
struct beam create by-line (0,0,0) (10,0,0) segments=10
struct beam property young=2e11 poisson=0.3
struct beam property cross-sectional-area=6e-3 moi-z=200e-6 moi-y=200e-6 moi-polar=0
; Boundary conditions
struct node fix velocity rotation range position-x 0 ; fully fix left end
struct node apply moment=(0,0,5e6) range position-x 10 ; apply moment at tip
; Run the model
model save 'Cantilever'
Buckling of an Axially Loaded Beam

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Beam/AxialBuckling" and select "AxialBuckling.f3prj" to load. The main
This example demonstrates the buckling behavior of an axially loaded beam with small initial deflection. The beam rests on a base and is fixed in lateral translation at its ends.
A global system of coordinates is defined with the z-axis pointing upward, oriented along the axis of the beam, and with origin at the base of the beam. The beam initial shape
is defined by the equation found in Massonnet (1960):
x_0 = f_0 {\rm sin} \Bigl({{\pi z} \over {l}}

(1) \Bigr)
where is beam length, and is maximum initial deflection.
The additional deflection taken by the beam under an axial load, , is predicted from linear stability analysis by the equation
x - x_0 = {{ f_0 {\rm sin} ({{\pi z} \over{l}})} \over {{ {P_{cr}} \over

(2) {P}} 1}}
P
where is the minimum critical load for buckling.
The minimum critical load is defined as
P_{cr} = \pi^2 { {EI} \over

(3) {l^2}}
where is Young's modulus, and is the moment of inertia for lateral flexion.
The additional deflection at the center of the beam is thus
f = { {f_0} \over { {P_{cr} / {P -

(4) 1} } }}
For this example, the beam is 200 m long, and the maximum amplitude of initial deflection is 1 cm (or 0.005% of the beam length). Young's modulus is 257 MPa, and the
x
moment of inertia for lateral flexion is 5.333 m4. The beam is modeled using 20 elements, translation is fixed in all directions at the base, and in the - and -
directions at the top. An axial load is applied in increments at the beam top until the critical load is reached. After each increment, the model is cycled to mechanical
equilibrium and the load deflection is recorded in a table.
The beam deflection is seen to increase beyond measure as the load converges to the minimum critical value, as expected. A comparison between analytical solution and
numerical prediction for additional deflection at the center of the beam is presented in Figure 1. As can be seen, the match between the solutions is very good.
../../../../../_images/axialbuckling-deflection.png
Figure 1: Load deflection curve.
Reference
Massonnet, C. E. Résistance Des Matériaux. Sciences Et Lettres, Liége (1960).
Data File
AxialBuckling.f3dat
; Axial loading of a beam with small initial deflection.

; Load versus additional deflection at beam half length:
model new
fish automatic-create off
model title "Axial loading of a beam with small initial deflection."
; Create a beam of 20 elements with a sin wave initial deflection in x
fish define createBeam
local p2 = vector(0,0,0)
loop local z (10,200,10)
local p1 = p2
p2 = vector(0.01*math.sin(math.pi*z/200.),0,z)
command
struct beam create by-line @p1 @p2 id=1
end_command
end_loop
end
@createBeam
; Setup properties and boundary conditions
struct beam property young 2.57e8 cross-sectional-area 4 direction-y (0,1,0) moi-y 5.33 moi-z 5.333 moi-polar 0 poisson 0.3
struct node fix velocity range position-z 0
struct node fix velocity-x velocity-y range position-z 200
; create history
struct node history displacement-x position (0,0,100)
struct node history displacement-y position (0,0,100)
; define loading sequence, in a table as a fraction of the critical load
table 'seq' add (1,.1) (2,.2) (3,.3) (4,.4) (5,.5) (6,.6) (7,.7) (8,.8) (9,.9) (10,.92) (11,.94) (12,.96) (13,.97) (14,.98) (15,.99)
; Apply Each load in sequence, and record deflection after equilibrium
fish define loadDeflection
local endNode = struct.node.near(0,0,200)
local midNode = struct.node.near(0,0,100)
local Pcr = (math.pi/200)^2 * 2.57e8 * 5.333
loop local i (1,table.size('seq'))
local load = table('seq',i) * Pcr
struct.node.apply(endNode,3) = -load
io.out('Loading step '+string(i))
command
end_command
local pos = struct.node.pos(midNode)
pos->z = 0
local deflect = math.mag(pos) - 0.01
local x = 0.01/(Pcr/load - 1)
table('def',deflect) = load
table('anal',x) = load
command
model save ['load'+string(load*100/Pcr)]
end_command
end_loop
end
@loadDeflection
model save 'AxialBuckling'
Plastic Hinge Formation in a Beam Structure

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Beam/PlasticHinge" and select "PlasticHinge.f3prj" to load. The main data
files used are shown at the end of this example. The remaining data files can be found in the project.
This example demonstrates two methods, referred to as the single-node and the double-node methods, by which FLAC3D can be used to calculate the initiation and
subsequent behavior of a plastic hinge in a beam. The single-node method involves specifying the limiting plastic moment that can be carried by the elements making up the
beam. This is done by specifying the desired plastic-moment capacity using the structure beam property plastic-moment command. With this method, a hypothetical
hinge can form between beam elements; however, because the elements are joined with a single node, a true discontinuity in the rotational motion cannot develop at these
locations. The double-node method involves creating double nodes at each potential hinge location and then appropriately linking these nodes together. The double nodes
allow a discontinuity in the rotation to occur when the limiting plastic moment is reached. The double-node method should be applied to calculate the large-strain, post-failure
behavior of a structure. If it is only necessary to determine the solution at the limiting plastic moment, then the single-node method is sufficient. In the following discussion,
we first define the example problem, and then solve it in two ways by using the single-node method, and then using the double-node method.
Single Node
P
A concentrated vertical load, , is applied at the center of a 10 m long, simply supported beam with a plastic-moment capacity, , of 25 kN-m. The system, along
with the shear and moment diagrams, is shown in Figure 1. From these shear and moment diagrams, we find that the specified plastic-moment capacity corresponds with a
maximum vertical load of 10 kN and a maximum shear force of 5 kN. If we apply a constant vertical velocity to the beam center, we expect that the limiting values of moment
and shear force will be 25 kN-m and 5 kN, respectively.
../../../../../_images/plastichinge-
diagram.png
Figure 1: Single beam with single concentrated load.
The FLAC3D model demonstrating the single-node method (see "PlasticHinge-Single.f3dat") is created by issuing a single structure beam create command and
specifying two segments. This produces a model containing 2 elements and 3 nodes, with both elements sharing the center node (node ID of 3). The beam is assigned the
same properties as in the Concentrated Loads example but, in addition, the plastic-moment capacity is set to 25 kN-m with the structure beam property plastic-moment
y
command. Simple supports are specified at the beam ends by restricting translation in the -direction. A constant vertical velocity is applied to the center node, and the
moment and shear force acting at the right end of element 1 are monitored during the calculation to determine when the limiting value is reached. Note that we specify
combined local damping for this problem (structure damping combined-local) in order to eliminate the ringing that can occur with the default local damping scheme
when the system is being driven by a constant motion.
We find that the limiting values of moment and shear force are equal to the analytical values of 25 kN-m and 5 kN, respectively (see Figure 2 and Figure 3). Also, the moment
and shear force distributions correspond with the analytical solution (see Figure 4 and Figure 5). We also see that a discontinuity in the rotational motion at the center location
does not develop; the rotation of the center node is zero (structure node list displacement).
../../../../../_images/plastichinge-singlemom.png
Figure 2: Moment at right end of element 1 versus applied center displacement (single-node method).
../../../../../_images/plastichinge-singleshear.png
Figure 3: Shear force at right end of element 1 versus applied center displacement (single-node method).
../../../../../_images/plastichinge-singlemz.png
Figure 4: Moment distribution at limit condition (single-node method).
../../../../../_images/plastichinge-singlefy.png
Figure 5: Shear force distribution at limit condition (single-node method).
Double Node
The FLAC3D model demonstrating the double-node method (see "PlasticHinge-Double.f3dat") is created by issuing two separate structure beam create commands. This
produces a model containing two elements and four nodes. Going from left to right, the left element uses nodes 1 and 2, and the right element uses nodes 3 and 4. Note that
nodes 2 and 3 lie in the same location, but they will not interact with one another. We now create an appropriate linkage between nodes 2 and 3 with the commands
struct node join

struct link attach rotation-z=normal-yield
struct link property rotation-z area=1.0 stiffness=6.4e8 yield-compression=25e3 yield-tension=25e3
The first command creates a node-to-node link from node 2 to node 3. The second command changes the default attachment condition in the z-rotational direction from rigid
to deformable. The third command sets the properties of this normal-yield spring as follows. We set the area to unity, and we set both the compressive and tensile yield
strengths equal to the desired plastic-moment capacity of 25 kN-m. Finally, we set the spring stiffness equal to a value that is large enough to make the spring deformation
small relative to the beam deformation. We determine this value by computing the rotational stiffnesses of the two elements that use the spring (each rotational stiffness is
4
E , where is element length) and multiplying this value by 10.
Now that the double nodes have been appropriately linked to one another, the beam is assigned the same properties as in Concentrated Loads—we do not specify a plastic-
moment capacity, because we want the plastic moment to develop in the normal-yield spring. Simple supports are specified at the beam ends by restricting translation in the y-
direction. A constant vertical velocity is applied to the center nodes (the applied velocity of the node with the rigid attachment condition is ignored) and the moment and shear
force acting at the right end of element 1 are monitored during the calculation to determine when the limiting value is reached. Note that we specify combined local damping
for this problem (structure damping combined-local) in order to eliminate the ringing that can occur with the default local damping scheme when the system is being
driven by a constant motion.
We find that the limiting values of moment and shear force are equal to the analytical values of 25 kN-m and 5 kN, respectively (see Figure 6 and Figure 7). Also, the moment
and shear force distributions correspond with the analytical solution (see Figure 8 and Figure 9). We also see that a discontinuity in the rotational motion at the center location
has developed; the rotation of nodes 2 and 3 are nonzero and equal and opposite to each other (structure node list displacement).
../../../../../_images/plastichinge-doublemom.png
Figure 6: Moment at right end of element 1 versus applied center displacement (double-node method).
../../../../../_images/plastichinge-doubleshear.png
Figure 7: Shear force at right end of element 1 versus applied center displacement (double-node method).
../../../../../_images/plastichinge-doublemz.png
Figure 8: Moment distribution at limit condition (double-node method).
../../../../../_images/plastichinge-doublefy.png
Figure 9: Shear force distribution at limit condition (double-node method).
Double Node Cantilever
These two examples demonstrate that both the single-node and the double-node methods produce the same behavior near the limiting moment; however, if we were to
continue loading the structure in a large-strain fashion, then the double-node method would produce more reasonable results because it would allow a discontinuity to develop
in the rotation at the center. We illustrate this behavior by modifying the double-node example to represent a cantilever beam (fixed at the left end) with a vertical load applied
at the free end (see "PlasticHinge-Cantilever.f3dat"). The problem is run in large-strain mode, and the load is specified such that it will remain oriented in the negative y-
direction throughout the simulation.
The final structural configuration and moment distribution are shown in Figure 10. We see that the double-node method allows a discontinuity to develop in the rotation at the
beam center.
../../../../../_images/plastichinge-cantilevermz.png
Figure 10: Final structural configuration and moment distribution in cantilever (double-node method).
Data Files
PlasticHinge-Single.f3dat
model new
model title "Plastic hinge formation (single-node method)"
; Create beam and assign properties
struct beam create by-line (0,0,0) (10,0,0) segments=2
struct beam property young=2.0e11 poisson=0.30
struct beam property cross-sectional-area=6e-3 moi-z=200e-6 moi-y=200e-6 moi-polar=0.0
struct beam property plastic-moment=25e3
; Assign boundary conditions
struct node fix velocity-y range union position-x 0.0 position-x 10 ; simple support at left and right end
struct node fix velocity-y range position-x 5 ; apply constant vertical velocity
struct node initialize velocity-y -5e-6 local range position-x 5 ; to center node
; Take histories
struct node history name='disp' displacement-y position (5,0,0) ; y-displacement of center node
struct beam history name='mom' moment-z end 2 position (2.5,0,0) ; moment
struct beam history name='force' force-y end 2 position (2.5,0,0) ; shear force
; Set damping, and cycle
struct damping combined-local
model cycle 3000 ; .015 total displacmeent
model save 'Single'
PlasticHinge-Double.f3dat
; File for Plastic hinge formation (double-node method)

model new
model title "Plastic hinge formation (double-node method)"
; Create beams
struct beam create by-line (0,0,0) (5,0,0) id=1 segments=1
; Join nodes, and make the z rot link plastic
struct node join
; Assign beam boundary conditions
struct node fix velocity-y range union position-x 0.0 position-x 10 ; simple support at left and right end
; apply constant vertical velocity to center node-3 --- must apply velocity to target node.
struct node fix velocity-y range position-x 5 ; apply constant vertical velocity
struct node initialize velocity-y -5e-6 local range position-x 5 ; to center node
; Take histories
struct node history name='disp' displacement-y position (5,0,0) ; y-displacement of center node
struct beam history name='mom' moment-z end 2 position (2.5,0,0) ; moment
struct beam history name='force' force-y end 2 position (2.5,0,0) ; shear force
; Set damping and cycle
model cycle 3000 ; .015 total displacmeent
model save 'Double'
PlasticHinge-Cantilever.f3dat
; file for Plastic hinge formation in cantilever (double-node method)

model new
model title "Plastic hinge formation in cantilever (double-node method)"
; Create two beams
; Join nodes, and make the z rot link plastic
struct node join
struct node fix velocity rotation range position-x=0 ; fully fix left end
struct node apply force=(0,-5.5e3,0) range position-x=10 ; apply force at tip
; Assign daming, and cycle
Commands
Operations on structural element beams.
Beams implement classic 3D beam theory behavior and are by default rigidly connected to their surroundings.
Extrude Block Commands
structure beam apply

Assign uniform applied distributed loads.
structure beam create
Create a beam represented by one or more elements.
structure beam delete
Delete all beam elements in the range.
structure beam group
Assign all beam elements in the range to the group...
structure beam hide
This commands hides or un-hides all beam elements in the...
structure beam history
Samples beam responses that include force and moment carried by...
structure beam import
Create beam elements from an outside source.
structure beam initialize
Initializes quantities on the element.
structure beam list
List information about beam elements.
structure beam property
Assigns a property to elements in the range.
structure beam refine
This command refines an existing element in the range by...
structure beam select
This command selects or de-selects all elements in the range.
l structure beam apply command

l structure beam create command
l structure beam delete command
l structure beam group command
l structure beam hide command
l structure beam history command
l structure beam import command
l structure beam initialize command
l structure beam list command
l structure beam property command
l structure beam refine command
l structure beam select command
structure beam apply command

Syntax
structure beam apply f1 f2 <range>
Assign uniform applied distributed loads. Loads (force per unit length) are applied to all elements in the range. Positive loads act in the positive y- or z-directions (f1
and f2, respectively) of the element system and maintain this orientation during large-strain motion. Point loads are applied at the nodes using the command structure
node apply.
structure beam create command

Syntax
structure beam create keyword
Primary keywords:
by-line | by-nodeids | by-ray
The three main keywords articulate three different techniques of creation: by creating a collection of elements that lie between a beginning and an endpoint
(by-line); by specifying an element to be created from an existing pair of nodes (by-nodes); or by specifying an initial point and a direction to follow (by-
ray).
by-line v1 v2 [keywordblock]
creates one element that lies along a straight line between the locations v1 and v2. New nodes associated with the element will also be created (see the id
keyword). The nodal connectivity of each new element will be ordered such that the direction from v1 to v2 corresponds with the direction from the begin point
to the end point. If there are zones in these locations, the element will be attached to the zones at its nodes such that the translational degrees-of-freedom are
rigidly connected to the zones and the rotational degrees-of-freedom are free. If no attachment to zones is desired, then the links may be deleted with the
command structure link delete after creating and positioning the element.
by-nodeids i1 i2 [keywordblock]
specify the ID numbers (i1, i2) of two nodes that will define the element. These nodes must already exist—nodes can be created with the structure node
create command. Ordering of the nodes defines the beam element coordinate system as follows. The positive x-direction lies along the line from i1 to i2, and the
y-direction is found by projecting the global y- or x-directions onto the element cross-section. The y-direction can also be modified with the property direction-y.
the new element will not be attached to the grid; if you wish to attach it to the grid, then after creating it, position its nodes with the structure node
initialize position command (which will create links and set appropriate attachment conditions for all nodes that are moved into a zone).
by-ray v1 v2 f [keywordblock]
creates one element that lies along a straight line starting at v1, proceeding in the direction specified by v2 for a distance given by f. New nodes associated with
the element will also be created (see the id keyword). The nodal connectivity of each new element will be ordered such that the direction from v1 corresponds
with the direction from the begin point to the end point. If there are zones in these locations, the element will be attached to the zones at its nodes such that the
translational degrees-of-freedom are rigidly connected to the zones and the rotational degrees-of-freedom are free. If no attachment to zones is desired, then the
links may be deleted with the command structure link delete after creating and positioning the element.
Keyword Block
The following keywords may be provided optionally on element creation using any of the major keywords: by-line, by-nodeids and by-ray.
distinct
eliminates sharing of nodes among created elements. Every element will create a new set of nodes, even if they are at the same location in space and
elements share the same ID number. This option is most commonly used with a later structure node join command to create links connecting nodes at
the same location in order to apply custom inter-element behavior.
group s <slot s >
assigns all newly created elements to the group s. The optional keyword slot can be used to specify the group slot; if not specified, the group is assigned to
the slot Default. Use of the group logic is described in Group.
id i
specify the ID that will be assigned to all new elements created by this command. If this value is not given, then the next available ID will be used. The ID
controls potential joining of the two element end-nodes to an existing element as follows. At each end-node location, a new node is created unless all of the
following conditions are fulfilled: (1) the ID is given; (2) an existing node is found near the potential new node location; and (3) the found node is part of a
beam with ID equal to i.
maximum-length f
break the element into segments no greater than length f. The segments setting, if provided, is overridden as needed by this setting.
segments i
break the element into i equal segments, creating new nodes as needed. The default value is 1, indicating that only one element will be created.
snap 
indicates that the first and last positions of the element(s) created will attempt to "snap" to the location of the nearest structural node (attached to any
element type) within a radius of 1/2 the element length. If only one end is snapped in this manner, then the entire line created will be offset by the
difference between the original and the snapped position.
structure beam delete command

Syntax
structure beam delete <range>
Delete all beam elements in the range. Structure nodes and links that become disconnected from any element will automatically be deleted as well.
structure beam group command

Syntax
structure beam group s <keyword>
Primary keywords:
slot | remove
Assign all beam elements in the range to the group with the name s. Use of the group logic is described in Group. Any element may only belong to one group in a given
slot. Assigning an element to a new group in that slot will cause it to be removed from its current group assignment. The structure beam list group command lists
the existing element group names. The groups can be visualized with the beam plot item.
will be the slot, and the name to the right will be the group.
slot s
remove
structure beam hide command

Syntax
structure beam hide <keyword> <range>
Primary keywords:
b | undo
This commands hides or un-hides all beam elements in the range. By default, commands that use a range filter will skip hidden objects. This can be overruled with the
use-hidden keyword in the range specification.
if a boolean type is specified, and if on, it hides all elements in the range. If off, it un-hides (or shows) all elements in the range, and the use-hidden keyword is
undo
this will reverse the operation of the last structure beam hide command. FLAC3D keeps a maximum undo stack of size 12.
structure beam history command

Syntax
structure beam history <name s > keyword
Primary keywords:
force | force-x | force-y | force-z | moment | moment-x | moment-y | moment-z
Samples beam responses that include force and moment carried by the beam. The force and moment vectors are expressed in the element local coordinate system (see
Figure 1.17 for sign convention). If a beam is created using the structure beam create command, then the nodes of each element so created will be ordered such that
the overall beam direction goes from the first point to the second point (i.e., the nodal connectivity of each element will be ordered such that the direction from end-1 to
end-2 corresponds with the direction from the first point to the second point).
force [keywordblock]
request a history of beam force magnitude
request a history of beam forces in the x-direction
request a history of beam forces in the y-direction
request a history of beam forces in the z-direction
moment [keywordblock]
request a history of beam bending moment magnitude
request a history of beam bending moment in the x-direction
request a history of beam bending moment in the y-direction
request a history of beam bending moment in the z-direction
Keyword Block
Either the component-id keyword or the position keyword must be supplied. The end keyword is optional. force, force-x, force-y, force-z, moment, moment-
x, moment-y and moment-z.
component-id i
the particular element is identified by the component ID number. If this keyword is used, position should not be used.
end i
the quantity will be sampled at end i (where i is 1 or 2), which corresponds with the order in the nodal-connectivity list. The history is sampled at end 1 (the
default) if this keyword is not supplied.
position v
the particular element is identified by (v) coordinates (the nearest element is taken). If this keyword is used, component-id should not be used.
structure beam import command

Syntax
structure beam import keyword
Primary keywords:
from-file | from-geometry | from-extruder
from-file s <format keyword> [keywordblock]
Create elements from the geometry file s.
The optional format keyword can be used to specify the format of the file. The options are dxf, geom, or stl. [CS: work out what needs to happen here later;
formats should have links] If not specified, the format is assumed from the file extension.
from-geometry s [keywordblock] <range>
Create elements from the geometry set named s. The range applies to the list of edges in the geometry set.
from-extruder s [keywordblock] <range>
Create elements from the extruder set named s. The range applies to the list of edges in the extruder set.
Keyword Block
Any of the following keywords may be optionally supplied for use with the major keywords of structure beam import: from-extruder, from-file and from-
geometry.
distinct
Eliminate sharing of nodes among created elements. Every element will create a new set of nodes, even if they are at the same location in space and elements
share the same ID number. This option is most commonly used with a later structure node join command to create links connecting nodes at the same
location in order to apply custom inter-element behavior.
id i
Specify the ID that will be assigned to all new elements created by this command. If this value is not given, then the next available ID will be used. The ID
following conditions are fulfilled: (1) the ID is given; (2) an existing node is found “near” the potential new node location; and (3) the found node is part of an
element with ID equal to i.
group s <keyword>
Assign the elements created to group s. Use of the group logic is described in Group.
slot s
maximum-length f
Break the element into segments no greater than length f. The segments setting, if provided, is overridden as needed by this setting.
segments i
Break the element into i equal segments, creating new nodes as needed. The default value is 1.
snap 
Indicate that the first and last positions of the element(s) created will attempt to "snap" to the location of the nearest structural node (attached to any element type)
within a radius of 1/2 the element length. If only one end is snapped in this manner, then the entire line created will be offset by the difference between the
original and the snapped position.
structure beam initialize command

Syntax
structure beam initialize <keyword>
Primary keywords:
coupling
The following keywords are available.
coupling
finds any deformable links attached to the element and attempts to initialize the force to match the stress state of the link target
structure beam list command

Syntax
structure beam list keyword
Primary keywords:
apply | force-end | group | information | length | force-node | property | system-local
apply
list applied distributed loads
force-end
forces exerted by the end nodes on the element, in element local coordinates
group <slot s >
list group to which the element belongs. By default, lists all slots with group assignments. If the slot keyword is used, only the contents of that slot is listed.
information
lists general element information, including id and component-id numbers, connected nodes, centroids, surface area, volume, and the hide and select status
length
list length of the element
force-node keyword
list nodal forces. By default, components are displayed in terms of the element local coordinate systems. These are the forces exerted by the nodes on the element.
local
list forces in terms of the element local coordinate system (the default)
global
list forces in terms of the global coordinate system
property keyword
list element property information
density
density, ρ
youngs
Young’s modulus, E
poisson
Poisson’s ratio, ν
plastic-moment
plastic moment, MP
thermal-expansion
thermal expansion coefficient, αt
cross-sectional-area
cross-sectional area, A
moi-y
second moment with respect to local y-axis, Iy
moi-z
second moment with respect to local z-axis, Iz
moi-polar
polar moment of inertia, J
direction-y
y-axis vector components
system-local
the element local coordinate system
structure beam property command

Syntax
structure beam property keyword <range>
Primary keywords:
density | youngs | poisson | plastic-moment | thermal-expansion | cross-sectional-area | moi-y | moi-z | moi-polar | direction-y
Assigns a property to elements in the range. The following properties are available.
density f
density (needed if dynamic mode or gravity are active), ρ
youngs f
poisson f
plastic-moment f
plastic moment capacity, MP
thermal-expansion f
cross-sectional-area f
moi-y f
moi-z f
moi-polar f
direction-y v
y-axis vector components (Yx, Yy, Yz) whose projection onto the element cross-section defines the y-axis of the element system
structure beam refine command

Syntax
structure beam refine i <range>
This command refines an existing element in the range by subdividing it into i equal-size segments. The original structural element is deleted.
Usage Example
The following example illustrates how structure beam refine can be used to refine the first two elements of the beam with id 100:
struct beam create (0,0,0) (1,0,0) id 100 segments 5 ; Create the beam
struct beam refine 10 range id 100 x 0 0.4 ; Refine the first two elements into 20 new elements
structure beam select command

Syntax
structure beam select <keyword>
Primary keywords:
b | new | undo
This command selects or de-selects all elements in the range. Selected objects can be specified in a range filter by using the selected keyword. Objects that are not
selected can be specified in a range filter by using the deselected keyword.
if a boolean type is specified, and if on, it selects all elements in the range. If off, it de-selects all elements in the range. on is the default if no keyword is given.
new
implies on. This will select elements in the range and automatically de-select elements not in the range.
undo
this will reverse the operation of the last structure beam select command. FLAC3D keeps a maximum undo stack of size 12.
FISH Functions
FISH functions operating on beam elements. The type specifiers used in the FISH function signatures are given in the FISH Type Index section.
Note that all beam functions will also work with pile elements.
Structural Beam Functions
struct.beam.area(STRUCT_BEAM_PNT)
Get/set the cross-section area of the element.
struct.beam.force(STRUCT_BEAM_PNT,INT<,INT>)
Get the force at one end of the beam in...
struct.beam.force.nodal(STRUCT_BEAM_PNT,INT<,INT>)
Get the generalized nodal force acting at end iend in...
struct.beam.length(STRUCT_BEAM_PNT)
Get the length of the beam element.
struct.beam.load(STRUCT_BEAM_PNT<,INT>)
Get/set the uniform applied distributed load acting on the beam...
struct.beam.moi(STRUCT_BEAM_PNT<,INT>)
Get/set the moment of inertia of the beam.
struct.beam.moment(STRUCT_BEAM_PNT,INT<,INT>)
Get the moment at one end of the beam in...
struct.beam.moment.plastic(STRUCT_BEAM_PNT)
Get/set the plastic moment capacity in the beam.
struct.beam.poisson(STRUCT_BEAM_PNT)
Get/set the Poisson's ratio of the beam element.
struct.beam.volume(STRUCT_BEAM_PNT)
Get the beam element volume, or the cross-sectional area times...
struct.beam.ydir(STRUCT_BEAM_PNT<,INT>)
Get the y -axis of the beam element local system.
struct.beam.young(STRUCT_BEAM_PNT)
Get/set the Young's modulus of the beam element.
l struct.beam.area
l struct.beam.force
l struct.beam.force.nodal
l struct.beam.length
l struct.beam.load
l struct.beam.moi
l struct.beam.moment
l struct.beam.moment.plastic
l struct.beam.poisson
l struct.beam.volume
l struct.beam.ydir
l struct.beam.young
struct.beam.area
Syntax
f = struct.beam.area(p)
struct.beam.area(p) = f
Returns: f - the cross-sectional area of the element

Accepts: f - the cross-sectional area of the element
Arguments: p - a pointer to a beam element
struct.beam.force
Syntax
Vector Access
v = struct.beam.force(p,iend<,i>)
Get the force at one end of the beam in element local system.
Which end is determined by iend, which should be 1 or 2.
Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.
Returns: v - force at one end of the beam

Arguments: p - a beam pointer
iend - indicates which end of the beam is used, can be 1 or 2
Component Access
f = struct.beam.force.x(p,iend)
Get the x-component of the force at end iend in element local system.
Returns: f - x-component of the y-axis of the local system of the beam element
f = struct.beam.force.y(p,iend)
Get the y-component of the force at end iend in element local system.
Returns: f - y-component of the y-axis of the local system of the beam element
f = struct.beam.force.z(p,iend)
Get the z-component of the force at end iend in element local system.
Returns: f - z-component of the y-axis of the local system of the beam element
struct.beam.force.nodal
Syntax
m = struct.beam.force.nodal(p,iend<,idof>)
Get the generalized nodal force acting at end iend in global system.
If the optional argument idof is provided, returns the force in that specific degree-of-freedom (from 1 to 6).
Returns: m - a 1×6 matrix with the generalized nodal force at end iend, or the value of specific degree-of-freedom idof
iend - indicates which end of the beam, either 1 or 2
struct.beam.length
Syntax
f = struct.beam.length(p)
Returns: f - the length of the beam

struct.beam.load
Syntax
v = struct.beam.load(p<,idof>)
struct.beam.load(p<,idof>) = v
Get/set the uniform applied distributed load acting on the beam element in the local y- and z-directions.
The x-component of the return value will always be 0.0; on assignment it is ignored.
The optional argument idof can be used to specify whether only the value in the y- or z-direction will be returned/assigned.
Returns: v - the uniform applied distributed load acting on the beam element, or the y- or z-component
Accepts: v - the uniform applied distributed load acting on the beam element, or the y- or z-component
idof - an optional degree-of-freedom indication, which should be 2 or 3
struct.beam.moi
Syntax
Vector Access
v = struct.beam.moi(p<,i>)
struct.beam.moi(p<,i>) = v
This is defined as the second moment of inertia with respect to the x-, y-, and z-axes.
Returns: v - moment of inertia vector or component

Accepts: v - moment of inertia vector or component
Component Access
f = struct.beam.moi.x(p)
struct.beam.moi.x(p) = f
Get/set the second moment of inertia with respect to the x-axis.
Returns: f - x-component moment of inertia vector

Accepts: f - x-component moment of inertia vector
f = struct.beam.moi.y(p)
struct.beam.moi.y(p) = f
Get/set the second moment of inertia with respect to the y-axis.
Returns: f - y-component moment of inertia vector

Accepts: f - y-component moment of inertia vector
f = struct.beam.moi.z(p)
struct.beam.moi.z(p) = f
Get/set the second moment of inertia with respect to the z-axis.
Returns: f - z-component moment of inertia vector

Accepts: f - z-component moment of inertia vector
struct.beam.moment
Syntax
Vector Access
v = struct.beam.moment(p,iend<,i>)
Get the moment at one end of the beam in element local system.
Which end is determined by iend, which should be 1 or 2.
Returns: v - moment at one end of the beam

Component Access
f = struct.beam.moment.x(p,iend)
Get the x-component of the moment at end iend in element local system.
f = struct.beam.moment.y(p,iend)
Get the y-component of the moment at end iend in element local system.
f = struct.beam.moment.z(p,iend)
Get the z-component of the moment at end iend in element local system.
struct.beam.moment.plastic
Syntax
f = struct.beam.moment.plastic(p)
struct.beam.moment.plastic(p) = f
Returns: f - the plastic moment capacity of the beam

Accepts: f - the plastic moment capacity of the beam
Arguments: p - a pointer to a structural beam element
struct.beam.poisson
Syntax
f = struct.beam.poisson(p)
struct.beam.poisson(p) = f
Returns: f - the Poisson's ratio of the beam element

Accepts: f - the Poisson's ratio of the beam element
struct.beam.volume
Syntax
f = struct.beam.volume(p)
Get the beam element volume, or the cross-sectional area times the length.
Returns: f - the beam element volume

struct.beam.ydir
Syntax
Vector Access
v = struct.beam.ydir(p<,i>)
Get the y-axis of the beam element local system. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.
Returns: v - local system y-axis vector or component

Component Access
f = struct.beam.ydir.x(p)
Get the x-component of the y-axis of the beam element local system.
f = struct.beam.ydir.y(p)
Get the y-component of the y-axis of the beam element local system.
f = struct.beam.ydir.z(p)
Get the z-component of the y-axis of the beam element local system.
struct.beam.young
Syntax
f = struct.beam.young(p)
struct.beam.young(p) = f
Returns: f - the Young's modulus of the beam element

Accepts: f - the Young's modulus of the beam element
Cable Structural Elements

Cable and bolt reinforcements in rock have two somewhat different functions. In hard rock subjected to low magnitude in-situ stress fields, failure is often localized and
limited to wedges of rock directly adjacent to openings. The effect of the rock-bolt reinforcement here is to provide a local resistance to wedge displacement at the joint
surfaces. In some cases, the bending, in addition to the axial stiffness of the reinforcement, may be important in resisting shear deformations. In FLAC3D, this type of bolt
action may be modeled using pile structural elements, which have a flexural rigidity (see Pile Structural Elements). If bending effects are not important, cable structural
elements are sufficient, because they provide a shearing resistance (by means of the grout properties) along their length. One can model reinforcing systems (e.g., cable bolts)
in which the bonding agent (grout) may fail in shear over some length of the reinforcement. The numerical formulation that accounts for this shear behavior of the grout
annulus is described in Shear Behavior of Grout Annulus.
Mechanical Behavior
Each cable structural element is defined by its geometric, material and grout properties. A cable element is assumed to be a straight segment of uniform cross-sectional and
material properties lying between two nodal points. An arbitrarily curved structural cable can be modeled as a curvilinear structure composed of a collection of cable
elements. The cable element behaves as an elastic, perfectly plastic material that can yield in tension and compression, but cannot resist a bending moment. A cable may be
grouted such that force develops along its length in response to relative motion between the cable and the grid. The grout behaves as an elastic, perfectly plastic material, with
its peak strength being confining stress dependent, and with no loss of strength after failure. Cable elements are suitable for modeling structural-support members in which
tensile capacity is important, and for which axially directed frictional interaction with the rock or soil mass occurs.
Each cable element has its own local coordinate system, shown in Figure 1. This system is used to define the average axial cable direction. The cable element coordinate
system is defined by the locations of its two nodal points, labeled as 1 and 2 in Figure 1. The element coordinate system is defined such that

x
y y x
3. the -axis is aligned with the projection of the global - or -direction (whichever is not parallel with the local -axis) onto the cross-
sectional plane.
system1.png
Figure 1: Cable element coordinate system and 2 active degrees-of-freedom of the cable finite element
The cable element coordinate system cannot be modified. It can be viewed with the Cable plot item and printed with the structure cable list system-local command.
The nodal connectivity can be printed with the structure cable list information command.
The orientation of the node-local system for all nodes used by cable elements is set automatically at the start of a set of cycles (or when the model cycle 0 command is
y
executed), such that the -axis is aligned with the average axial direction of all cable elements using the node, and the -axes are arbitrarily oriented in the cable
cross-sectional plane.
Cables support large-strain sliding (by setting the slide property to on) whereby the interpolation locations (used by the cable nodes to transfer forces and velocities to and
from the zones — see Structural-Element Links) will migrate through the grid when running in large-strain mode. This allows one to calculate the large-strain, post-failure
behavior of a cable whereby substantial sliding between the cable nodes and the zones occurs. If a cable node moves out of all zones, then a connection with the zones will not
be reestablished if the node is later moved back into zones; however, the connection remains intact as the cable nodes slide between zones.
The two active degrees-of-freedom of the cable finite element are shown in Figure 1. For each axial displacement shown in the figure, there is a corresponding axial force.
The stiffness matrix of the cable finite element includes only this single degree-of-freedom at each node to represent axial action within a cable structure.
The following four subsections describe (1) the axial behavior of the cable itself, (2) the shear behavior of the grout annulus, (3) the normal behavior at the grout interface,
and (4) the means by which cables may be pretensioned. The behavior is described in terms of the cable properties listed in Properties (refer to this list for a summary of
relevant notations).
Axial Behavior
The axial behavior of conventional reinforcement systems may be assumed to be governed entirely by the reinforcing member itself. The reinforcing member is usually
composed of steel, and may be either a bar or a cable. Because the reinforcing member is slender, it offers little bending resistance (particularly in the case of a cable), and is
treated as a one-dimensional structural member with the capacity to sustain uniaxial tension. (Compression is also allowed; however, when modeling support that is primarily
loaded in compression, pile structural elements are recommended.)
A one-dimensional constitutive model is adequate for describing the axial behavior of the reinforcing member. The axial stiffness, , is determined based on the
A E
reinforcement cross-sectional area, , Young's modulus, , and element length, , by the relation
K = {A E
\over L}
A tensile- and compressive-yield strength, and , may be assigned to the cable element such that cable forces that are greater than these limits cannot develop
F
(see Figure 2). If either or is not specified, the cable will have infinite strength for loading in that direction.
../../../../../../_images/material-
behavior.png
Figure 2: Cable material behavior for elements
In evaluating the axial forces that develop in the reinforcement, displacements are computed at nodal points along the reinforcement axis, as shown in Figure 3. Out-of-
balance forces at each node are computed from axial force in the reinforcement, as well as shear forces contributed through shear interaction along the grout annulus. Axial
displacements are computed by integrating the nodal accelerations using the out-of-balance axial force and a mass lumped at each node.
../../../../../../_images/mechanical-
representation.png
Figure 3: Mechanical representation of fully bonded reinforcement
Shear Behavior of Grout Annulus
The shear behavior of the cable-rock interface is cohesive and frictional in nature. The system is idealized (as shown in Figure 4 (a)), and represented numerically as a spring-
slider system located at the nodal points along the cable axis (as shown in Figure 3). The shear behavior of the grout annulus during relative shear displacement between the
cable/grout interface and the grout/rock interface (as shown in Figure 4 (b)) is described numerically by (1) the grout shear stiffness, , (2) the grout cohesive strength,
\ \sig
, (3) the grout friction angle, , (4) the grout exposed perimeter,
p , and (5) the effective confining stress, ( Figure 4 (c)). The mechanical
behavior of the grouted-cable system is depicted in terms of these parameters in Figure 5. Note that the grout properties associated with each cable element are averaged at
cable nodes.
../../../../../../_images/grouted-cable-
system.png
Figure 4: Idealization of grouted-cable system
../../../../../../_images/grout-material-
behavior.png
Figure 5: Grout material behavior for cable elements
\sig
The effective confining stress, , acts in the plane perpendicular to the cable axis, and is computed at each nodal point along the cable axis, based on the stress
y \sig
acting in the zone to which the nodal point is linked. Denote the cable-axis direction as , and denote the principal stresses acting in the '-plane as and
\sig \sigma_1 > \sig
, such that \sigma_2 (tension positive). Then the value of is taken as
\sigma_m = - \bigl ({{\sigma_1 + \sigma_2}\over 2} + p

\bigr )
where = pore pressure
In computing the relative displacement at the cable-rock interface, an interpolation scheme is used to calculate the displacement of the rock in the cable axial direction at each
cable node, based on the displacement field in the zone to which the node is linked. The interpolation scheme uses weighting factors that are determined by the distance to
each of the gridpoints of the zone. The same interpolation scheme is used to apply forces developed at the cable-rock interface back to the gridpoints of the zone.
Normal Behavior at Grout Interface
As explained above, an interpolated estimate of grid velocity is made at each cable node. The velocity normal to the cable-axis direction is transferred directly to the node
(i.e., the cable node is "slaved" to the grid motion in the normal direction). The node exerts no normal force on the grid if the two cable elements that share the node are
colinear; however, if the two elements are not colinear, then a proportion of their axial forces will act in the normal direction. This net force acts both on the grid and on the
cable node (in opposite directions). Thus, an initially straight cable can sustain normal loading if it is allowed finite deflection, using the large-strain solution mode.
Pretensioning
Cables may be pretensioned via the structure cable apply tension command. A positive value assigns a tensile axial force into all of the cable elements that fall within
the range. This tension will be maintained until released with the structure cable apply tension active off command. Note that removing the tension apply condition
does not change the current axial force in the cable element, it just removes the condition maintaining that force at a specific level.
In practice, pretensioned cables may be fully grouted, or they may be left ungrouted over part of their length. In either case, some anchorage length is provided (usually at the
far end) to support the cable during pretensioning. To simulate this pretensioning in FLAC3D, one need only specify anchorage properties for the cable elements making up
c_
the anchorage length, and other properties (e.g., ) for the elements making up the free length.
It is important to note that the cable with specified pretension is initially unlikely to be in equilibrium with other structural elements or the FLAC3D grid to which it is linked.
In other words, some displacement of the cable nodes and linked entities is probably required to achieve equilibrium. As a result, properly pretentioning cables generally is
done in three commands:
struct cable apply tension value 1000 range group 'pretension'

model solve
struct cable apply tension active off
The first command applies tension to a specific set of cable elements (previously tagged with the pretension group name for this purpose). The second command solves to
equilibrium. The third command removes the applied tension value, so that the cable will respond naturally from then on.
For an example of this in practice, please see Installation of a Triple-Anchored Excavation Wall or Impermeable Concrete Caisson Wall with Pretensioned Tiebacks.
Response Quantities
Cable responses include force, stress and yield state of the cable element itself, and stress, displacement and slip state of the shear coupling springs that represent the grout.
Additional coupling-spring information includes the current loading direction and the confining stress. The cable responses can be accessed via FISH and
1. printed with one of the keywords available to the the structure cable list command,
2. monitored with the structure cable history command, and
3. plotted with the Cable plot item.
The sign of the grout stress refers to the average axial cable direction such that positive grout stresses act on the cable in the positive average axial cable direction. This sign
convention assumes that the set of elements making up the cable are oriented consistently, such that their local coordinate systems form a continuous description of the cable
orientation. Such will be the case if the cable is created using the structure cable create command. The nodes of each element so created will be ordered such that the
overall cable direction goes from the first point to the second point. The nodal connectivity can be printed with the structure cable list information command.
Properties
Each cable element possesses 12 properties:
1. density, mass density, ρ (optional — needed if dynamic mode or gravity is active) [M/L3]
2. young, Young's modulus, E [F/L2]
3. grout-cohesion, grout cohesive strength (force) per unit length, cg [F/L]
4. grout-friction, grout friction angle, ϕg [degrees]
5. grout-stiffness, grout stiffness per unit length, kg [F/L2]
6. grout_perimeter, grout exposed perimeter, pg [L]
7. slide, large-strain sliding flag (default: off)
8. slide-tolerance, large-strain sliding tolerance
9. thermal-expansion, thermal-expansion coefficient, αt [1/T] (optional — used for thermal analysis)
10. cross-section-area, cross-sectional area, A [L2]
11. yield-compression, compressive yield strength (force), Fc [F]
12. yield-tension, tensile yield strength (force), Ft [F]
The area, modulus and yield strength of the cable are usually readily available from handbooks, manufacturer's specifications, etc. The grout properties are more difficult to
estimate. The grout annulus is assumed to behave as an elastic-perfectly plastic solid. As a result of relative shear displacement, , between the tendon surface and the
borehole surface, the shear force, , mobilized per length of cable is related to the grout stiffness, :
F^t\ =\ k_g
\ u^t
Usually, can be measured directly in laboratory pull-out tests. Alternatively, the stiffness can be calculated from a numerical estimate for the elastic shear stress,
\t
a , obtained from an equation describing the shear stress at the grout/rock interface (St. John and Van Dillen 1983):
\tau_G =\ {G \over {(D/2+t)}}\ \ \ {\Delta u \over {\ln

(1+2t/D)}}
where: \D = relative displacement between the element and the surrounding material;
elt
= grout shear modulus;
= reinforcing diameter; and
= annulus thickness.
Consequently, the grout shear stiffness, , is simply given by
k_g\ =\ {2\pi\ G \over {\ln\

(1+2t/D)}}
k
In many cases, the following expression has been found to provide a reasonable estimate of for use in FLAC3D:
k_g\ \simeq\ {2\pi\ G \over {10\ \ln\

(1) (1+2t/D)}}
The one-tenth factor helps to account for the relative shear displacement that occurs between the host-zone gridpoints and the borehole surface. This relative shear
displacement is not accounted for in the present formulation.
The maximum shear force per cable length in the grout is determined by the relation illustrated in Figure 2. The values for bond cohesive strength, , and friction angle,
\
p , can be estimated from the results of pull-out tests conducted at different confining pressures or, should such results not be available, the maximum force per length
may be approximated from the peak shear strength (St. John and Van Dillen 1983):
{\tau_{peak}\ =\
\tau_IQ_B}
\
where t is approximately one-half of the uniaxial compressive strength of the weaker of the rock and grout, and is the quality of the bond between the grout
and rock ( = 1 for perfect bonding).
Neglecting frictional confinement effects, may then be obtained from
c_g\ =\ \pi (D + 2t)\ \tau_

(2) {peak}
Failure of reinforcing systems does not always occur at the grout/rock interface. Failure may occur at the reinforcing/grout interface, as is often true for cable reinforcing. In
D
such cases, the shear stress should be evaluated at this interface. This means that the expression ( ) is replaced by ( ) in (2).
The calculation of cable element properties is demonstrated by the following example. A 25.4 mm (1 inch)-diameter locked-coil cable was installed at 2.5 m spacing. The
reinforcing system is characterized by several properties:
25.4 mm
cable diameter ( )
D 38 mm
hole diameter ( +)
E 98.6 GPa
cable modulus ( )
cable ultimate tensile capacity 0.548 MN
grout compressive strength 20 MPa
9 GPa
grout shear modulus ( )
friction (ignored) 0
Two independent methods are used in evaluating the maximum shear force in the grout. In the first method, the bond shear strength is assumed to be one-half the uniaxial
compressive strength of the grout. If the grout-material compressive strength is 20 MPa, and the grout is weaker than the surrounding rock, the grout shear strength is then 10
MPa.
In the second method, reported pull-out data are used to estimate the grout shear strength. The report presents results for 15.9 mm (5/8 inch)-diameter steel cables grouted
with a 0.15 m (5.9 inch) bond length in holes of varying depths. The testing indicated capacities of roughly 70 kN. If a surface area of 0.0075 m2 (0.15 m × 0.05 m) is
assumed for the cables, then the calculated maximum shear strength of the grout is
{70\ \hbox{x}\ 10^3\ \hbox{N} \over {0.0075\ \hbox{m}^2}} = 9.33\ \hbox{x}\ 10^6\ \hbox{N/m}^2 = 9.33\ \hbox
{MPa}
This value agrees closely with the 10 MPa estimated above, and either value could be used. Assuming failure occurs at the cable/grout interface, the maximum bond force per
D D
length is (using (2) with + replaced by )
c_g = \pi (0.0254 m) (10 MPa) = 800

kN/m
, is estimated from (1). For the assumed values shown above, a grout stiffness of 1.5 × 1010
{N/m \over
The grout stiffness, {m}} is calculated.
Another example estimation of grout properties from pull-out tests is presented in Simulation of Pull-Tests for Fully Bonded Rock Reinforcement
Simple examples are given to illustrate the use of cables.
l Cable-Reinforced Beam
l Soil Nailing
A complete list of examples that use cable elements is available in Structural Cable Examples.
Commands & FISH

l Commands
l FISH Functions
Cable-Reinforced Beam
Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Cable/ReinforcedBeam" and select "ReinforcedBeam.f3prj" to load. The
main data files used are shown at the end of this example. The remaining data files can be found in the project.
This example illustrates the behavior of a simply supported, lightly reinforced beam subjected to gravity loading. Cable elements are used to represent the reinforcement.
A vertical crack is created through the beam center by adding a zero-strength interface. If the model is run without reinforcement (by removing the structure cable create
commands), the system behaves as two separate pieces that separate at the interface. The two blocks are supported on rollers; thus, they can move away from one another as
the system collapses (see Figure 1).
../../../../../_images/reinforcedbeam-geom.png
Figure 1: Structural configuration after 3000 cycles (no cable present).
If the model is rerun with a cable inserted within the beam near its bottom fiber, then the cable carries the tension that develops in the lower portion of the beam. The final
axial force distribution in the cable after the model has stabilized is shown in Figure 2. These tensile forces in the cable are produced by the grout stresses that have developed
along the cable length (see Figure 3). The maximum vertical center line displacement is approximately 10 mm.
../../../../../_images/reinforcedbeam-disp.png
Figure 2: Final axial force distribution in cable.
../../../../../_images/reinforcedbeam-grout.png
Figure 3: Final grout stress distribution.
The average axial direction of the cable goes from left to right, corresponding with the orientation of the points given with the structure cable create by-line
command. In Figure 3, we see that the grout stresses are positive on the right side of the cable and negative on the left side of the cable. These values can be printed with the
structure cable list grout command.
In the previous model, the grout cohesive strength was set to a very large value to prevent grout failure. If we set the grout cohesive strength equal to 1.5 × 105 N/m and rerun
the model, we find that the system still stabilizes; however, during the loading process, the grout yields (cable slips) in the middle region (see Figure 4). The grout stress in
this region is equal to the grout cohesive strength (see Figure 5), the tensile force is distributed farther along the cable (compare Figure 2 and Figure 6), and the maximum
vertical centerline displacement has increased from 10 mm to 11.8 mm.
../../../../../_images/reinforcedbeam-failstate.png
Figure 4: Final grout slip state (reduced grout cohesive strength).
../../../../../_images/reinforcedbeam-failgrout.png
Figure 5: Final grout stress distribution (reduced grout cohesive strength).
../../../../../_images/reinforcedbeam-faildisp.png
Figure 6: Final axial force distribution in cable (reduced grout cohesive strength).
Data File
ReinforcedBeam.f3dat
model new
model title "Cable-reinforced beam"
; Create beam (composed of zones)
zone face skin ; Label model boundaries
; Create interface betweenthe two
zone interface 1 create by-face separate range position-x 6.0
zone interface 1 node property stiffness-normal 1e10 stiffness-shear 1e10 friction 0
zone interface 1 tolerance-contact 1e-2
; Assign constitutive model and properties
zone cmodel assign elastic
zone property bulk 1e9 shear .3e9
zone initialize density 2400
; Boundary conditions - pin on right and left lower corners
zone gridpoint fix velocity-z 0 range position-z 0 position-x 0
zone gridpoint fix velocity-z 0 range position-z 0 position-x 12
; Setup model
model gravity 10
model save 'Start'
; Run problem with no cable present
zone mechanical damping combined
model cycle 3000

model save 'NoCable'
; Now rerun problem with a cable present
model restore 'Start'
; Create Cable and set properties
struct cable create by-line (0.1, 0.5, 0.1) (11.9, 0.5, 0.1) id=1 segments=13
struct cable property cross-sectional-area=2e-3 young=200e9 yield-tension=1e20 grout-stiffness=1e10 grout-cohesion=1e20 ; 1e11
zone mechanical damping combined
model save 'Cable'
; Now allow the cable to fail
struct cable property grout-cohesion 1.5e5
model save 'CableFail'
Soil Nailing
Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Cable/SoilNailing" and select "SoilNailing.f3prj" to load. The main data
This example demonstrates the ability of cable elements to simulate support provided by materials such as soil nails in the construction of reinforced embankments. In this
example, three soil nails are installed at different levels in a vertical embankment. Two conditions are examined: (1) only cohesive resistance is assumed between the nails and
the soil; and (2) both cohesive and frictional resistance are included.
In the first case, the soil nails are not sufficient to support the embankment. Figure 1 shows the axial forces in the cables, and indicates that the slip condition has been reached
in the grout for all nodes.
In the second case, by including a frictional resistance at the nail/soil interface of 25°, the nails are now sufficient to stabilize the embankment. Figure 2 plots the axial forces
in the cables for this case. Note that significantly higher axial forces can now develop as a result of the frictional resistance.
../../../../../_images/soilnailing-low.png
Figure 1: Axial forces in nails with only cohesive strength at soil/nail interface (the embankment is collapsing).
../../../../../_images/soilnailing-high.png
Figure 2: Axial forces in nails with both frictional and cohesive strength at soil/nail interface (the embankment is stable).
Data File
SoilNailing.f3dat
model new
model title "Soil nailing (using cables)"
; Create zones
zone face skin ; Name model boundaries
; Assign constitutive model and properties
zone property bulk 5e9 shear 1e9 cohesion 4e4 friction 30 density 2000
zone face apply velocity (0,0,0) range group 'Bottom'
; initial conditions
model gravity 10
zone initialize-stresses ratio 0.6,0.4
; Solve to initial equilibrium (should be instant)
; Release boundary condition on left
zone face apply-remove range group 'West'
; Create cables, and assign properties
struct cable create by-ray (0,0.5,3.5) (1,0,0) 8 segments=8

struct cable property cross-sectional-area=5.02e-3 young=200e9 yield-tension=1e10 grout-stiffness=7e6 grout-cohesion=1e2
model save 'Start'
; Cycle to equilibrium - we expect to fail so limit cycles as well
model solve ratio-local 1e-4 cycles 5000
model save 'LowFriction'
;
; Re-run with higher friction
struct cable property grout-perimeter=0.314 grout-friction=25
model save 'HighFriction'
Commands
Operations on structural element cables.
Cable elements do not support moment transmission. Cables are typically rigidly connected to their surroundings in the directions normal to their element direction and have a
deformable connected (governed by grout properties) in the direction parallel to the element.
Structural Element Cable Commands
structure cable apply

Applies conditions to cable elements in the range.
structure cable create
Create a cable, represented by one or more elements.
structure cable delete
Delete all cable elements in the range.
structure cable group
Assign all cable elements in the range to the group...
structure cable hide
This commands hides or un-hides all cable elements in the...
structure cable history
Sample cable responses.
structure cable import
Create cable elements from an outside source.
structure cable initialize
structure cable list
List information about cables.
structure cable property
structure cable refine
structure cable select
This commands selects or de-selects all elements in the range.
l structure cable apply command

l structure cable create command
l structure cable delete command
l structure cable group command
l structure cable hide command
l structure cable history command
l structure cable import command
l structure cable initialize command
l structure cable list command
l structure cable property command
l structure cable refine command
l structure cable select command
structure cable apply command

Syntax
structure cable apply keyword <range>
Applies conditions to cable elements in the range. The following keywords and options are available:
f1 f2
assign uniform applied distributed loads. Loads (force per unit length) are applied to all elements in the range. Positive loads act in the positive y- or z-directions
(f1 and f2, respectively) of the element system and maintain this orientation during large-strain motion. Point loads are applied at the nodes using the command
structure node apply .
tension keyword
assign a specific axial tension value in the cable element that will be maintained during cycling. Incomplete sentence follows: This is intended as a way to pre-
tension cables, but applying the pre-tension force as a tension to the end cable element(s), that are generally ungrouted. [DR: why is this flagged?] Note that this
setting will override the normal force-displacement law for the cable element as long as it is active. Removing the condition will not remove the force, but from
then on, the cable element forces will evolve naturally.
active b
make the tensile apply condition active or inactive. If active, the last specified value of tension is used, which is 0.0 by default.
value f
set the axial tensile force applied to the element f. This makes the condition active automatically.
structure cable create command

Syntax
structure cable create keyword
Primary keywords:
(by-line); by specifying an element to be created from an existing pair of nodes (by-nodeids); or by specifying an initial point and a direction to follow (by-
ray).
Create one element that lies along a straight line between the locations v1 and v2. New nodes associated with the element will also be created (see the id
Specify the ID numbers (i1, i2) of two nodes that will define the element. These nodes must already exist—nodes can be created with the structure node
create command. Ordering of the nodes defines the beam element coordinate system as follows. The positive x-direction lies along the line from i1 to i2, and the
The new element will not be attached to the grid. If you wish to attach it to the grid, then after creating it, position its nodes with the structure node
Create one element that lies along a straight line starting at v1, proceeding in the direction specified by v2 for a distance given by f. New nodes associated with
Keyword Block
The following keywords may be optionally provided on element creation, using any of the major keywords: by-line, by-nodeids and by-ray.
distinct
Eliminate sharing of nodes among created elements. Every element will create a new set of nodes, even if they are at the same location in space and
group s <slot s >
Assign all newly created elements to the group s. If the optional keyword slot can be used to specify the group slot, if not specified the group is assigned to
id i
following conditions are fulfilled: 1) the ID is given; 2) an existing node is found near the potential new node location; and 3) the found node is part of a
beam with ID equal to i.
maximum-length f
segments i
Break the element into i equal segments, creating new nodes as needed. The default value is 1, indicating that only one element will be created.
snap 
Indicate that the first and last positions of the element(s) created will attempt to "snap" to the location of the nearest structural node (attached to any
structure cable delete command

Syntax
structure cable delete <range>
Delete all cable elements in the range. Structure nodes and links that become disconnected from any element will automatically be deleted as well.
structure cable group command

Syntax
structure cable group s <keyword>
Assign all cable elements in the range to the group with the name s. Use of the group logic is described in Group. Any element may only belong to one group in a given
slot. Assigning an element to a new group in that slot will cause it to be removed from its current group assignment. The command structure cable list group
command lists the existing element group names. The groups can be visualized with the cable plot item.
slot s
remove
structure cable hide command

Syntax
structure cable hide <keyword>
Primary keywords:
b | undo
This commands hides or un-hides all cable elements in the range. By default, commands that use a range filter will skip hidden objects. This can be overruled with the
undo
this will reverse the operation of the last structure cable hide command. FLAC3D keeps a maximum undo stack of size 12.
structure cable history command

Syntax
structure cable history keyword
Primary keywords:
force | stress | yield-tension | yield-compression | grout-displacement | grout-slip | grout-stress
Sample cable responses. Quantities for sampling include cable element force, stress and yield state, and shear coupling spring displacement, stress and slip state. If a
cable is created using the structure cable create command, then the nodes of each element so created will be ordered such that the overall cable direction goes
from the begin point to the end point (i.e., the nodal connectivity of each element will be ordered such that the direction from end-1 to end-2 corresponds with the
direction from the begin point to the end point).
average axial force in the element (positive: tension; negative: compression)
average axial stress in the element (positive: tension; negative: compression)
yield-tension [keywordblock]
tensile yield state of the element. Value {0, 1, 2} denotes never yielded, now yielding, or yielded in the past, respectively.
yield-compression [keywordblock]
compressive yield state of the element. Value {0, 1, 2} denotes never yielded, now yielding, or yielded in the past, respectively.
grout-displacement [keywordblock]
displacement in grout (shear coupling spring) at end of the element. Sign convention is +/- with respect to the average axial direction of cable.
grout-slip [keywordblock]
slip state in grout (shear coupling spring) at end of the element. Value {0, 1, 2} denotes never slipped, now slipping, or slipped in the past, respectively.
grout-stress [keywordblock]
stress in grout (shear coupling spring) at end of the element. Sign convention is +/- with respect to the average axial direction of cable.
Keyword Block
Either the component-id keyword or the position keyword must be supplied. The end keyword is optional. These keywords are supplied with the following
keywords of structure cable history: I cant figure out why the wrong keyword list is appearing here. It is the same as the cable create command that works
fine [DR: What is this comment in reference to? inline help perhaps? can't identify the problem...] force, grout-displacement, grout-slip, grout-stress,
stress, yield-compression and yield-tension.
component-id i
the particular element is identified by the component ID number. If this keyword is used, position should not be used.
end i
position v
structure cable import command

Syntax
structure cable import keyword
Primary keywords:
The optional format keyword can be used to specify the format of the file. The options are: dxf, geom, or stl. [CS: work out what needs to happen here later;
Keyword Block
Any of the following keywords may be optionally supplied for use with the major keywords of structure cable import: from-extruder, from-file and from-
geometry.
distinct
id i
following conditions are fulfilled: 1) the ID is given; 2) an existing node is found “near” the potential new node location; and 3) the found node is part of an
group s <keyword>
slot s
maximum-length f
segments i
snap 
structure cable initialize command

Syntax
structure cable initialize <keyword>
Primary keywords:
coupling | force-axial
coupling
force-axial f
initializes the axial force in the element to f by setting the internal nodal forces. Note that this will override the existing internal nodal translational force state in
the element.
structure cable list command

Syntax
structure cable list keyword
Primary keywords:
apply | force-axial | force-node | group | grout | information | length | property | stress | system-local | yield
apply
list applied distributed loads
force-axial
axial forces exerted by the nodes on the element
force-node keyword
local
global
group <slot s >
grout
shear stress in the grout
information
length
list length of the element
property keyword <range>

density
density, ρ
youngs
poisson
grout-cohesion
grout cohesive strength, cg
grout-friction
grout friction angle, φg
grout-stiffness
grout stiffness, kg
grout-perimeter
grout exposed perimeter, pg
plastic-moment
plastic moment, MP
slide
sliding flag
slide-tolerance
sliding tolerance
thermal-expansion
yield-compression
compressive yield strength, Fc
yield-tension
tensile yield strength, Ft
stress
axial stress in the element
system-local
yield
indicator of whether or not the element itself has yielded
structure cable property command

Syntax
structure cable property keyword
Primary keywords:
density | young | grout-cohesion | grout-friction | grout-stiffness | grout-perimeter | plastic-moment | slide | slide-tolerance | thermal-expansion | cross-sectional-area |
yield-compression | yield-tension
Assigns a property to elements in the range. The following properties are available:
density f
density (needed if dynamic mode or gravity are active), ρ
young f
grout-cohesion , f
grout cohesive strength, cg
grout-friction f
grout friction angle, φg
grout-stiffness f
grout stiffness, kg
grout-perimeter f
grout exposed perimeter, pg
plastic-moment f
plastic moment, MP
slide b
sliding flag
slide-tolerance f
sliding tolerance
thermal-expansion f
yield-compression f
compressive yield strength, Fc
yield-tension f
tensile yield strength, Ft
structure cable refine command

Syntax
structure cable refine i <range>
This command refines an existing element in the range by subdividing it into i equal-size segments. The original structural element is deleted.
structure cable select command

Syntax
structure cable select <keyword>
Primary keywords:
b | new | undo
This commands selects or de-selects all elements in the range. Selected objects can be specified in a range filter by using the selected keyword. Objects that are not
new
undo
this will reverse the operation of the last structure cable select command. FLAC3D keeps a maximum undo stack of size 12.
FISH Functions
FISH functions operating on extrusion cables. The type specifiers used in the FISH function signatures are given in the FISH Type Index section.
Structural Cable Functions
struct.cable.area(STRUCT_CABLE_PNT)
Get/set the cross-section area of the cable element.
struct.cable.force.axial(STRUCT_CABLE_PNT)
Get the average axial force of the element (positive: tension;...
struct.cable.force.nodal(STRUCT_CABLE_PNT,INT<,INT>)
Get the generalized nodal force acting at end iend .
struct.cable.grout.cohesion(STRUCT_CABLE_PNT)
Get/set the grout cohesion.
struct.cable.grout.confining(STRUCT_CABLE_PNT,INT)
Get the confining stress acting on the grout at end...
struct.cable.grout.dir(STRUCT_CABLE_PNT,INT<,INT>)
Get the direction vector in which cableSEL is being loaded...
struct.cable.grout.disp(STRUCT_CABLE_PNT,INT)
Get displacement in grout (shear coupling spring) at end iend ...
struct.cable.grout.friction(STRUCT_CABLE_PNT)
Get/set the grout internal friction angle.
struct.cable.grout.perimeter(STRUCT_CABLE_PNT)
Get/set the grout exposed perimeter.
struct.cable.grout.slip(STRUCT_CABLE_PNT,INT)
Get the slip state of grout (shear coupling spring) at...
struct.cable.grout.stiffness(STRUCT_CABLE_PNT)
Get/set the grout stiffness.
struct.cable.grout.stress(STRUCT_CABLE_PNT,INT)
Get stress in grout (shear coupling spring) at end iend ...
struct.cable.length(STRUCT_CABLE_PNT)
Get the length of the cable element.
struct.cable.slide(STRUCT_CABLE_PNT)
Get the boolean flag of the large-strain sliding.
struct.cable.slide.tol(STRUCT_CABLE_PNT)
Get/set the large-strain sliding tolerance of the cable element.
struct.cable.state.compression(STRUCT_CABLE_PNT)
Get the compression yield state of the cable element.
struct.cable.state.tension(STRUCT_CABLE_PNT)
Get the tension yield state of cable element.
struct.cable.stress.axial(STRUCT_CABLE_PNT)
Get the average axial stress of the cable element (positive:...
struct.cable.volume(STRUCT_CABLE_PNT)
Get the cable element volume, or the cross-sectional area times...
struct.cable.yield.compression(STRUCT_CABLE_PNT)
Get/set the compression yield strength of the cable element.
struct.cable.yield.tension(STRUCT_CABLE_PNT)
Get/set the tension yield strength of the cable element.
struct.cable.young(STRUCT_CABLE_PNT)
Get/set the Young's modulus of the cable element.
l struct.cable.area
l struct.cable.force.axial
l struct.cable.force.nodal
l struct.cable.grout.cohesion
l struct.cable.grout.confining
l struct.cable.grout.dir
l struct.cable.grout.disp
l struct.cable.grout.friction
l struct.cable.grout.perimeter
l struct.cable.grout.slip
l struct.cable.grout.stiffness
l struct.cable.grout.stress
l struct.cable.length
l struct.cable.slide
l struct.cable.slide.tol
l struct.cable.state.compression
l struct.cable.state.tension
l struct.cable.stress.axial
l struct.cable.volume
l struct.cable.yield.compression
l struct.cable.yield.tension
l struct.cable.young
struct.cable.area
Syntax
f = struct.cable.area(p)
struct.cable.area(p) = f

Arguments: p - a pointer to a cable element
struct.cable.force.axial
Syntax
f = struct.cable.force.axial(p)
Get the average axial force of the element (positive: tension; negative: compression).
Returns: f - the average axial force of the element

Accepts: f - the average axial force of the element
struct.cable.force.nodal
Syntax
m = struct.cable.force.nodal(p,iend<,idof>)
Get the generalized nodal force acting at end iend.
If the optional argument idof is provided, returns the force in that specific degree-of-freedom (from 1 to 6).
Returns: m - a 1x6 matrix with the generalized nodal force at end iend, or the value of specific degree-of-freedom idof
iend - indicates which end of the cable, either 1 or 2
struct.cable.grout.cohesion
Syntax
f = struct.cable.grout.cohesion(p)
struct.cable.grout.cohesion(p) = f
Returns: f - grout cohesion

Accepts: f - grout cohesion
Arguments: p - pointer to a cable element
struct.cable.grout.confining
Syntax
f = struct.cable.grout.confining(p,iend)
Get the confining stress acting on the grout at end iend ∈ {1, 2}. Negative value indicates compression. The stress acts in a plane perpendicular to the cable axis;
effective confining stress is the average of the principal values in this plane.
Returns: f - stress in grout

iend - end number of the element, iend ∈ {1, 2}.
struct.cable.grout.dir
Syntax
Vector Access
v = struct.cable.grout.dir(p,iend<,i>)
Get the direction vector in which cableSEL is being loaded by the coupling spring at end iend ∈ {1, 2}.
Returns: v - displacement vector or component

iend - end number of the element, iend ∈ {1, 2}
Component Access
f = struct.cable.grout.dir.x(p,iend)
Get the x-component displacement vector.
Returns: f - x-component displacement vector

f = struct.cable.grout.dir.y(p,iend)
Get the y-component displacement vector.
Returns: f - y-component displacement vector
f = struct.cable.grout.dir.z(p,iend)
Get the z-component displacement vector.
Returns: f - z-component displacement vector

struct.cable.grout.disp
Syntax
f = struct.cable.grout.disp(p,iend)
Get displacement in grout (shear coupling spring) at end iend ∈ {1, 2}; positive/negative with respect to the average axial direction of cable.
Returns: f - displacement in grout

struct.cable.grout.friction
Syntax
f = struct.cable.grout.friction(p)
struct.cable.grout.friction(p) = f
Returns: f - grout internal friction angle

Accepts: f - grout internal friction angle
struct.cable.grout.perimeter
Syntax
f = struct.cable.grout.perimeter(p)
struct.cable.grout.perimeter(p) = f
Returns: f - grout exposed perimeter

Accepts: f - grout exposed perimeter
struct.cable.grout.slip
Syntax
i = struct.cable.grout.slip(p,iend)
Get the slip state of grout (shear coupling spring) at end iend ∈ {1, 2}. Return value {0, 1, 2} denotes never slipped, now slipping, or slipped in the past, respectively.
Returns: i - slip state of grout, i ∈ {0, 1, 2} denotes never slipped, now slipping, or slipped in the past, respectively
struct.cable.grout.stiffness
Syntax
f = struct.cable.grout.stiffness(p)
struct.cable.grout.stiffness(p) = f
Returns: f - grout stiffness

Accepts: f - grout stiffness
struct.cable.grout.stress
Syntax
f = struct.cable.grout.stress(p,iend)
Get stress in grout (shear coupling spring) at end iend ∈ {1, 2}; positive/negative with respect to average axial direction of cable.
Returns: f - stress in grout

struct.cable.length
Syntax
f = struct.cable.length(p)
Returns: f - the length of the cable element

struct.cable.slide
Syntax
b = struct.cable.slide(p)
Get the boolean flag of the large-strain sliding. If true, slide is on; if false, slide is off.
Returns: b - a boolean flag. If true, slide is on; if false, slide is off.

struct.cable.slide.tol
Syntax
f = struct.cable.slide.tol(p)
struct.cable.slide.tol(p) = f
Returns: f - large-strain sliding tolerance of the element

Accepts: f - large-strain sliding tolerance of the element
struct.cable.state.compression
Syntax
i = struct.cable.state.compression(p)
Get the compression yield state of the cable element. The return value {0, 1, 2} denotes never yielded, now yielding, or yielded in the past, respectively.
Returns: f - an integer in the set of {0, 1, 2} denotes never yielded, now yielding, or yielded in the past, respectively
struct.cable.state.tension
Syntax
i = struct.cable.state.tension(p)
Get the tension yield state of cable element. The return value {0, 1, 2} denotes never yielded, now yielding, or yielded in the past, respectively.
Returns: i - an integer in the set of {0, 1, 2} denotes never yielded, now yielding, or yielded in the past, respectively
struct.cable.stress.axial
Syntax
f = struct.cable.stress.axial(p)
Get the average axial stress of the cable element (positive: tension; negative: compression).
Returns: f - the average axial stress of the element

Accepts: f - the average axial stress of the element
struct.cable.volume
Syntax
f = struct.cable.volume(p)
Get the cable element volume, or the cross-sectional area times the length.
Returns: f - the element volume of the element

Accepts: f - the element volume of the element
struct.cable.yield.compression
Syntax
f = struct.cable.yield.compression(p)
struct.cable.yield.compression(p) = f
Returns: f - compression yield strength of the cable element

struct.cable.yield.tension
Syntax
f = struct.cable.yield.tension(p)
struct.cable.yield.tension(p) = f
Returns: f - tension yield strength of the cable element

struct.cable.young
Syntax
f = struct.cable.young(p)
struct.cable.young(p) = f
Returns: f - the Young's modulus of the element

Accepts: f - the Young's modulus of the element
Pile Structural Elements

Mechanical Behavior
Each pile structural element is defined by its geometric, material and coupling-spring properties. A pile element is assumed to be a straight segment of uniform, bisymmetrical
cross-sectional properties lying between two nodal points. An arbitrarily curved structural pile can be modeled as a curvilinear structure composed of a collection of pile
element. The stiffness matrix of a pile element is identical to that of a beam element; however, in addition to providing the structural behavior of a beam (including the ability
to specify a limiting plastic moment), both a normal-directed (perpendicular to the pile axis) and a shear-directed (parallel with the pile axis) frictional interaction occurs
between the pile and the grid. In this sense, piles offer the combined features of beams and cables. In addition to skin-friction effects, end-bearing effects can also be modeled
(see Axially Loaded Pile). Pile elements are suitable for modeling structural-support members, such as foundation piles, for which both normal- and shear-directed frictional
interaction with the rock or soil mass occurs.
A special material model is also available as an extension to the pile element, to simulate the behavior of rockbolt reinforcement. The model is activated by specifying
structure pile property rockbolt-flag on, and includes the ability to account for changes in confining stress around the reinforcement, strain-softening behavior of the
material between the pile and the grid, and tensile rupture of the pile.
Each pile element has its own local coordinate system, shown in Figure 1. This system is used to specify both the cross-sectional moments of inertia and applied distributed
loading, and to define the sign convention for force and moment distributions across pile elements that make up a single pile (see Figure 5). The pile element coordinate
system is defined by the locations of its two nodal points, labeled 1 and 2 in Figure 1, and by the vector . The element coordinate system is defined such that

x
y \
3. the -axis is aligned with the projection of b onto the cross-sectional plane (i.e., the plane whose normal is directed along the -axis).
system2.png
Figure 1: Pile element coordinate system and 12 active degrees-of-freedom of the beam finite element used by each element
The pile element coordinate system can be modified with the structure pile property direction-y command. (If is not specified, or is parallel with the local
y x
-axis, then defaults to the global - or -direction — whichever is not parallel with the local -axis.) The element coordinate system can be
viewed with the Pile plot item, and printed with the structure pile list system-local command. The nodal connectivity can be printed with the structure pile list
information command.
The orientation of the node-local system for all nodes used by pile elements is set automatically at the start of a set of cycles (or when the model cycle 0 command is
y
executed), such that the -axis is aligned with the average axial direction of all pil elements using the node, and the -axes are arbitrarily oriented in the pile cross-
sectional plane.
Piles support large-strain sliding (by setting the slide property to on), whereby the interpolation locations (used by the pile nodes to transfer forces and velocities to and from
the zones — see Structural-Element Links) will migrate through the grid when running in large-strain mode. This allows one to calculate the large-strain, post-failure behavior
of a pile, whereby substantial sliding between the pile nodes and the zones occurs. If a pile node moves out of all zones, then a connection with the zones will not be
reestablished if the node is later moved back into zones; however, the connection remains intact as the pile nodes slide between zones.
Piles interact with the grid via shear and normal coupling springs. The coupling springs are nonlinear, spring-slider connectors that transfer forces and motion between the pile
and the grid at the pile nodes (by way of the link emanating from each pile node). The behavior of the shear coupling springs is identical to the shear behavior of a grouted
cable, as described in Shear Behavior of Grout Annulus. The behavior of the normal coupling springs includes the ability to model load reversal and the formation of a gap
between the pile and the grid. The normal coupling springs can simulate the effect of the host medium squeezing around the pile. The formulations for the shear and normal
coupling springs and the rockbolt logic are presented in the following three subsections. The behavior is described in terms of the pile element properties listed in Pile
Properties (refer to this list for a summary of relevant notations).
Behavior of Shear Coupling Springs
The shear behavior of the pile-grid interface is cohesive and frictional in nature. It is modeled in the same way as the grouted-cable system (described in Shear Behavior of
Grout Annulus), in which the grout properties are replaced by the corresponding shear coupling spring properties of (1) stiffness, , (2) cohesive strength, , (3)
\
friction angle, , and (4) exposed perimeter, . The mechanical behavior of the pile in the shear direction is depicted in terms of these parameters, as well as the
\sig
effective confining stress, (also defined in Shear Behavior of Grout Annulus), in Figure 2. Note that the shear coupling spring properties associated with each pile
element are averaged at pile nodes.
../../../../../../_images/shear-material-
behavior.png
Figure 2: Shear-directional material behavior for pile elements.
Behavior of Normal Coupling Springs
The normal behavior of the pile-grid interface is cohesive and frictional in nature. It is modeled in a fashion similar to the grouted-cable system, and is represented
numerically as a spring-slider system located at the nodal points along the pile axis, as shown in Shear Behavior of Grout Annulus. The normal behavior of the pile-grid
interface, during relative normal displacement, , between the pile and the host medium (as shown in Figure 3) is described numerically by the normal coupling spring
k \ p g
properties of (1) stiffness, , (2) cohesive strength, , (3) friction angle, , (4) exposed perimeter, , and (5) gap-use flag, . The mechanical
\sig
behavior of the pile in the normal direction is depicted in terms of these parameters, as well as the effective confining stress, ma_ (defined in Shear Behavior of Grout
Annulus), in Figure 4. Note that the normal coupling spring properties associated with each pile element are averaged at pile nodes.
../../../../../../_images/normal-behavior-
idealization.png
Figure 3: Idealization of normal-directional behavior of pile elements.
../../../../../../_images/normal-material-
behavior.png
Figure 4: Normal-directional material behavior for pile elements.
When a pile is loaded laterally, a gap may open between the pile and the host medium. If the load is reversed, the pile first must traverse this gap before it can load the host
medium on the opposite side. The effect of a gap is considered by setting the gap-use flag to on. In the current implementation of gap behavior, two gap values are stored for
each of the two normal directions of the link emanating from each pile node. The two gap values record positive and negative relative displacements along their corresponding
y
direction. Thus, the "gap" appears as a parallelogram with its sides oriented parallel with the -axes of Figure 3. Initially, each pile node has no gap, and the gap grows
independently in the two normal directions during relative normal displacements occurring while the maximum normal force is acting. The gap does not close, it only
expands. The size of the gap can be accessed via FISH and printed with the structure pile list coupling-yield command.
Rockbolt Behavior
An extension of the pile element logic is available to simulate the behavior of rockbolt reinforcement. The behavior of these elements is similar to the behavior of cable
elements, except that they also include bending resistance. By invoking the structure pile property rockbolt-flag on command, the following additional behavior is
included in the element.
1. The pile element itself may yield in the axial direction. The yield strength is specified by the property (tensile-yield).
2. Rockbolt breakage is simulated based upon a user-defined tensile failure strain (tfstrain). A strain measure, based on adding the axial and bending plastic
\varepsilon^
strains, is evaluated at each pile node. The axial plastic strain, {ax}_{pl}
, is accumulated based on the average strain of pile elements using the
\varepsilo
node. The bending plastic strain is averaged over the element and then accumulated. The total plastic tensile strain, n_{pl} , is then calculated by
\varepsilon_{pl} = \Sigma \varepsilon^{ax}_{pl} + \Sigma {d \over 2} {\theta_{pl}

\over L}
where:
= rockbolt diameter;
= element length; and

\
t = average angular rotation over the element
If this strain exceeds the limit, tensile-failure-strain, the forces and moment in this element are set to zero, and the element is assumed to have failed.
3. The effective confining stress acting on the pile element is based on the change in stress since installation. Stresses in the grid around the element are stored
when the element is installed and, as calculation progresses, the effective confining stress around the element is calculated as the change in stress from the
installation state. (For the default pile element, the effective confining stress is based on the current stress state in the zones surrounding the pile.)
4. A user-defined table (coupling-friction-table) can be specified to give a correction factor for the effective confining stress, in cases of non-isotropic stress,
as a function of a deviatoric stress ratio. By default, the confining stress acting on piles is given by the confining stress relation. By specifying a table with
\sig
coupling-friction-table and setting the coupling-confining-flag flag, factors are applied to the value of to account for non-isotropic stresses.
5. Softening as a function of shear displacement for the shear coupling-spring cohesion and friction angle properties can be prescribed via the user-defined
tables coupling-cohesion-table and coupling-friction-table.
Response Quantities
Pile responses include force and moment acting on the pile itself, and stress, displacement and yield state in both the normal and shear coupling springs. Additional coupling-
spring information includes the current loading direction, the confining stress and the gap being tracked by the normal springs. The pile responses can be accessed via FISH,
and
1. printed with the structure pile list command,

2. monitored with the structure pile history command, and
3. plotted with the Pile plot item.
The sign convention in Figure 5 provides a continuous description of force and moment distributions across elements that make up a single pile. It assumes that the set of
elements making up the pile are oriented consistently, such that their local coordinate systems form a continuous description of the pile orientation. Such will be the case if the
pile is created using the structure pile create command. The nodes of each element so created will be ordered such that the overall pile direction goes from the the first
point tot he second point. The nodal connectivity can be printed with the structure pile list information command.
../../../../../../_images/sign-
convention1.png
Figure 5: Sign convention for forces and moments at the ends of a pile element (Axes show element coordinate system, ends 1 and 2 correspond with order in nodal
connectivity list, and all quantities are drawn acting in their positive sense.)
Properties
Each pile element possesses 20 properties (an additional 7 properties control the rockbolt logic and are listed in Rockbolt Properties):
\
E
2. youngs, Young's modulus, [F/L2]
\
3. poisson, Poisson's ratio,
\
4. plastic-moment, plastic moment capacity, (optional — if not specified, is assumed to be infinite) [F L]
\al
5. thermal-expansion, thermal-expansion coefficient, ph [1/T]
A
6. cross-sectional-area, cross-sectional area, [L2]
y
7. direction-y, vector whose projection onto the pile element cross-section defines the element -axis (optional — if not specified,
y x
defaults to the global - or -direction, whichever is not parallel with the element -axis)
y
8. moi-y, second moment with respect to element -axis, [L4]
9. moi-z, second moment with respect to element -axis, [L4]
J
10. moi-polar, polar moment of inertia, [L4]
11. perimeter, exposed perimeter, [L]
c
12. coupling-cohesion-normal, normal coupling spring cohesion per unit length, [F/L]
\
13. coupling-friction-normal, normal coupling spring friction angle, [degrees]
14. coupling-gap-normal, normal coupling spring gap-use flag, (default: off)
15. coupling-stiffness-normal, normal coupling spring stiffness per unit length, [F/L2]
c
16. coupling-cohesion-shear, shear coupling spring cohesion per unit length, [F/L]
\
17. coupling-friction-shear, shear coupling spring friction angle, [degrees]
k
18. coupling-stiffness-shear, shear coupling spring stiffness per unit length, [F/L2]
The material behavior is described by properties 1-6, the cross-sectional geometry is described by properties 7-10, and the coupling behavior is described by properties 11-20.
For a general cross-section, shown in Beam Cross Section, the polar moment of inertia, , and second moments, and , are defined in the element
x y
coordinate system by these integrals, in which the two principal axes of the cross section are defined by the element - and -axes.
Pile element properties are determined in a fashion similar to that used for beam elements.
The exposed perimeter of a pile element and the properties of the coupling springs should be chosen to represent the behavior of the pile/medium interface commensurate with
the problem being analyzed. For piles in soil, the pile/soil interaction can be expressed in terms of a shear response along the length of the pile shaft as a result of axial loading
(e.g., a friction pile), or in terms of a normal response when the direction of loading is perpendicular to the pile axis (e.g., piles used to stabilize a slope).
Pile/soil interaction will depend on whether the pile was driven or cast-in-place. The interaction is expressed in terms of the shear resistance that can develop along the length
of the pile. For example, driven friction piles receive most of their support by friction or adhesion from the soil along the pile shaft. A cast-in-place end-bearing pile, on the
other hand, receives the majority of its support from soil near the tip of the pile.
In many cases, properties needed to describe the site-specific response of the pile/soil interaction will not be available. However, a reasonable understanding of the soil
properties at the site is usually provided from standard in-situ and laboratory tests. In such cases, the pile/soil shear response can be estimated from the soil properties. If the
failure associated with the pile/soil response is assumed to occur in the soil, then the lower limits for coupling-friction-shear and coupling-cohesion-shear can be related to the
angle of internal friction of the soil (for coupling-friction-shear) and the soil cohesion times the perimeter of the pile (for coupling-cohesion-shear). If failure is assumed to
occur at the pile/soil interface, the values for coupling-friction-shear and coupling-cohesion-shear may be reduced to reflect the smoothness of the pile surface.
Rockbolt Properties
If the rockbolt logic is active (structure pile property rockbolt-flag on), then 7 properties can also be assigned (in addition to those listed in Pile Properties):
21. coupling-confining-flag flag to activate incremental confining stress logic (default: off)
22. coupling-confining-table name of the table relating effective confining stress factor to deviatoric stress
23. coupling-cohesion-table name of the table relating cohesion of shear coupling spring to relative shear displacement
24. coupling-friction-table name of the table relating friction angle of shear coupling spring to relative shear displacement
25. rockbolt-flag flag to activate rockbolt logic (default: off)
26. tensile-failure-strain tensile failure strain (nondimensional)
27. tensile-yield axial tensile yield strength (force units), [F]
Examples that illustrate the effect of these properties are given in Simulation of Pull-Tests for Fully Bonded Rock Reinforcement.
Simple examples are given to illustrate the use of piles.
l Axially Loaded Pile

l Laterally Loaded Pile
A complete list of examples that use pile elements is available in Structural Pile Examples.
Commands & FISH

l Commands
l FISH Functions
Axially Loaded Pile

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ‣ Examples.... Choose "Structure/Pile/AxiallyLoaded" and select "AxiallyLoaded.f3prj" to load. The main data
Piles transfer axial loads to the ground via two mechanisms: skin friction along the shaft and end-bearing. The pile logic directly includes skin-friction effects, and end-
bearing effects can be included by making a small modification to the linkage at the bottom pile node. Both effects are examined in this example.
Skin Friction — The ultimate bearing capacity of a single pile of length in a cohesionless soil is a function of the shaft resistance due to skin friction, as given by
(Cernica 1995)
Q_s = \sum_i L_i (a_s)_i

(1) (s_s)_i
where:
= increment of pile length;
(a \D
= area of pile surface in length elt in contact with soil; and
(s = unit shaft resistance.
For uniform soil conditions and constant pile cross-section, and are constant and
Q_s = L
(2)
s
In free-draining cohesionless soil, the value for is assumed to equal
s_s = K_s \sigma_{avg} \tan

(3) \phi_s
where: = average coefficient of earth pressure on the pile shaft;
\sigma_ = average effective overburden pressure along the pile shaft; and
{avg}
\ = angle of skin friction.
End Bearing — The ultimate bearing capacity due to end-bearing resistance of a single pile is typically calculated based on the principles of bearing capacity for shallow
N_
foundations using the bearing capacity factors , , and {\gamm . For a single pile in a cohesionless soil, the end-bearing capacity, , is given by
(Cernica 1995)
Q_p = A_p \gamma L

(4) N_q
where: A = area of pile tip;
\ga = unit weight of soil;
\bigl ( {{1 + \sin \phi} \over {1 - \sin \phi}}

= \bigr )^2
; and
\ = the friction angle of the soil.
The total pile capacity for a single pile in a cohesionless soil is then
Q = Q_s + Q_p = L a_s K_s \sigma_{avg} \tan \phi_s + A_p \gamma L \bigl ( {{1 + \sin \phi} \over {1 - \sin \phi}}
(5) \bigr )^2
In this example, a single pile in a cohesionless soil is axially loaded by applying a constant vertical velocity to the top of the pile. The axial force in the top pile element is
monitored to determine the limiting load (i.e., the ultimate bearing capacity). The pile length within the soil is 7 m, and the pile diameter is 1 m. The soil has a friction angle of
10°, and the skin friction between the pile shaft and soil is also assumed to be 10°. The unit weight of the soil is 20,000 N/m3, and the stress state is assumed to be isotropic (
= 1). The average effective overburden pressure along the pile shaft is calculated at the mid-depth of the pile to be 70,000 Pa, assuming that the strength varies
linearly.
Q
If only skin friction along the shaft is considered, using equations (2) and (3), the ultimate bearing capacity for the pile is = 271 kN. If the end-bearing capacity is
included, using equation (5), the total bearing capacity = 493 kN.
In the FLAC3D data file, the analysis is first conducted by only accounting for the shaft resistance. coupling-friction-shear is set to 10°, and the other coupling spring strength
parameters are set to zero. The history of the axial force in the top pile element is plotted versus vertical displacement of the top node in Figure 1. The limiting load is equal to
280 kN.
This figure also contains a plot of the coupling-spring shear-stress distribution along the pile and shows the linear increase in shear stress with depth. Note that combined
damping (structure damping combined-local), rather than local damping, is used for this analysis because there is significant uniform motion in one direction as a result
of the downward loading on the pile (see Mechanical Damping).
The link at the bottom node provides the pile-grid interaction described in Pile Structural Elements. This interaction does not include end-bearing effects. To include end-
bearing effects, we must delete this link, replace it with a new link containing a normal-yield spring in the axial direction, and specify appropriate spring properties. We
include end-bearing effects by including commands after creating the pile:
struct link delete range position-z 4.0

struct link create target zone group 'End' range position-z 4.0
struct link attach x=normal-yield y=free z=free range group 'End'
struct link attach rotation-x=free rotation-y=free rotation-z=free range group 'End'
struct link property x area=1.0 stiffness=5.4e11 yield-compression=2.22e5 range group 'End'
The first two commands delete the existing link and replace it with a new link that is given a group name of End. All link properties are specified with respect to the node-
x
local system of the source node. Because the source node is used by a pile element, its node-local system will be oriented such that the -direction is aligned with the pile
axis. Note that this orientation is set automatically at the start of a set of cycles, or when the model cycle 0 command is executed.
x
The next three commands set attachment conditions for all link directions to be free, except for the -direction, in which a normal-yield spring is inserted. The final
command sets the properties of this spring as follows. The spring stiffness, , should be at least as large as the axially directed stiffness of the bottom node in the original
system (before its link has been deleted). The command structure node list stiffness shows this value to be 5.4 × 1011 N/m. Thus, we set the spring area equal to 1.0
m2, and the spring stiffness equal to 5.4 × 1011 N/m3. We set the compressive yield strength of the spring equal to the bearing capacity at 7 m depth, as given by equation (4),
to equal 222 kN.
The results are shown in Figure 2. The limiting load equals 490 kN when end-bearing resistance is included. Both FLAC3D results (for skin friction alone, and for skin
friction plus end bearing) compare well with the solutions given in equations (2) and (5).
../../../../../_images/axiallyloaded-pile1.png
Figure 1: Friction pile: Top force-displacement history and shear stress along shaft.
../../../../../_images/axiallyloaded-pile2.png
Figure 2: Friction and end-bearing pile: Top force-displacement history and shear stress along shaft.
References
Cernica, J. N. Geotechnical Engineering: Foundation Design, New York: John Wiley & Sons Inc. (1995).
Data File
AxiallyLoaded.f3dat
; Axially loaded pile example application

model new
model title "Axially Loaded Pile"
; Create the grid
zone create brick size 15 15 15 edge=11
; Assign constitutive model and propertie
zone property bulk=5e9 shear=1e9 density=2000
model gravity 10
zone initialize-stresses
model solve ratio-local 1e-4 ; Should be instant
; =======================================================
; Create a pile in the center of the soil block
struct pile create by-line (5.5, 5.5, 12) (5.5, 5.5, 4) segments=32
struct pile property young=8.0e10 poisson=0.30 cross-sectional-area=0.7854 moi-polar=0.0 moi-y=0.0 moi-z=0.0 ...
perimeter=3.14 coupling-stiffness-shear=1.3e11 coupling-cohesion-shear=0.0 coupling-friction-shear=10.0 ...
coupling-stiffness-normal=1.3e11 coupling-cohesion-normal=0.0 coupling-friction-normal=0.0 coupling-gap-normal=off
; =======================================================
; Specify and apply velocity to pile tip.
struct node fix velocity-x range position-z 12
struct node initialize velocity-x 0.5e-8 local range position-z 12
; =======================================================
; Set up histories for monitoring model behavior
struct node history name='disp' displacement-z position (5.5,5.5,12)
struct pile history name='force' force-x position (5.5,5.5,12)
; =======================================================
model save 'Initial'
; =======================================================
; Apply velocity to achieve total displacement of 10e-5 m
model cycle 20000
model save 'AxiallyLoaded-1'
; =======================================================
; Include end-bearing effect
model restore 'Initial'
struct link delete range position-z 4.0
struct link create target zone group 'End' range position-z 4.0
struct link attach x=normal-yield y=free z=free range group 'End'
struct link attach rotation-x=free rotation-y=free rotation-z=free range group 'End'
struct link property x area=1.0 stiffness=5.4e11 yield-compression=2.22e5 range group 'End'
model cycle 20000
model save 'AxiallyLoaded-2'
Laterally Loaded Pile

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ? Examples.... Choose "Structure/Pile/LaterallylLoaded" and select "LaterallyLoaded.f3prj" to load. The main
A vertical pile is subjected to a lateral displacement at its top. The pile is pushed in one direction, then the loading is reversed and the pile is pushed in the opposite direction.
This loading cycle is performed for the case of no normal gap present, and then for 100% of the gap effective. The results demonstrate the response of the pile structural
elements to lateral loading both with and without the effect of a gap between the pile and the medium. The top node of the pile is marked with the group name Top.
In the FLAC3D data file, the pile (composed of 8 pile elements) is created in the center of the soil block such that the top pile node is one meter above the soil surface (see
Figure 1). We wish to apply to the top node a constant lateral velocity of 1 × 10-8 that will move the node along the diagonal of the soil block. This direction is described by a
vector of (1,1,0) in the global system. We specify this nodal velocity condition with the structure node initialize velocity (0.707e-8,0.707e-8,0) range group 'Top'
command.
We must also specify the appropriate velocity-fixity condition at this node with the structure node fix command, which requires specification of fixity directions in the
node-local system, not the global system. Because the top node is used by a pile element, its node-local system will be oriented such that the x-axis is aligned with the pile
axis, and the yz-axes lie in the pile cross-sectional plane. In our model, the node-local system of the top node is oriented such that the x-axis points in the negative global z-
direction, the y-axis points in the positive global y-direction, and the z-axis points in the positive global x-direction. The orientation of the node-local system can be visualized
with the "Pile" plot item by setting the "System" attribute to "Node".
Note that this orientation is set automatically at the start of a set of cycles, or when the model cycle 0 command is executed. Therefore, we fix the lateral velocity to remain
constant with the commands
struct node fix velocity-y range group 'Top' ; fix velocities in lateral plane, top node
struct node fix velocity-z range group 'Top'
We wish to monitor the applied load acting at the top node and plot this value versus the displacement of the top node. If the loading is applied in a quasi-static fashion, then
the applied load acting at the top node will equal the shear force acting at the top end of the top pile element. The shear forces are expressed in the pile element coordinate
system (see Pile Sign Conventions). In order to obtain the shear force acting in the diagonal direction in which the load is being applied, we must rotate the y-axis of the pile
element system such that it lies along this diagonal using the direction-y property.
The applied lateral load can then be monitored with the structure pile history command:
struct pile history name='force' force-y position (5.5,5.5,12) ; shear force at top
../../../../../_images/laterallyloaded-geom.png
Figure 1: Soil block and vertical pile.
The x- and y-components of the applied displacement can be monitored with separate structure node history commands; however, we wish to monitor the lateral
displacement occurring along the diagonal. To do this, we use the FISH function lateralDisp, which accesses the x- and y-components of the displacement using the
struct.node.disp.global function.
For this problem, the cohesion and friction of the normal coupling spring are set to 0.01 MN/m and zero, respectively. The no-gap case is run by specifying coupling-gap-
normal off in the structure pile property command. The full-gap case is run by specifying coupling-gap-normal on. Figure 2 shows the normal load at the pile top versus
displacement for the no-gap case, and Figure 3 shows the results for the full-gap case. During the lateral loading, the limiting normal force is the same for both cases.
However, the normal load versus displacement histories are different. In the model with a full gap, it is necessary to close the gap before the force with opposite direction is
generated. The pile is unloaded when it returns to its initial position.
../../../../../_images/laterallyloaded-nogap-chart.png
Figure 2: Shear load at top of pile versus lateral displacement for no gap.
../../../../../_images/laterallyloaded-fullgap-chart.png
Figure 3: Shear load at top of pile versus lateral displacement for full gap.
Additional information about the system behavior can be learned by studying the model at the end of the first stage of loading, when the initial applied displacement is 0.4
mm. At this stage, the upper portion of the pile is compressing the soil in the (1,1,0) direction, while the lower portion of the pile is compressing the soil in the minus (1,1,0)
direction. The plots of nodal displacement, bending moment in the pile, and stress and yield state of the normal coupling springs (see Figure 4 and Figure 5) confirm this
loading mode and indicate that the normal coupling springs above and below the load-reversal point are yielding. The normal stress is zero over the top element, because the
c
top node is above the soil surface. From Figure 4 it can be seen that the normal stress at the yielding nodes equals 3.185 kPa. This equals normal cohesion, , divided
p
by perimeter, , as it should. The pile responses can also be accessed via FISH.
../../../../../_images/laterallyloaded-stress.png
Figure 4: Stress and yield state of normal coupling springs (undeformed and deformed by 5000 magnification, end of first loading stage, gap on).
../../../../../_images/laterallyloaded-moment.png
Figure 5: Moment distribution (undeformed and deformed by 5000 magnification, end of first loading stage, gap on).
Data File
LaterallyLoaded.f3dat
model new
model title "Laterally loaded pile"
; Create zones
zone create brick size 8 8 8 edge=11
zone prop bulk=5e9 shear=1e9 density=2000
model gravity 10
model solve ratio-local 1e-4 ; Should be instant
; =======================================================
; Create a pile in the center of the soil block
struct pile create by-line (5.5,5.5,12.0) (5.5,5.5,4.0) segments=8
struct node group 'Top' range position-z 12 ; Tag top node
struct pile property young=8.0e10 poisson=0.30 cross-sectional-area=0.7854 ...
moi-polar=9.82e-2 moi-y=4.91e-2 moi-z=4.91e-2 ...
perimeter=3.14 ...
coupling-stiffness-shear=1.3e11 coupling-cohesion-shear=1.0e10 coupling-friction-shear=0.0 ...
coupling-stiffness-normal=1.3e09 coupling-cohesion-normal=1.0e04 coupling-friction-normal=0.0 ...
coupling-gap-normal=off ...
direction-y=(1,1,0) ; so that shear force Fy corresponds with diagonal direction
; =======================================================
; Fish function to find lateral displacement of top node
fish define lateralDisp
global topNode
if type.name(topNode) == 'integer' then
topNode = struct.node.near(5.5,5.5,12)
endif
local disp = struct.node.disp.global(topNode)
lateralDisp = math.sqrt(disp(1)^2 + disp(2)^2) * math.sgn(disp(1))
end
; =======================================================
struct pile history name='force' force-y position (5.5,5.5,12) ; shear force at top
fish history name='disp' @lateralDisp ; lateral displacement
; =======================================================
struct node fix velocity-y range group 'Top' ; fix velocities in lateral plane, top node
struct node fix velocity-z range group 'Top'
; move (+) diag-dir
struct node initialize velocity (0,0.707e-8,0.707e-8) local range group 'Top'
; =======================================================
; Run no-gap case
; =======================================================
model cycle 40000 ; disp of +4e-4
model save 'NoGap-1'
; move (-) diag-dir
struct node initialize velocity (0,-0.707e-8,-0.707e-8) local range group 'Top'
model cycle 80000 ; disp of -8e-4
model save 'NoGap-2'
; move (+) diag-dir
struct node initialize velocity (0,0.707e-8,.707e-8) local range group 'Top'
model save 'NoGap-Final'
; =======================================================
; Run full-gap case
; =======================================================
struct pile property coupling-gap-normal on
model save 'FullGap-1'
; move (-) diag-dir
struct node initialize velocity (0,-0.707e-8,-0.707e-8) local range group 'Top'
model cycle 80000 ; disp of -8e-4
model save 'FullGap-2'
; move (+) diag-dir
struct node initialize velocity (0,0.707e-8,.707e-8) local range group 'Top'
model save 'FullGap-Final'
Commands
Operations on structural element piles.
Pile elements use the same internal formulation and beam elements, but connected to their surroundings by deformable links in all directions. The directions perpendicular to
the element direction can support the creation of a gap that results from pile movement, for example.
Structural Element Pile Commands
structure pile apply

structure pile create
Create a pile represented by one or more elements.
structure pile delete
Delete all pile elements in the range.
structure pile group
Assign all pile elements in the range to the group...
structure pile hide
This commands hides or un-hides all pile elements in the...
structure pile history
Sample pile responses.
structure pile import
Create pile elements from an outside source.
structure pile initialize
structure pile list
List information about piles.
structure pile property
Assign the specified property to all elements in the range.
structure pile refine
this command refines an existing element in the range by...
structure pile select
l structure pile apply command

l structure pile create command
l structure pile delete command

l structure pile group command
l structure pile hide command
l structure pile history command
l structure pile import command
l structure pile initialize command
l structure pile list command
l structure pile property command
l structure pile refine command
l structure pile select command
structure pile apply command

Syntax
structure pile apply f1 f2 <range>
Assign uniform applied distributed loads. Loads (force per unit length) are applied to all elements in the range. Positive loads act in the positive y- or z-directions (f1
and f2, respectively) of the element system and maintain this orientation during large-strain motion. Point loads are applied at the nodes using the command structure
node apply.
structure pile create command

Syntax
structure pile create keyword
Primary keywords:
(by-line); by specifying an element to be created from an existing pair of nodes (by-nodeids); or by specifying an initial point and a direction to follow (by-
ray).
Create one element that lies along a straight line between the locations v1 and v2. New nodes associated with the element will also be created (see the id
Specify the ID numbers (i1, i2) of two nodes that will define the element. These nodes must already exist—nodes can be created with the structure node
create command. Ordering of the nodes defines the pile element coordinate system as follows. The positive x-direction lies along the line from i1 to i2, and the
The new element will not be attached to the grid; if you wish to attach it to the grid, then after creating it, position its nodes with the structure node
Create one element that lies along a straight line starting at v1, proceeding in the direction specified by v2 for a distance given by f. New nodes associated with
Keyword Block
The following keywords may be optionally provided on element creation, using any of the major keywords: by-line, by-nodeids and by-ray.
distinct
group s <slot s >
Assign all newly created elements to the group s. The optional keyword slot can be used to specify the group slot; if not specified, the group is assigned to
id i
following conditions are fulfilled: 1) the ID is given; 2) an existing node is found near the potential new node location; and 3) the found node is part of a
pile with ID equal to i.
maximum-length f
segments i
snap 
Indicate that the first and last positions of the element(s) created will attempt to "snap" to the location of the nearest structural node (attached to any
structure pile delete command

Syntax
structure pile delete <range>
Delete all pile elements in the range. Structure nodes and links that become disconnected from any element will automatically be deleted as well.
structure pile group command

Syntax
structure pile group s <keyword>
Primary keywords:
slot | remove
Assign all pile elements in the range to the group with the name s. Use of the group logic is described in Group. Any element may only belong to one group in a given
slot. Assigning an element to a new group in that slot will cause it to be removed from its current group assignment. The structure pile list group command lists
the existing element group names. The groups can be visualized with the pile plot item.
slot s
remove
structure pile hide command

Syntax
structure pile hide <keyword> <range>
Primary keywords:
b | undo
This commands hides or un-hides all pile elements in the range. By default, commands that use a range filter will skip hidden objects. This can be overruled with the
undo
this will reverse the operation of the last structure pile hide command. FLAC3D keeps a maximum undo stack of size 12.
structure pile history command

Syntax
structure pile history keyword
Primary keywords:
coupling-displacement-normal | coupling-stress-normal | coupling-yield-normal | coupling-displacement-shear | coupling-stress-shear | coupling-yield-shear | force |

force-x | force-y | force-z | moment | moment-x | moment-y | moment-z
Sample pile responses. Quantities for sampling include force and moment acting on the pile itself, and displacement, stress, and yield state in both the normal and shear
coupling springs.
If a pile is created using the structure pile create command, then the nodes of each element so created will be ordered such that the overall pile direction goes
from the begin point to the end point (i.e., the nodal connectivity of each element will be ordered such that the direction from v1 to v2 corresponds with the direction
from the begin point to the end point).
coupling-displacement-normal [keywordblock]
displacement in the normal direction coupling spring at end of the element. Sign convention for normal spring is+/-, indicating separation/overlap.
coupling-stress-normal [keywordblock]
stress in the normal direction coupling spring at end of the element. Sign convention for normal spring is +/-, indicating separation/ overlap.
coupling-yield-normal [keywordblock]
yield state in the normal direction coupling spring at end of the element. Value {0, 1, 2} denotes never yielded, yielding now, or yielded in past, respectively.
coupling-displacement-shear [keywordblock]
displacement in the shear direction coupling spring at end of the element. Sign convention for shear spring is +/- with respect to average axial direction of pile.
coupling-stress-shear [keywordblock]
stress in the shear direction coupling spring at end of the element. Sign convention for shear spring is +/- with respect to average axial direction of pile.
coupling-yield-shear [keywordblock]
yield state in the shear coupling spring at end of the element. Value {0, 1, 2} denotes never yielded, yielding now, or yielded in past, respectively.
force magnitude
force (x-component, element system)
force (y-component, element system)
force (z-component, element system)
moment magnitude
moment (x-component, element system)
moment (y-component, element system)
moment (z-component, element system)
Keyword Block
Either the cid keyword or the position keyword must be supplied. The end keyword is optional. coupling-displacement-normal, coupling-displacement-shear,
coupling-stress-normal, coupling-stress-shear, coupling-yield-normal, coupling-yield-shear, force, force-x, force-y, force-z, moment, moment-x,
moment-y and moment-z.
component-id i
the particular element is identified by the CID number. If this keyword is used, position should not be used.
end i
position v
structure pile import command

Syntax
structure pile import keyword
Primary keywords:
Keyword Block
Any of the following keywords may be optionally supplied for use with the major keywords of structure pile import: from-extruder, from-file and from-
geometry.
distinct
id i
following conditions are fulfilled: 1) the ID is given; 2) an existing node is found “near” the potential new node location; and 3) the found node is part of an
group s <keyword>
slot s
maximum-length f
segments i
snap 
structure pile initialize command

Syntax
structure pile initialize <keyword>
Primary keywords:
coupling | force-axial
coupling
force-axial f
initializes the axial force in the element to f by setting the internal nodal forces. Note that this will override the existing internal nodal translational force state in
the element.
structure pile list command

Syntax
structure pile list keyword
Primary keywords:
apply | coupling-confinement | coupling-normal | coupling-shear | coupling-yield | force-end | force-node | group | information | length | property | system-local
apply
applied distributed loads
coupling-confinement
confining stress acting perpendicular to the element, both principal values
coupling-normal
values for the coupling spring in the normal direction, including displacement, stress, and direction
coupling-shear
values for the coupling spring in the shear direction, including displacement, stress, and direction
coupling-yield
state of the coupling springs in the shear and normal direction, and the current gap values
force-end
forces exerted by the end nodes on the element, in element local coordinates
force-node keyword
local
global
group <slot s >
information
length
length of the element
property keyword
list a pile property using one of the following keywords
density
density, ρ
young
plastic-moment
plastic moment, MP
poisson
thermal-expansion
moi-y
moi-z
moi-polar
direction-y
y-direction vector components
slide
sliding flag
slide-tolerance
sliding tolerance
coupling-confining-flag
flag to activate incremental confining stress logic (default: off)
coupling-confining-table
name of the table relating effective confining stress factor to deviatoric stress
coupling-cohesion-normal
normal coupling spring cohesive strength, cn
coupling-cohesion-shear
shear coupling spring cohesive strength, cs
coupling-cohesion-table
name of the table relating cohesion of shear coupling spring to relative shear displacement
coupling-friction-normal
normal coupling spring friction angle, φn
coupling-friction-shear
shear coupling spring friction angle, φs
coupling-friction-table
name of the table relating friction angle of shear coupling spring to relative shear displacement
coupling-gap-normal
normal coupling spring gap-use flag, g
coupling-stiffness-normal
normal coupling spring stiffness, kn
coupling-stiffness-shear
shear coupling spring stiffness, ks
perimeter
exposed perimeter, p
rockbolt-flag
flag to activate rockbolt logic (default: off)
tensile-failure-strain
tensile failure strain (nondimensional)
tensile-yield
axial tensile yield strength (force units), [F]
system-local
structure pile property command

Syntax
structure pile property keyword <range>
Primary keywords:
coupling-cohesion-normal | coupling-cohesion-shear | coupling-cohesion-table | coupling-confining-flag | coupling-confining-table | coupling-friction-normal | coupling-

friction-shear | coupling-friction-table | coupling-gap-normal | coupling-stiffness-normal | coupling-stiffness-shear | cross-sectional-area | density | direction-y | moi-
polar | moi-y | moi-z | perimeter | plastic-moment | poisson | rockbolt-flag | slide | slide-tolerance | tensile-failure-strain | tensile-yield | thermal-expansion | young
coupling-cohesion-normal f
normal coupling spring cohesive strength, cn
coupling-cohesion-shear f
shear coupling spring cohesive strength, cs
coupling-cohesion-table s
name of the table relating cohesion of shear coupling spring to relative shear displacement
coupling-confining-flag b
flag to activate incremental confining stress logic (default: off)
coupling-confining-table s
name of the table relating effective confining stress factor to deviatoric stress
coupling-friction-normal f
normal coupling spring friction angle, fn
coupling-friction-shear f
shear coupling spring friction angle, fs
coupling-friction-table s
name of the table relating friction angle of shear coupling spring to relative shear displacement
coupling-gap-normal b
normal coupling spring gap-use flag, g
coupling-stiffness-normal f
normal coupling spring stiffness, kn
coupling-stiffness-shear f
shear coupling spring stiffness, ks
density f
density,
direction-y v
y-direction vector components
moi-polar f
moi-y f
moi-z f
perimeter f
exposed perimeter, p
plastic-moment f
plastic moment, MP
poisson f
Poisson’s ratio,
rockbolt-flag b
flag to activate rockbolt logic (default: off)
slide b
sliding flag
slide-tolerance f
sliding tolerance
tensile-failure-strain f
tensile failure strain (nondimensional)
tensile-yield f
axial tensile yield strength (force units), [F]
thermal-expansion f
thermal expansion coefficient, at
young f
structure pile refine command

Syntax
structure pile refine i <range>
this command refines an existing element in the range by subdividing it into i equal-size segments. The original structural element is deleted.
structure pile select command

Syntax
structure pile select <keyword>
Primary keywords:
b | new | undo
This command selects or de-selects all elements in the range. Selected objects can be specified in a range filter by using the selected keyword. Objects that are not
new
undo
this will reverse the operation of the last structure pile select command. FLAC3D keeps a maximum undo stack of size 12.
FISH Functions
FISH functions operating on extrusion piles. The type specifiers used in the FISH function signatures are given in the FISH Type Index section.
Note that all beam functions may also be used on pile elements.
Structural Pile Functions
struct.pile.area(STRUCT_PILE_PNT)
Get/set the cross-section area of the pile element.
struct.pile.axial.yield(STRUCT_PILE_PNT)
Get/set the axial tensile yield strength (force units) of the...
struct.pile.force(STRUCT_PILE_PNT,INT<,INT>)
Get the nodal force acting on the pile element at...
struct.pile.force.nodal(STRUCT_PILE_PNT,INT<,INT>)
struct.pile.gap(STRUCT_PILE_PNT,INT,INT)
Get the gap component in normal spring at end iend ...
struct.pile.length(STRUCT_PILE_PNT)
Get/set the length of the pile element.
struct.pile.load(STRUCT_PILE_PNT<,INT>)
Get/set the uniform applied distributed load acting on the pile...
struct.pile.moi(STRUCT_PILE_PNT<,INT>)
Get/set the moment of inertia of the pile.
struct.pile.moment(STRUCT_PILE_PNT,INT<,INT>)
Get the nodal moment acting on the pile element at...
struct.pile.moment.plastic(STRUCT_PILE_PNT)
Get/set the plastic moment capacity of the pile element.
struct.pile.normal.cohesion(STRUCT_PILE_PNT)
Get/set the normal coupling spring cohesive strength of the pile...
struct.pile.normal.dir(STRUCT_PILE_PNT,INT<,INT>)
Get the global direction in which the pile element is...
struct.pile.normal.disp(STRUCT_PILE_PNT,INT)
Get the displacement in the coupling normal spring at end...
struct.pile.normal.friction(STRUCT_PILE_PNT)
Get/set the normal coupling spring friction angle of the pile...
struct.pile.normal.gap(STRUCT_PILE_PNT)
Get the normal coupling spring gap-use flag.
struct.pile.normal.state(STRUCT_PILE_PNT,INT)
Get the yield state of the coupling normal spring at...
struct.pile.normal.stiffness(STRUCT_PILE_PNT)
Get/set the normal coupling spring stiffness of the pile element.
struct.pile.normal.stress(STRUCT_PILE_PNT,INT)
Get the stress in the coupling normal spring at end...
struct.pile.perimeter(STRUCT_PILE_PNT)
Get/set the exposed perimeter of the pile element.
struct.pile.poisson(STRUCT_PILE_PNT)
Get/set the Poisson’s ratio of the pile element.
struct.pile.rockbolt(STRUCT_PILE_PNT)
Get a boolean flag of the rockbolt.
struct.pile.shear.cohesion(STRUCT_PILE_PNT)
Get/set the shear coupling spring cohesive strength of the pile...
struct.pile.shear.dir(STRUCT_PILE_PNT,INT<,INT>)
struct.pile.shear.disp(STRUCT_PILE_PNT,INT)
Get the displacement in coupling shear spring at end iend ...
struct.pile.shear.flag(STRUCT_PILE_PNT)
Get the shear direction incremental confining stress flag.
struct.pile.shear.friction(STRUCT_PILE_PNT)
Get/set the shear coupling spring friction angle of the pile...
struct.pile.shear.state(STRUCT_PILE_PNT,INT)
Get the yield state of the coupling shear spring at...
struct.pile.shear.stiffness(STRUCT_PILE_PNT)
Get/set the shear coupling spring stiffness of the pile element.
struct.pile.shear.stress(STRUCT_PILE_PNT,INT)
Get the stress in coupling shear spring at end iend ...
struct.pile.slide(STRUCT_PILE_PNT)
Get a boolean flag of slide.
struct.pile.slide.tol(STRUCT_PILE_PNT)
Get/set the large-strain sliding tolerance of the pile element.
struct.pile.strain.failure(STRUCT_PILE_PNT)
Get/set the tensile failure strain (non-dimensional) of the pile element.
struct.pile.stress.confining(STRUCT_PILE_PNT,INT)
Get the confining stress at end iend ∈ {1, 2}...
struct.pile.table.cohesion(STRUCT_PILE_PNT)
Get/set the shear direction cohesion strength table number for the...
struct.pile.table.factor(STRUCT_PILE_PNT)
Get/set the shear direction friction table number for the pile...
struct.pile.table.friction(STRUCT_PILE_PNT)
Get/set the shear direction incremental confining stress factor table number...
struct.pile.volume(STRUCT_PILE_PNT)
Get/set the volume of the pile element.
struct.pile.ydir(STRUCT_PILE_PNT<,INT>)
Get the y -axis of the pile element local system.
struct.pile.young(STRUCT_PILE_PNT)
Get/set the Young’s modulus of the pile element.
l struct.pile.area
l struct.pile.axial.yield
l struct.pile.force
l struct.pile.force.nodal
l struct.pile.gap
l struct.pile.length
l struct.pile.load
l struct.pile.moi
l struct.pile.moment
l struct.pile.moment.plastic
l struct.pile.normal.cohesion
l struct.pile.normal.dir
l struct.pile.normal.disp
l struct.pile.normal.friction
l struct.pile.normal.gap
l struct.pile.normal.state
l struct.pile.normal.stiffness
l struct.pile.normal.stress
l struct.pile.perimeter
l struct.pile.poisson
l struct.pile.rockbolt
l struct.pile.shear.cohesion
l struct.pile.shear.dir
l struct.pile.shear.disp
l struct.pile.shear.flag
l struct.pile.shear.friction
l struct.pile.shear.state
l struct.pile.shear.stiffness
l struct.pile.shear.stress
l struct.pile.slide
l struct.pile.slide.tol
l struct.pile.strain.failure
l struct.pile.stress.confining
l struct.pile.table.cohesion
l struct.pile.table.factor
l struct.pile.table.friction
l struct.pile.volume
l struct.pile.ydir
l struct.pile.young
struct.pile.area
Syntax
f = struct.pile.area(p)
struct.pile.area(p) = f

Arguments: p - a pointer to a pile element
struct.pile.axial.yield
Syntax
f = struct.pile.axial.yield(p)
struct.pile.axial.yield(p) = f
Get/set the axial tensile yield strength (force units) of the pile element.
Returns: f - the axial tensile yield strength (force units) of the element
Accepts: f - the axial tensile yield strength (force units) of the element
struct.pile.force
Syntax
Vector Access
v = struct.pile.force(p,iend<,i>)
Get the nodal force acting on the pile element at end iend ∈ {1, 2} in the element local system. Returns a vector, unless an optional component argument i is supplied, in
which case it returns the component value.

Component Access
f = struct.pile.force.x(p,iend)
Get the x-component of the nodal force acting on the pile element at end iend ∈ {1, 2} in the element local system.
Returns: f - x-component of nodal force

f = struct.pile.force.y(p,iend)
Get the y-component of the nodal force acting on the pile element at end iend ∈ {1, 2} in the element local system.
Returns: f - y-component of nodal force

f = struct.pile.force.z(p,iend)
Get the z-component of the nodal force acting on the pile element at end iend ∈ {1, 2} in the element local system.
Returns: f - z-component of nodal force

struct.pile.force.nodal
Syntax
m = struct.pile.force.nodal(p,iend<,idof>)
Get the generalized nodal force acting at end iend in the global system.
If the optional argument idof is provided, it returns the force in that specific degree-of-freedom (from 1 to 6).
Returns: m - a 1×6 matrix with the generalized nodal force at end iend, or the value of specific degree-of-freedom idof
iend - indicates which end of the pile, either 1 or 2
struct.pile.gap
Syntax
f = struct.pile.gap(p,iend,ig)
Get the gap component in normal spring at end iend ∈ {1, 2} of the pile element. The gap forms a rectangular shape in the pile cross-sectional plane, which is defined
by the local yz-axes of the pile element node. The gap consists of four values denoting gap size in the positive and negative y- and z-directions. The value of ig ∈ {1, 2,
3, 4} denotes the positive y-direction, negative y-direction, positive z-direction, and negative z-direction, respectively. The gap is always being tracked, but only affects
behavior if the normal coupling spring gap-use flag function struct.pile.normal.gap is true.
Returns: f - the gap component

iend - end number of the pile element, iend ∈ {1, 2}
ig - an integer (see explanations above)
struct.pile.length
Syntax
f = struct.pile.length(p)
Returns: f - the length of the element

struct.pile.load
Syntax
v = struct.pile.load(p<,idof>)
struct.pile.load(p<,idof>) = v
Get/set the uniform applied distributed load acting on the pile element in the local y- and z-directions.
The x-component of the return value will always be 0.0; on assignment it is ignored.
The optional argument idof can be used to specify whether only the value in the y- or z-direction will be returned/assigned.
Returns: v - the uniform applied distributed load acting on the pile element, or the y- or z-component
Accepts: v - the uniform applied distributed load acting on the pile element, or the y- or z-component
idof - an optional degree-of-freedom indication, which should be 2 or 3
struct.pile.moi
Syntax
Vector Access
v = struct.pile.moi(p<,i>)
struct.pile.moi(p<,i>) = v
This is defined as the second moment of inertia with respect to the x-, y-, and z-axes.

Accepts: v - moment of inertia vector or component
Component Access
f = struct.pile.moi.x(p)
struct.pile.moi.x(p) = f
Get/set the second moment of inertia with respect to the x-axis.
Returns: f - x-component moment of inertia vector

Accepts: f - x-component moment of inertia vector
f = struct.pile.moi.y(p)
struct.pile.moi.y(p) = f
Get/set the second moment of inertia with respect to the y-axis.
Returns: f - y-component moment of inertia vector

Accepts: f - y-component moment of inertia vector
f = struct.pile.moi.z(p)
struct.pile.moi.z(p) = f
Get/set the second moment of inertia with respect to the z-axis.
Returns: f - z-component moment of inertia vector

Accepts: f - z-component moment of inertia vector
struct.pile.moment
Syntax
Vector Access
v = struct.pile.moment(p,iend<,i>)
Get the nodal moment acting on the pile element at end iend ∈ {1, 2} in the element local system. Returns a vector, unless an optional component argument i is
supplied, in which case it returns the component value.

Component Access
f = struct.pile.moment.x(p,iend)
Get the x-component of the nodal moment acting on the pile element at end iend ∈ {1, 2} in the element local system.
Returns: f - x-component of nodal moment

f = struct.pile.moment.y(p,iend)
Get the y-component of the nodal moment acting on the pile element at end iend ∈ {1, 2} in the element local system.
Returns: f - y-component of nodal moment

f = struct.pile.moment.z(p,iend)
Get the z-component of the nodal moment acting on the pile element at end iend ∈ {1, 2} in the element local system.
Returns: f - z-component of nodal moment

struct.pile.moment.plastic
Syntax
f = struct.pile.moment.plastic(p)
struct.pile.moment.plastic(p) = f
Returns: f - the plastic moment capacity of the element

Accepts: f - the plastic moment capacity of the element
struct.pile.normal.cohesion
Syntax
f = struct.pile.normal.cohesion(p)
struct.pile.normal.cohesion(p) = f
Get/set the normal coupling spring cohesive strength of the pile element.
Returns: f - the normal coupling spring cohesive strength of the element

Accepts: f - the normal coupling spring cohesive strength of the element
struct.pile.normal.dir
Syntax
Vector Access
v = struct.pile.normal.dir(p,iend<,i>)
Get the global direction in which the pile element is being loaded by the coupling normal spring at end iend ∈ {1, 2}. Returns a vector, unless an optional component
argument i is supplied, in which case it returns the component value.
Returns: v - vector or component of the direction

Component Access
f = struct.pile.normal.dir.x(p,iend)
Get the x-component of the global direction in which the pile element is being loaded by the coupling normal spring at end iend ∈ {1, 2}.
Returns: f - x-component of the direction

f = struct.pile.normal.dir.y(p,iend)
Get the y-component of the global direction in which the pile element is being loaded by the coupling normal spring at end iend ∈ {1, 2}.
Returns: f - y-component of the direction

f = struct.pile.normal.dir.z(p,iend)
Get the z-component of the global direction in which the pile element is being loaded by the coupling normal spring at end iend ∈ {1, 2}.
Returns: f - z-component of the direction

struct.pile.normal.disp
Syntax
f = struct.pile.normal.disp(p,iend)
Get the displacement in the coupling normal spring at end iend ∈ {1, 2} of the pile element. Sign convention for normal spring is positive/negative, indicating
separation/overlap.
Returns: f - the normal coupling spring stiffness of the element

struct.pile.normal.friction
Syntax
f = struct.pile.normal.friction(p)
struct.pile.normal.friction(p) = f
Get/set the normal coupling spring friction angle of the pile element.
Returns: f - the normal coupling spring friction angle of the element

Accepts: f - the normal coupling spring friction angle of the element
struct.pile.normal.gap
Syntax
b = struct.pile.normal.gap(p)
Get the normal coupling spring gap-use flag. A true value denotes gap is on, and a false value denotes gap is off.
Returns: b - the normal coupling spring gap-use flag

struct.pile.normal.state
Syntax
i = struct.pile.normal.state(p,iend)
Get the yield state of the coupling normal spring at end iend ∈ {1, 2} of the pile element. Return value ∈ {0, 1, 2} denotes never yielded, now yielding, or yielded in the
past, respectively.
Returns: i - a value ∈ {0, 1, 2} denotes never yielded, now yielding, or yielded in the past, respectively
struct.pile.normal.stiffness
Syntax
f = struct.pile.normal.stiffness(p)
struct.pile.normal.stiffness(p) = f

Accepts: f - the normal coupling spring stiffness of the element
struct.pile.normal.stress
Syntax
f = struct.pile.normal.stress(p,iend)
Get the stress in the coupling normal spring at end iend ∈ {1, 2} of the pile element. Sign convention for the normal spring is positive/negative, indicating
separation/overlap.
Returns: f - the normal coupling spring stress of the element

struct.pile.perimeter
Syntax
f = struct.pile.perimeter(p)
struct.pile.perimeter(p) = f
Returns: f - the exposed perimeter of the element

Accepts: f - the exposed perimeter of the element
struct.pile.poisson
Syntax
f = struct.pile.poisson(p)
struct.pile.poisson(p) = f
Returns: f - the Poisson’s ratio of the element

Accepts: f - the Poisson’s ratio of the element
struct.pile.rockbolt
Syntax
b = struct.pile.rockbolt(p)
Get a boolean flag of the rockbolt. A true value denotes the rockbolt flag is on, and a false value denotes the rockbolt flag is off.
Returns: b - the rockbolt flag

struct.pile.shear.cohesion
Syntax
f = struct.pile.shear.cohesion(p)
struct.pile.shear.cohesion(p) = f
Get/set the shear coupling spring cohesive strength of the pile element.
Returns: f - the shear coupling spring cohesive strength of the element

Accepts: f - the shear coupling spring cohesive strength of the element
struct.pile.shear.dir
Syntax
Vector Access
v = struct.pile.shear.dir(p,iend<,i>)
Get the global direction in which the pile element is being loaded by the coupling shear spring at end iend ∈ {1, 2}. Returns a vector, unless an optional component
argument i is supplied, in which case it returns the component value.

Component Access
f = struct.pile.shear.dir.x(p,iend)
Get the x-component of the global direction in which the pile element is being loaded by the coupling shear spring at end iend ∈ {1, 2}.

f = struct.pile.shear.dir.y(p,iend)
Get the y-component of the global direction in which the pile element is being loaded by the coupling shear spring at end iend ∈ {1, 2}.

f = struct.pile.shear.dir.z(p,iend)
Get the z-component of the global direction in which the pile element is being loaded by the coupling shear spring at end iend ∈ {1, 2}.

struct.pile.shear.disp
Syntax
f = struct.pile.shear.disp(p,iend)
Get the displacement in coupling shear spring at end iend ∈ {1, 2} of the pile element. Sign convention for shear spring is positive/negative with respect to the average
axial direction of pile.
Returns: f - the shear coupling spring stiffness of the element

struct.pile.shear.flag
Syntax
b = struct.pile.shear.flag(p)
Get the shear direction incremental confining stress flag. A true value denotes the flag is on, and a false value denotes the flag is off.
Returns: b - the shear direction incremental confining stress flag

struct.pile.shear.friction
Syntax
f = struct.pile.shear.friction(p)
struct.pile.shear.friction(p) = f
Get/set the shear coupling spring friction angle of the pile element.
Returns: f - the shear coupling spring friction angle of the element

Accepts: f - the shear coupling spring friction angle of the element
struct.pile.shear.state
Syntax
i = struct.pile.shear.state(p,iend)
Get the yield state of the coupling shear spring at end iend ∈ {1, 2} of the pile element. Return a value ∈ {0, 1, 2} denote never yielded, now yielding, or yielded in the
past, respectively.
Returns: i - a value ∈ {0, 1, 2} denotes never yielded, now yielding, or yielded in the past, respectively
struct.pile.shear.stiffness
Syntax
f = struct.pile.shear.stiffness(p)
struct.pile.shear.stiffness(p) = f

Accepts: f - the shear coupling spring stiffness of the element
struct.pile.shear.stress
Syntax
f = struct.pile.shear.stress(p,iend)
Get the stress in coupling shear spring at end iend ∈ {1, 2} of the pile element. Sign convention for shear spring is positive/negative with respect to the average axial
direction of pile.

struct.pile.slide
Syntax
b = struct.pile.slide(p)
Get a boolean flag of slide. A true value denotes the slide flag is on, and a false value denotes the slide flag is off.
Returns: b - the slide flag

struct.pile.slide.tol
Syntax
f = struct.pile.slide.tol(p)
struct.pile.slide.tol(p) = f
Returns: f - the large-strain sliding tolerance of the element

Accepts: f - the large-strain sliding tolerance of the element
struct.pile.strain.failure
Syntax
f = struct.pile.strain.failure(p)
struct.pile.strain.failure(p) = f
Returns: f - the tensile failure strain of the element

Accepts: f - the tensile failure strain of the element
struct.pile.stress.confining
Syntax
f = struct.pile.stress.confining(p,iend)
Get the confining stress at end iend ∈ {1, 2} of the pile element. (Negative value is compression.) Stress acts in a plane perpendicular to the pile axis; confining stress is
the average of the principal values in this plane.

struct.pile.table.cohesion
Syntax
s = struct.pile.table.cohesion(p)
struct.pile.table.cohesion(p) = s
Get/set the shear direction cohesion strength table number for the pile element.

struct.pile.table.factor
Syntax
s = struct.pile.table.factor(p)
struct.pile.table.factor(p) = s
Get/set the shear direction friction table number for the pile element.

struct.pile.table.friction
Syntax
s = struct.pile.table.friction(p)
struct.pile.table.friction(p) = s
Get/set the shear direction incremental confining stress factor table number for the pile element.

struct.pile.volume
Syntax
f = struct.pile.volume(p)
Returns: f - the volume of the element

struct.pile.ydir
Syntax
Vector Access
v = struct.pile.ydir(p<,i>)
Get the y-axis of the pile element local system. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.
Returns: v - local system y-axis vector or component

Arguments: p - a pile pointer
Component Access
f = struct.pile.ydir.x(p)
Get the x-component of the y-axis of the pile element local system.
Returns: f - x-component of the y-axis of the local system of the pile element
f = struct.pile.ydir.y(p)
Get the y-component of the y-axis of the pile element local system.
Returns: f - y-component of the y-axis of the local system of the pile element
f = struct.pile.ydir.z(p)
Get the z-component of the y-axis of the pile element local system.
Returns: f - z-component of the y-axis of the local system of the pile element
struct.pile.young
Syntax
f = struct.pile.young(p)
struct.pile.young(p) = f
Returns: f - the Young’s modulus of the element

Accepts: f - the Young’s modulus of the element
Shell-Type Structural Elements

The shell-type structural elements include shell elements, geogrid elements, and liner elements. The mechanical behavior of these elements can be divided into the structural
response of the shell material itself, and the way the element interacts with the grid. The structural response of the shell material is common to all shell-type elements, and is
described in this section. Specific behaviors that differ for each element type are described in the section for that type.
Mechanical Behavior
Each shell-type structural element (shell, geogrid, or liner) is defined by its geometric and material properties. A shell-type element is assumed to be a triangle of uniform
thickness lying between three nodal points. An arbitrarily curved structural shell can be modeled as a faceted surface composed of a collection of shell-type elements. Each
shell-type element behaves as an isotropic or anisotropic, linearly elastic material with no failure limit; however, one can introduce a plastic-hinge line (across which a
discontinuity in rotation may develop) along the edges between shell-type elements, using the same double-node procedure as applied to beams (see Plastic Hinge Formation
in a Shell Structure). Each shell-type element provides a different means of interacting with the grid (see Shell Structural Elements, Geogrid Structural Elements, and Liner
Structural Elements). The structural response of the shell is controlled by the finite element assigned to the element. There are five finite elements available: 2 membrane
elements, 1 plate-bending element and 2 shell elements. The general properties of these finite elements are described in Shell Finite Elements. Because these are all thin-shell
finite elements, shell-type elements are suitable for modeling thin-shell structures in which the displacements caused by transverse-shearing deformations can be neglected.
Thick-shell structures should be modeled with FLAC3D zones.
Each shell-type element has its own local coordinate system shown in Figure 1. This system is used to specify applied pressure loading. A separate material coordinate system
is used to specify orthotropic material properties, and a surface coordinate system (providing a continuous description of the shell mid-surface spanning adjacent shell-type
elements) is used to recover stresses — see Stresses in Shells. The shell-type element coordinate system is defined by the locations of its three nodal points, labeled 1, 2 and 3
in Figure 1. The shell-type element coordinate system is defined such that
1. the shell-type element lies in the -plane,

x
z
3. the -axis is normal to the element plane and positive on the "outside" of the shell surface. (The two sides of each shell-type element are designated as
outside and inside.)
The shell-type element coordinate system cannot be modified.
system3.png
Figure 1: Shell-type element coordinate system and 18 degrees of freedom available to the shell finite elements
Response Quantities
Stress quantities (which include stress resultants and stresses acting in the shell) can be recovered for all shell-type elements. The stress resultants are expressed in a surface
coordinate system that provides a continuous description of the shell mid-surface spanning adjacent shell-type elements. The stresses are expressed in the global coordinate
system. Stress quantities can only be recovered after a consistent surface coordinate system has been established (see Stress Recover Procedure). The stress quantities can be
accessed via FISH, and
1. printed with the structure shell list stress or structure shell list stress-principal commands, or the equivalent for geogrid or liner
elements.,
2. monitored with the structure shell history command (or equivalent for geogrid or liner elements), and
3. plotted with the Shell, Geogrid, or Liner plot items.
Note that the stresses and stress-resultants calculated with the structure shell recover (for example) command are the values stored in the element and available to FISH.
By default, the Shell-type plot items calculate stress resultant quantities independently. It is possible to instruct the plot items to display the values calculated with the
structure shell recover command, in which case they will not be update until the next command is issued.
Properties
Each shell-type element possesses 4 properties:
\
2. Isotropic:
\
isotropic, isotropic material properties: and where is Young's modulus [F/L2] and is Poisson's ratio.
Orthotropic:
orthotropic-membrane, orthotropic material properties, {c'11, c'12, c'22, c'33} [F/L2] which defines the membrane material stiffness matrix
[{{\bf E}_m}^
{\prime}] in the material coordinate system.
orthotropic-bending, orthotropic material properties, {c'11, c'12, c'22, c'33} [F/L2] which defines the bending material stiffness matrix
[{{\bf E}_b}^
orthotropic-both, orthotropic material properties, {c'11, c'12, c'22, c'33} [F/L2] which defines the membrane and bending stiffness matrix
[{\bf E}^
Anisotropic:
anisotropic-membrane, anisotropic membrane material properties, {c'11, c'12, c'13, c'22, c'23, c'33} [F/L2], which defines the membrane
material-stiffness matrix [E'm] in the material coordinate system.
anisotropic-bending, anisotropic bending material properties, {c'11, c'12, c'13, c'22, c'23, c'33} [F/L2], which defines the membrane bending-
stiffness matrix [E'b] in the material coordinate system.
anisotropic-both, anisotropic membrane and bending material properties, {c'11, c'12, c'13, c'22, c'23, c'33} [F/L2], which define membrane and
bending material-stiffness matrix [E'] in the material coordinate system.
\al
3. thermal-expansion, thermal-expansion coefficient, ph [1/T]
4. thickness, thickness, [L]
The material constitutive behavior may be isotropic, orthotropic or anisotropic; thus, one of property (2a) through (2g) must be specified. It is assumed that the material
properties are homogeneous over the shell-type element (i.e., they do not vary with position) and that the shell thickness is constant. A description of the material properties
follows.
The shell-type elements model general shell behavior as a superposition of membrane and bending actions via the five 3-noded triangular finite elements described in Shell
Finite Elements. The material properties of the finite elements that model membrane and bending actions are described by the material-rigidity matrices
[{\bf D}_m] = \int_{-{t/2}}^{+{t/2}} [{\bf E}_m]dz = t[{\bf E}_m]
[{\bf D}_b] = \int_{-{t/2}}^{+{t/2}} [{\bf E}_b]z^2dz = {{t^3} \over {12}} [{\bf

(1)
[{\bf [{\bf
respectively, where is the shell thickness and E} and E} are material-stiffness matrices that relate stresses to strains via the constitutive relations
\begin{Bmatrix} \sigma_m \end{Bmatrix} =

{\begin{Bmatrix} \sigma_x \\ \sigma_y \\ \tau_{xy} \end{Bmatrix}}_m =
\begin{bmatrix} {\bm E}_m \end{bmatrix} \begin{Bmatrix} {\bm \varepsilon} \end{Bmatrix} =
\begin{bmatrix} c^m_{11} & c^m_{12} & c^m_{13} \\ & c^m_{22} & c^m_{23} \\ sym. & & c^m_{33} \end{bmatrix} \begin{Bmatrix} \varepsilon_x \\ \varepsilon_y \\ \gamma_{xy} \end
{Bmatrix}
\begin{Bmatrix} \sigma_b \end{Bmatrix} =

{\begin{Bmatrix} \sigma_x \\ \sigma_y \\ \tau_{xy} \end{Bmatrix}}_b =
\begin{bmatrix} {\bm E}_b \end{bmatrix} \begin{Bmatrix} {\bm \varepsilon} \end{Bmatrix} =
(2)
[{\bf [{\bf
The material-rigidity matrices are used to form the finite element stiffness matrices ( D} is used by the CST and CST hybrid finite elements, and D} is used
by the DKT finite element) and to recover stress resultants. The stresses in (2) are obtained from the stress resultants by
\begin{Bmatrix} \sigma_m \end{Bmatrix} = \frac{1}{t} \begin{Bmatrix} N_x \\ N_y \\ N_{xy} \end{Bmatrix}
\begin{Bmatrix} \sigma_b \end{Bmatrix} = \frac{12}{t^3} \begin{Bmatrix} M_x \\ M_y \\ M_{xy} \end
[{\ [{\bf [{\bf

In the following discussion, we use bf when referring to relations that apply to both E} and E} . For isotropic material properties, only ,
t
and must be specified. For orthotropic and anisotropic material properties, the material directions and must be specified. For most cases,
[{\bf E}_m] = [{\bf E}_b] =
[{\bf E]} ; however, when modeling equivalent or transformed orthotropic shells (with elastic properties equal to the average properties of components of
[{\bf E}_m] \not= [{\bf
the original shell) and controlling the membrane and bending rigidities independently, it is necessary to set E}_b] .
Isotropic Material Properties
[{\bf E}_m] = [{\bf E}_b] = [{\

For the case of an isotropic shell, [{\bf E}] , and the six constants of bf are related to the two elastic constants of Young's modulus, , and
\
Poisson's ratio, , by
c_{11} &= c_{22} = {E \over 1 -

\nu^2}
c_{33} &= {E \over 2(1 +

\nu)}
c_{12} &= \nu\left({E \over 1 - \nu^2}

\right)
c_{13} &= c_
{23} = 0
c
The are invariant constants and retain the same values in any orthogonal coordinate system.
Orthotropic and Anisotropic Material Properties
Under the assumptions of linear elasticity, the general constitutive matrix of material stiffness coefficients is symmetric and can be expressed in terms of 21 independent
elastic constants. An orthotropic material has three preferred directions of elastic symmetry, and its material-stiffness matrix can be expressed in terms of 9 independent
elastic constants:
\begin{Bmatrix} \sigma_{x^{\prime}} \\ \sigma_{y^{\prime}} \\ \sigma_{z^{\prime}} \\

\tau_{x^{\prime}y^{\prime}} \\ \tau_{x^{\prime}z^{\prime}} \\ \tau_{y^{\prime}z^{\prime}} \end{Bmatrix} =
\begin{bmatrix} C^{\prime}_{11} & C^{\prime}_{12} & C^{\prime}_{13} & 0 &0 &0 \\
& C^{\prime}_{22} & C^{\prime}_{23} & 0 &0 &0 \\
& & C^{\prime}_{33} & 0 &0 &0 \\
& & & C^{\prime}_{44} & 0 &0 \\
& sym. & & & C^{\prime}_{55} & 0 \\
& & & &0 & C^{\prime}_{66} \end{bmatrix}
\begin{Bmatrix} \varepsilon_{x^{\prime}} \\ \varepsilon_{y^{\prime}} \\ \varepsilon_{z^{\prime}} \\
\gamma_{x^{\prime}y^{\prime}} \\ \gamma_{x^{\prime}z^{\prime}} \\ \gamma_{y^{\prime}z^{\prime}} \end
(3)
x^{\prime} y^{\prime} z^
in which {\prime} are the principal directions of orthotropy. This relation describes a three-dimensional orthotropic continuum. The relation can be
\sigma_{z^
restricted to describe an orthotropic shell by enforcing the Kirchhoff thin-plate conditions of plane stress ( {\prime}} = 0 ) and no transverse-shear strain (
\gamma_{x^{\prime}z^{\prime}} = \gamma_{y^{\prime}z^
{\prime}} = 0 ), so that the material-stiffness matrix can be expressed in terms of 4 independent elastic constants:
\begin{Bmatrix} \sigma^{\prime} \end{Bmatrix} =

\begin{Bmatrix} \sigma_x^{\prime} \\ \sigma_y^{\prime} \\ \tau_{x^{\prime}y^{\prime}} \end{Bmatrix} =
\begin{bmatrix} {\bm E^{\prime}} \end{bmatrix} \begin{Bmatrix} {\bm \varepsilon^{\prime}} \end{Bmatrix} =
\begin{bmatrix} c^{\prime}_{11} & c^{\prime}_{12} & 0 \\
& c^{\prime}_{22} & 0 \\
sym. & & c^{\prime}_{33} \end{bmatrix}
\begin{Bmatrix} \varepsilon_{x^{\prime}} \\ \varepsilon_{y^{\prime}} \\ \gamma_{x^{\prime}y^{\prime}} \end{Bmatrix} \rm {(orthotropic\
(4)
x^{\prime} y^ [{\bf E^
in which the shell mid-surface lies in the {\prime} -plane. The material-stiffness matrix expressed in the principal directions (denoted here by {\prime}}] ) has
four independent constants that define an orthotropic material.
The material-stiffness matrix of an anisotropic shell can be expressed in terms of 6 independent elastic constants:
\begin{Bmatrix} \sigma^{\prime} \end{Bmatrix} =

\begin{Bmatrix} \sigma_x^{\prime} \\ \sigma_y^{\prime} \\ \tau_{x^{\prime}y^{\prime}} \end{Bmatrix} =
\begin{bmatrix} {\bm E^{\prime}} \end{bmatrix} \begin{Bmatrix} {\bm \varepsilon^{\prime}} \end{Bmatrix} =
\begin{bmatrix} c^{\prime}_{11} & c^{\prime}_{12} & c^{\prime}_{13} \\
& c^{\prime}_{22} & c^{\prime}_{23} \\
sym. & & c^{\prime}_{33} \end{bmatrix}
\begin{Bmatrix} \varepsilon_{x^{\prime}} \\ \varepsilon_{y^{\prime}} \\ \gamma_{x^{\prime}y^{\prime}} \end{Bmatrix} \rm {(anisotropic\
(5)
x^{\prime} y^ [{\bf E^
in which the shell mid-surface lies in the {\prime} -plane. The material-stiffness matrix expressed in the material directions (denoted here by {\prime}}] ) has
six independent constants that define an anisotropic shell.
x^ \
Consider a shell-type element with its local coordinate system, , rotated with respect to the {\pri -axis by an angle, b , as shown in Figure 2. The strain-
\begin{bmatrix}{\bf T_{\varepsilon}}\end
transformation matrix, {bmatrix} , relates the strains in the two systems via
\begin{Bmatrix} {\bm \varepsilon^{\prime}} \end{Bmatrix} = \begin{bmatrix} {\bf T_{\bf \varepsilon}} \end{bmatrix} \begin{Bmatrix} {\bm \varepsilon} \end
(6) {Bmatrix}
\begin{bmatrix}{\bf T_{\varepsilon}}\end \
{bmatrix} can be expressed in terms of b as
\begin{bmatrix} {\bf T_{\varepsilon}} \end{bmatrix} =

\begin{bmatrix} c^2 & s^2 & cs \\ s^2 & c^2 & -cs \\ -2cs & 2cs & c^2 - s^2 \end
{bmatrix},
The stresses in the two systems are related via
\begin{Bmatrix} {\bf \sigma} \end{Bmatrix} =

\begin{bmatrix} {\bf T_{\varepsilon}} \end
{bmatrix}^T
Substituting (4) or (5) and (6) into the preceding yields
\begin{Bmatrix} {\bf \sigma} \end{Bmatrix} =

{bmatrix}^T
\begin{bmatrix} {\bf E^{\prime}} \end{bmatrix}
in which
\begin{bmatrix} {\bf E} \end{bmatrix} =

{bmatrix}^T
\begin{bmatrix} {\bf E^{\prime}} \end{bmatrix}
(7)
Thus we have, from (7) and (1), the expression
\begin{bmatrix} {\bf D}_m \end{bmatrix} =

t \begin{bmatrix} {\bf T_{\varepsilon}} \end
{bmatrix}^T
\begin{bmatrix} {\bf E^{\prime}_m} \end{bmatrix}
and
\begin{bmatrix} {\bf D}_b \end{bmatrix} =

\frac{t^3}{12} \begin{bmatrix} {\bf T_{\varepsilon}} \end
{bmatrix}^T
\begin{bmatrix} {\bf E^{\prime}_b} \end{bmatrix}
x y [{\bf E^
for the material-rigidity matrices of a shell in which the material directions are not aligned with the and axes. For an orthotropic shell, {\prime}}] has two
[{\
zero terms, but these terms will not, in general, be zero for bf when the principal directions of orthotropy are not aligned with the and axes.
../../../../../../_images/material-
x^{\prime}y^{\prime}z^
Figure 2: Shell-type element coordinate system and material coordinate system {\prime}
Determination of Orthotropic Material Properties
[{{\bf E}_m}^ [{{\bf E}_b}^

The material-stiffness matrix {\prime}] and {\prime}] can be expressed in terms of the elastic constants in (3) via
c^{\prime}_{11} &= C^{\prime}_{11} - {{C^{\prime}_{13} C^{\prime}_{13}} \over {C^{\prime}_

{33}}}

{33}}}
c^{\prime}_{33} &= C^{\prime}

_{44}

{33}}}
\nu_{x^ \nu_{y^ E^{\prime}_{x^

They can also be expressed in terms of the effective Poisson's ratios ( {\prime}} and {\prime}} ), effective moduli ( {\prime}} and
E^{\prime}_{y^
{\prime}}
) and shear modulus ( ) for orthotropic plates (Ugural 1981, p. 141):
c^{\prime}_{11} &= {{E^{\prime}_{x^{\prime}}} \over {1 - \nu_{x^{\prime}} \nu_{y^{\prime}}}}
c^{\prime}_{22} &= {{E^{\prime}_{y^{\prime}}} \over {1 - \nu_{x^{\prime}} \nu_{y^{\prime}}}}
c^{\prime}_{33} &= G
c^{\prime}_{12} &= {{E^{\prime}_{x^{\prime}} \nu_{y{\prime}}} \over {1 - \nu_{x^{\prime}} \nu_{y^{\prime}}}} = {{E^{\prime}_{y^{\prime}} \nu_{x{\prime}}} \over {1 - \nu_{x^{\prime}} \nu_{y^
(8)
Ugural states that the orthotropic plate moduli and Poisson's ratios are obtained by tension and shear tests, as in the case of isotropic materials.
When it is not possible to determine the material stiffnesses experimentally, an equivalent or transformed orthotropic plate (with elastic properties equal to the average
properties of components of the original plate), for which the membrane stiffnesses are approximated with the relations in (8), and the bending stiffnesses are approximated
with the following rigidities, can be used.
{c^b_{11}}^\prime &= {12 \over t^3} D_{x^

{\prime}}
{c^b_{22}}^\prime &= {12 \over t^3} D_{y^

{\prime}}
{c^b_{33}}^\prime &= {12 \over t^3} G_{x^{\prime}y^

{\prime}}
{c^b_{12}}^\prime &= {12 \over t^3} D_{x^{\prime}y^

{\prime}}
D_{x^ D_{y^ D_{x^{\prime}y^ G_{x^{\prime}y^

,
{\prime}} {\prime}} , {\prime}} and {\prime}} represent the flexural rigidities and the torsional rigidity of an orthotropic plate,
respectively. Rigidities for some commonly encountered cases are given in Figure 3. These cases include a reinforced concrete slab with orthogonal steel bars, a plate
reinforced by equidistant stiffeners, a plate reinforced by a set of equidistant ribs, and a corrugated plate.
click image to
enlarge
H = 2G_{xy} +
Figure 3: Rigidities of various orthotropic plates (from Ugural 1981, Table 6.1, where D_{xy} )*
Note
*Used with the permission of McGraw-Hill Publishing Company.
Shell Structural Elements

Note that shell structural elements are based on the Shell-Type Structural Element and share the underlying formulation and implementation.
Mechanical Behavior
The mechanical behavior of each shell structural element can be divided into the structural response of the shell material itself (see Mechanical Behavior), and the way in
which the shell element interacts with the grid. Shell elements may be rigidly connected to the grid such that stresses develop within the shell as the grid deforms; however,
more generalized grid connections are available with geogrid and liner elements.
Response Quantities
Shell element responses include stress resultants and stresses actiing in the shell. See Response Quantities.
Properties
Each shell element possesses 4 properties, there are also common to geogrid and liner elements and are documented in Shell-Type Properties.
Simple examples are given to illustrate the use of shells.
l Simple Beam — Two Equal Concentrated Loads — Shell Elements

l Cantilever Beam with Applied Moment at Tip — Shell Elements
l Plastic Hinge Formation in a Shell Structure
l Isotropic Rectangular Plate with Applied Pressure
l Advancing Lined Tunnel (Rigidly Connected to Zones)
A complete list of examples that use shell elements is available in Structural Shell Examples.
Commands & FISH

l Commands
l FISH Functions
Simple Beam — Two Equal Concentrated Loads — Shell Elements

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ? Examples.... Choose "Structure/Shell/ConcentratedLoads" and select "ConcentratedLoads.f3prj" to load. The
A simply supported beam is loaded by two equal concentrated loads symmetrically placed, as described in Simple Beam — Two Equal Concentrated Loads — Beam
Elements. Here this problem is replicated using shell elements to compute maximum mid-span deflection along with moment and shear distributions, which are compared
with the analytical solution.
The analytical solution corresponds with beam-theory assumptions; therefore, we must assign boundary conditions and properties to the shell model to replicate these
conditions. We create a shell model of the beam shown in Figure 1, such that length equals 9 m and depth, , equals 1 m. There are two issues to consider:
1/(1-
1. A plate manifests greater stiffness than a beam by a factor of \nu^2) , because the plate material through the depth (the -direction in Figure 1)
\kap \
inhibits development of anticlastic curvature, (Ugural 1981, p. 8). Therefore, we set =0 in our shell model.
V Q
2. If the x-direction of the surface coordinate system is aligned with the beam axis (the x-direction of Figure 1), then the shear force, , equals ,
M
where is the transverse-shear stress resultant, and the moment, , equals , where is the bending stress resultant. Note that
the equilibrium equations for a plate give
Q_x = {\partial M_x \over \partial x} + {\partial M_{xy} \over

\partial y}
M_
The beam-theory solution assumes that {xy} . But in our plate, the sides are slightly less stiff than the inside, which produces inward twist (with curvature
\kap x
) along each side edge. We can minimize this effect by restraining rotation about the -axis, but the nodes at the cross-diagonal points away from
M Q
the edges still displace slightly less than those along the edges, to produce small twisting moments, . The values of that we compute will be
M
correct on the inside, but incorrect for elements along the edges. The only way to completely eliminate would be to impose the exact non-twist beam-
theory deformation field. In our case, we are imposing the loading and computing the deformation field, so we expect the slight error in along the edges.
../../../../../_images/shellloads-diagram.png
Figure 1: Simply supported beam with two equal concentrated loads (distance in units of meters).
The FLAC3D model contains 144 shell elements and 88 nodes, as shown in Figure 2. We utilize a cross-diagonal mesh pattern to ensure symmetric response, and we utilize a
DKT plate bending finite element because this is a small-strain, plate-bending problem. The same results would be produced if we used either of the shell finite elements,
because no membrane loading occurs. We set the Young's modulus and Poisson's ratio equal to 200 GPa and 0, respectively. We set the shell thickness equal to 0.133887 m to
\t
produce a second moment of inertia, , equal to 200 -6 4
i 10 m . Boundary conditions consist of simple supports at the beam ends, and two point loads, each of
which is 10,000 N. The point loads are distributed to the four nodes along each load line based on tributary length associated with each node. Thus, the inner nodes carry
twice the load of the outer nodes.
../../../../../_images/shellloads-geom.png
Figure 2: FLAC3D model for simple beam problem modeled with shell elements.
\t
The displacement field is shown in Figure 3. The maximum displacement occurs at the beam center and equals 6.469 i 10-3 m, which corresponds exactly with the
theoretical value.
An alternative means of visualizing the displacement field for a small-strain simulation is to use the Shell plot item and specify a nonzero value for the deformation factor.
Figure 4 shows both the undeformed and the deformed shape by adding two Shell plot items to the view and specifying deformation factors of zero and 100, respectively.
../../../../../_images/shellloads-disp.png
Figure 3: Displacement field of simple beam modeled with shell elements.
../../../../../_images/shellloads-deform.png
Figure 4: Deformed (factor of 100) and undeformed shapes of simple beam modeled with shell elements.
Figure 5 and Figure 6 show the shear force and moment distributions. Based on this scale, they correspond with the theoretical solutions. These plot items display these
quantities in the surface coordinate system that is specified with the "Surf X" attribute, set such that the surface x-direction corresponds with the global x-direction, the surface
y-direction corresponds with the global z-direction, and the surface z-direction corresponds with the negative global y-direction. The sign convention for these stress resultants
is shown here. We see that positive corresponds with stretching of the fibers in the positive z-direction of the surface, and positive corresponds with shear
forces acting in the positive z-direction of the positive x-directed surface.
../../../../../_images/shellloads-shear.png
Figure 5: Shear force distribution in simple beam modeled with shell elements.
../../../../../_images/shellloads-moment.png
Figure 6: Moment distribution in simple beam modeled with shell elements.
A closer examination of the shear force and moment distributions in the left third of the beam is provided in Figure 8 and Figure 7. The moment distribution is constant across
\t
the depth and varies linearly from zero at the support to 3 4
i 10 at the third point, which corresponds exactly with the theoretical solution. The shear distribution is
not constant across the depth. It has the correct value away from the edges, but deviates from the beam-theory solution along the edges.
Q \t
At x =1.5 away from the edge, the values of and are found to be 1.0 i 104 and 1.5 x 104, respectively, which correspond exactly with the theoretical
\t \t
values. At x =1.5 near the edge, the values of and are found to be 9.25 i 103 and 1.5 i 104, respectively. We see that there is an error of
M
7.5% in the value of shear force along the edge. This deviation from the beam-theory solution arises from the nonzero value of that develops at the nodes along the
edge (see Figure 8).
../../../../../_images/shellloads-shearclose.png
Figure 7: Shear force distribution in left third of simple beam modeled with shell elements.
../../../../../_images/shellloads-momentclose.png
Figure 8: Moment distribution in left third of simple beam modeled with shell elements.
../../../../../_images/shellloads-twist.png
Figure 9: Twisting moment distribution in left third of simple beam modeled with shell elements.
The stress-recovery procedure smooths bending and membrane resultants at the nodes and then uses the bending resultants to compute the constant value of transverse-shear
resultants within each shell element. The best accuracy is obtained by smoothing these values over each surface patch for which the stresses will vary continuously. In this
problem, when we compute stresses using the structure shell recover command, by default, stresses are recovered, and thus smoothed, for all shell elements in the
model. The structure shell history resultant-qx command, however, only recovers stresses for the particular element identified; therefore, smoothing does not occur. In
Q
this problem, we sampled a history of in one element using the command
struct shell history resultant-qx surface-x (1,0,0) position (1.625,0,0.5)
\t
A plot of this quantity is shown in Figure 10, where we see that the value does not equal the value of 1.0 i 104, which we obtained above from the plot item and from
the structure shell recover resultants command. For this problem, the smoothing process is necessary to produce good values of .
../../../../../_images/shellloads-history.png
Figure 10: Evolution of shear force at centroid of a shell element (computed with no nodal smoothing).
Reference
Ugural, A. C. Stresses in Plates and Shells. New York: McGraw-Hill Publishing Company Inc. (1981).
Data File
ConcentratedLoads.f3dat
model new
model title "Simple Beam (modeled using shell elements)"
; Create shell elements and assign material properties
struct shell create by-quadrilateral (0,0,0) (9,0,0) (9,0,1) (0,0,1) size=(12,3) cross-diagonal element-type=dkt
struct shell property isotropic=(2e11, 0.0) thickness=0.133887
struct node fix velocity-x velocity-y rotation-x rotation-y range position-x 0.0 ; support at left end - hinge
struct node fix velocity-y rotation-x rotation-y range position-x 9.0 ; support at right end - roller
struct node fix velocity-z rotation-x rotation-y ; restrict non-beam deformation modes
; Applied loads
struct node apply force-edge (0,-1e4,0) range union position-x=3 position-x 6
; History
history interval 1
struct shell history resultant-qx surface-x (1,0,0) position (1.625,0,0.5)
; Solve to equilibrium
model save 'ConcentratedLoads'
Cantilever Beam with Applied Moment at Tip — Shell Elements

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Shell/Cantilever" and select "Cantilever.f3prj" to load. The main data files
used are shown at the end of this example. The remaining data files can be found in the project.
A cantilever beam is subjected to an applied moment at its tip, as described in Cantilever Beam with Applied Moment at Tip — Beam Elements. Here we replicate this
problem using shell elements to compute the large-strain y-direction deflection at the beam tip.
The FLAC3D model simulates a beam of 10 m length and 1 m depth. We utilize a cross-diagonal mesh pattern to ensure symmetric response, and we utilize the DKT-CST
Hybrid Shell Element. We set the Young's modulus and Poisson's ratio equal to 200 GPa and 0, respectively. We set the shell thickness equal to 0.133887 m to produce a
second moment of inertia, , equal to 200 × 10-6 m4. The left end is fully fixed in all six degrees of freedom. The total applied moment at the tip is 5 MN-m, one-half of
which is assigned to each of the two nodes at the tip.
The final structural configuration is shown in Figure 1. The y-direction deflection at the beam tip equals 5.471 m, which is within 0.1% of the analytical solution.
../../../../../_images/shellcantilever-disp.png
Figure 1: Final structural configuration.
Reference
Data File
Cantilever.f3dat
model new
model title "Cantilever beam (using shell elements), applied tip moment (large-strain)"
; Create shells and assign properties
struct shell create by-quad (0,0,0) (10,0,0) (10,0,1) (0,0,1) size (10,1) ...
cross-diagonal element-type=dkt-csth
struct shell property isotropic=(2e11, 0.0) thick=0.133887
struct node fix velocity rotation range position-x=0 ; fully fix left end
struct node apply moment=(0,0,2.5e6) range position-x=10
; Solve model
Plastic Hinge Formation in a Shell Structure

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Shell/PlasticHinge" and select "PlasticHinge.f3prj" to load. The main data
This example demonstrates a procedure by which FLAC3D can be used to calculate the initiation and subsequent behavior of a plastic hinge line that forms within a shell
structure. The double-node method described in Plastic Hinge Formation in a Beam Structure is replicated using shell elements. Double nodes are created along the hinge line,
and then appropriately link these nodes together. The double nodes allow a discontinuity in the rotation to occur when the limiting plastic moment is reached. For shell
elements, there is no analog to the single-node method (using the structure beam property plastic-moment command) that can be used to model plastic hinges in beam
elements.
The problem to be considered is described in Plastic Hinge Formation in a Beam Structure and shown in Figure 1. The FLAC3D model simulates a beam of 10 m length and 1
m depth (see Figure 2). A cross-diagonal mesh pattern is utilized to ensure symmetric response, and a DKT-CST Hybrid Shell Element is utilized to support the membrane
loading that will develop after failure if the problem is run in large-strain mode. The Young's modulus and Poisson's ratio are set equal to 200 GPa and 0, respectively. The
I
shell thickness is set equal to 0.133887 m to produce a second moment of inertia, , equal to 200 × 10-6 m4.
../../../../../_images/shellplastichinge-
diagram.png
Figure 1: Simple beam with single concentrated load.
../../../../../_images/shellplastichinge-geom.png
Figure 2: FLAC3D model for plastic hinge example using shell elements.
Two separate structure shell create commands are issued to produce a model containing two separate shell sections: one for the left half of the beam; the other for the
right half of the beam. Figure 3 shows the shell elements with the node positions marked; Figure 4 shows an outline of the shell elements, and marks the location of links.
Notice that there is a set of eight nodes that overlap along the beam center line, which are connected by node-to-node links.
../../../../../_images/shellplastichinge-nodes.png
Figure 3: Shell elements—nodes are shown as spheres.
../../../../../_images/shellplastichinge-links.png
Figure 4: Shell elements—link locations are shown as spheres.
We now create appropriate linkages between these nodes with the commands
struct node join

struct link attach rotation-z=normal-yield ; Change z-rot dof to normal-yield
; Set properties of those springs
struct link property rotation-z area=1.0 stiffness=5e9
struct link property rotation-z yield-compression=8.33e3 yield-tension=8.33e3 range position-x 5.0 position-z 0.3 0.7
struct link property rotation-z yield-compression=4.17e3 yield-tension=4.17e3 range position-x 5.0 position-z 0.0
The command creates node-to-node links on each node that lies in the same location as another. The links are shown in Figure 4 and are rigid in all directions by default. The
next command affects all links by setting the attachment conditions for the z-rotational direction to be a normal yield spring. three translational directions and the x- and y-
rotational directions to be rigid, and specifying a normal-yield spring to be inserted in the z-rotational direction. The final commands set the properties of these normal-yield
springs as follows. We set all areas to unity, and we set both the compressive and tensile yield strengths equal to the desired plastic-moment capacity (based on the tributary
length associated with each node). The total plastic-moment capacity is 25 kN-m, so we assign 8.33 kN-m to the two center springs and 4.17 kN-m to the two end springs.
Finally, we set the spring stiffness equal to a value that is large enough to make the spring deformation small relative to the shell deformation. We choose a value of 5 × 109,
which is approximately the rotational stiffness of the nodes just to the left of the center.
Now that the double-nodes have been appropriately linked to one another, simple supports are specified at the beam ends by restricting translation in the y-direction. A
constant vertical velocity is applied to the four target nodes on the right section, and the moment acting at the centroid of an element near the center is monitored during the
calculation to determine when the limiting value is reached.
We find that the limiting value of moment is reached (see Figure 5). Figure 6 shows the value at the beam center is found to be 24.89 kN, which is within 1% of the specified
moment capacity. Figure 7 shows that a discontinuity in the displacement has developed.
../../../../../_images/shellplastichinge-hist.png
Figure 5: Moment at centroid of an element near the center versus applied center displacement.
../../../../../_images/shellplastichinge-moment.png
Figure 6: Mx contours on the shell.
../../../../../_images/shellplastichinge-disp.png
Figure 7: y-displacements on an exaggerated deformation plot of the shell.
Data File
PlasticHinge.f3dat
model new
model title 'Plastic hinge formation (double-node method with shell elements)'
; Create shell elements in two groups
struct shell create by-quadrilateral (0,0,0) ( 5,0,0) ( 5,0,1) (0,0,1) size (6,3) ...
id=1 element-type=dkt-csth cross-diagonal group 'Left'
struct shell create by-quadrilateral (5,0,0) (10,0,0) (10,0,1) (5,0,1) size (6,3) ...
id=2 element-type=dkt-csth cross-diagonal group 'Right'
; Create links (default to rigid in all six dof) at nodes whos positions coincide
struct node join
struct link attach rotation-z=normal-yield ; Change z-rot dof to normal-yield
; Set properties of those springs
struct link property rotation-z area=1.0 stiffness=5e9
struct link property rotation-z yield-compression=8.33e3 yield-tension=8.33e3 range position-x 5.0 position-z 0.3 0.7
struct node fix velocity-y rotation-x rotation-y range position-x= 0.0 ; support at left end - roller
struct node fix velocity-y rotation-x rotation-y range position-x=10.0 ; support at rt. end - roller
struct node fix velocity-y range position-x 5.0 group 'Right'
struct node initialize velocity-y -5e-7 local range position-x 5.0 group 'Right'
; Histories
struct node history displacement-y position (5.0,0,0.6667)
struct shell history resultant-mx surface-x 1,0,0 position (4.861,0,0.5)
; Cycle the model
model cycle 30000 ; 0.015 total displacement
model save 'PlasticHinge'
Isotropic Rectangular Plate with Applied Pressure

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Shell/PlateAppliedPressure" and select "PlateAppliedPressure.f3prj" to
load. The main data files used are shown at the end of this example. The remaining data files can be found in the project.
An isotropic rectangular plate (4 m by 8 m) is simply supported along its edges. The solution for bending and deflection of the plate when subjected to a uniform pressure, p,
w_{\rm
is given by Ugural (1981, pp. 66-73). The maximum deflection, max} , occurs at the plate center and equals
w_{\rm max} = {\delta_1 p a^4

\over D}
The maximum bending stress resultants also occur at the plate center and equal
M_x &= \delta_3

p a^2
M_y &= \delta_2

p a^2
where: a = short length of plate;

D \
= flexural rigidity = {Et^3\over12(1-
\nu^2)}
(E is Young's modulus=, is Poisson's ratio, and t is plate thickness); and
\de \de \de \de
lta , = coefficients from Table 3.1 of Ugural (1981) ( lta = 0.01013, lta = 0.1017, lta = 0.0464).
\de
lta ,
\de
lta
The following shell properties are specified:
t 0.3 m
thickness ( )
30 GPa
Young's modulus ( )
0.30
Poisson's ratio ( )
For an applied pressure of 240 kPa, the plate oriented such that a = 4 m (aligned with the y-axis), and the long dimension of the plate aligned with the x-axis, the maximum
w_{\rm
plate deflection is max} = 8.39 mm, and the maximum bending stress resultants are = 178 kN and = 391 kN (where the surface coordinate system
in which and are expressed is aligned with the global system).
The FLAC3D model consists of 64 shell elements, as shown in Figure 1. Only half of the plate is modeled; a symmetry plane is prescribed at half the long dimension (at x =
4). The nodes along the symmetry edge have their x-velocities and y- and z-rotations fixed. The other three edges have only their z-velocities fixed to simulate simple
supports. (Although the proper classical plate theory boundary condition for a simple support also includes constraining rotation about an axis in the plane of the plate directed
normal to the edge, such classical boundary conditions tend to overconstrain the mesh and produce results that are too stiff (Cook 1989, p. 332).) The pressure loading is
applied with the structure shell apply command. A cross-diagonal mesh pattern is utilized to ensure symmetric response, and the DKT Plate Bending Element is also
utilized. The same results would be produced if either of the shell finite elements were used, because no membrane loading occurs.
../../../../../_images/plateapplied-geometry.png
Figure 1: FLAC3D model for rectangular plate problem.
The displacement field is shown in Figure 3 and Figure 2. The maximum plate deflection occurs at the plate center and equals 8.224 mm, which is within 2% of the theoretical
value.
M M
Contours of the bending stress resultants and are shown in Figure 4 and Figure 5. The exact values computed at the plate center of and are
182 kN and 396 kN, respectively, which are both within 2.3% of the analytical values.
../../../../../_images/plateapplied-deformed.png
Figure 2: Deformed (magnification of 100) shape of rectangular plate.
../../../../../_images/plateapplied-disp.png
Figure 3: Contours of plate deflection.
../../../../../_images/plateapplied-mx.png
Figure 4: Contour of bending stress resultant .
../../../../../_images/plateapplied-my.png
Figure 5: Contour of bending stress resultant .
References
Ugural, A. C. Stresses in Plates and Shells. New York: McGraw-Hill Publishing Company Inc. (1981).
Data File
PlateAppliedPressure.f3dat
model new
model title "Rectangular plate with applied pressure"
; Create shell elements and set properties
struct shell create by-quadrilateral (0,0,0) (4,0,0) (4,4,0) (0,4,0) size (4,4) ...
element-type=dkt cross-diagonal
; Bounday conditions
struct node fix velocity-z range position-y 4 ; Simply supported condition
struct node fix velocity-z range position-x 0
struct node fix velocity-z range position-y 0
struct node fix velocity-x rotation-y rotation-z range position-x 4 ; Symmetry condition
; Applied Pressure
struct shell apply -240e3
; Solve
model save 'PlateAppliedPressure'
Advancing Lined Tunnel (Rigidly Connected to Zones)

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ‣ Examples.... Choose "Structure/Shell/AdvancingTunnel" and select "AdvancingTunnel.f3prj" to load. The
This example demonstrates how to simulate the sequential operations of excavating and adding support to an advancing tunnel. The tunnel has a circular cross-section and is
\ E
located at 5 m depth in a soft elastic soil ( = 48.2 MPa, = 0.34) with isotropic in-situ stresses of 1 MPa. The tunnel is supported by shotcrete ( = 10.5
\
GPa, = 0.25) with a thickness of 0.2 m. The shotcrete remains elastic and rigidly connected to the soil throughout the simulation. (The shotcrete/soil interface can be
allowed to fail in either tension or shear, such that gaps can form and slip can occur, if liner elements are used instead of shells — see Advancing Lined Tunnel.)
The geometry for this model was constructed interactively using the Extruder tool, and the data file exported from the State Record into "geometry.f3dat". Figure 1 shows the
resulting geometry and the group names assigned to zones and zone faces using the Extruder tool and the zone face skin command.
../../../../../_images/advancing-geom.png
Figure 1: Model geometry with zone and face names assigned.
Begin with an initial tunnel of 2 m total length. For simplicity, it is assumed that the excavation proceeds simultaneously on both tunnel faces; therefore, it is only necessary to
model one quarter-section of the tunnel by applying symmetry boundary conditions on the three symmetry planes. The excavation process is modeled by assigning the null
material model to zones. Then the stresses are allowed to redistribute. The shotcrete is now installed by creating shell elements and attaching them to the tunnel surface with
the structure shell create by-face command. The next tunnel segment is excavated and, again, the stresses are allowed to redistribute. The model at this stage is shown
in Figure 2. This excavation sequence can be repeated to follow the entire tunnel construction.
../../../../../_images/advancing-stage2.png
Figure 2: Stage 2: Install shotcrete in section 1; excavate tunnel section 2.
Figure 3 and Figure 4 show the displacements that occur during the second excavation stage for the case with no support and the case with support, respectively. The z-
displacement history at the tunnel crown is included in each figure. It can be seen that the support reduces the crown displacement from approximately 12 mm to 1 mm.
../../../../../_images/advancing-disp2no.png
Figure 3: Displacements during stage 2—no support.
../../../../../_images/advancing-disp2.png
Figure 4: Displacements during stage 2—shotcrete support.
M
The bending stress resultant, , where the x-direction lies along the tunnel axis, is shown in Figure 5. It can be seen that bending is most extreme at the front of the
liner near the tunnel face. A plot of the deformed shape of the liner in Figure 6 indicates that this intense bending arises from the large pinching deformation.
../../../../../_images/advancing-mx2.png
Figure 5: Bending stress resultant, , at end of stage 2.
../../../../../_images/advancing-deform2.png
Figure 6: Deformed (magnification of 150) shape of shotcrete at end of stage 2.
One additional excavation stage is performed. The model at the end of this stage is shown in Figure 7. The shotcrete support has been extended into tunnel section 2 by
issuing another structure shell create by-face command, noting that by default a new ID number is issued for the elements created. This creates a "cold-joint" between
the two shotcrete segments. (There will be a collection of double nodes lying along the interface: one is used by segment one; the other is used by segment two. Forces and
moments will not be transferred between the adjoining elements; instead, only forces will be transmitted into the surrounding zones at the common locations. This mimics two
separate shell segments lying next to one another.) The deformation that occurs during stage 3 begins to load the new shell segment, and produces additional load in the
previous shell segment. Both the displacement (see Figure 8) and the bending stress (see Figure 9) fields are discontinuous across the joint.
../../../../../_images/advancing-stage3.png
../../../../../_images/advancing-deform3.png
Figure 8: Deformed (magnification of 150) shape of shotcrete at end of stage 3.
../../../../../_images/advancing-mx3.png
Figure 9: Bending stress resultant, , at end of stage 3.
Data File
AdvancingTunnel.f3dat
model new
model title 'Advancing Lined Tunnel (Rigidly Connected to Zones)'
; Create simple zone geometry, created interactively in Extruder and exported from the State Record
call 'geometry.f3dat' suppress ; Also assigns group names to model zones and faces.
zone generate from-extruder
; Model and properties
zone property bulk 50e6 shear 18e6
zone initialize stress xx -1e6 yy -1e6 zz -1e6
; Boundary Conditions - roller on near boundaries and fixed on far.
zone face apply velocity-normal 0 range group 'West'
zone face apply velocity-normal 0 range group 'South'
zone face apply velocity (0,0,0) range group 'East' or 'North' or 'Top'
; --- Stage 1: excavate tunnel section 1
zone cmodel assign null range group 'section1' group 'tunnel'
model save 'Stage1'
; Reset displacements, take history of roof closure

zone history displacement-z position (0,1,1)
model save 'Stage2-start'
model save 'Stage2-nosupport'
; -- Try with support

model restore 'Stage2-start'
; --- Add shotcrete, on shotcrete faces in section 1.
struct shell create by-face group 'shotcrete1' range group 'shotcrete' group 'section1'
struct shell property isotropic=(10.5e9, 0.25) thickness=0.2
; --- Boundary conditions for structural elements
struct node fix velocity-x rotation-y rotation-z range position-x 0 ; symmetry conditions
struct node fix velocity-y rotation-x rotation-z range position-y 0
struct node fix velocity-z rotation-x rotation-y range position-z 0
model save 'Stage2-support'
; --- Add shotcrete, on shotcrete faces in section 1.
struct shell create by-face group 'shotcrete2' range group 'shotcrete' group 'section2'
struct shell property isotropic=(10.5e9, 0.25) thickness=0.2
; --- Boundary conditions for structural elements
struct node fix velocity-x rotation-y rotation-z range position-x 0 ; symmetry conditions
struct node fix velocity-z rotation-x rotation-y range position-z 0
model save 'Stage3-support'
Commands
Operations on structural element shells.
Shell elements are plate elements that implement classic shell theory. They are, by default, rigidly connected to their surroundings.
Structural Element Cable Commands
structure shell apply

Assign uniform applied pressure f to all shell elements in...
structure shell create
Create a shell.
structure shell delete
Delete all shell elements in the range.
structure shell group
Assign all shell elements in the range to the group...
structure shell hide
This command hides or un-hides all shell elements in the...
structure shell history
Sample shell responses.
structure shell import
Create shell elements from an outside source.
structure shell initialize
structure shell list
List properties and response of each shell element in the...
structure shell property
structure shell recover
Stress-recovery for shell elements.
structure shell refine
This command refines elements in the range by subdividing them...
structure shell select
l structure shell apply command

l structure shell create command
l structure shell delete command
l structure shell group command
l structure shell hide command
l structure shell history command
l structure shell import command
l structure shell initialize command
l structure shell list command
l structure shell property command
l structure shell recover command
l structure shell refine command
l structure shell select command
structure shell apply command

Syntax
structure shell apply f <range>
Assign uniform applied pressure f to all shell elements in the range. Positive pressure acts in the positive z-direction of the element system and maintains this orientation
during large-strain motion.
structure shell create command

Syntax
structure shell create keyword
Primary keywords:
by-face | by-nodeids | by-quadrilateral | by-triangle
Create a shell. The four main keywords articulate four different techniques of creation: by creating a collection of elements from a group of zone faces (by-face); by
creating a single element from four existing nodes (by-nodes); from a specified quadrilateral (by-quadrilateral); or from a triangle (by-triangle).
by-face [keywordblock] <range>
Create new elements that are attached to the set of three- or four-sided zone-faces in the range. By default, only surface faces will be considered, and the internal
keyword can be used to select internal faces. New nodes associated with the element will also be created (see the id keyword). The nodes of each new element
will be ordered counter-clockwise with respect to the outside of the specified zone faces, thereby making the element z-axis point outward. The element will be
attached to the grid at its nodes with link attachment conditions appropriate to the element type (see this table in the topic Structural Element Links). Note that
after creating the elements with this command, the zones may be deleted and the elements may be positioned by moving its nodes with the structure node
initialize position command.
by-nodeids i1 i2 i3 [keywordblock]
Create elements given an existing set of nodes. The new elements will not be attached to the grid. If you wish to attach it to the grid, then after creating it, position
its nodes with the structure node initialize position command (which will create links and set appropriate attachment conditions for all nodes that are
moved into a zone).
by-quadrilateral v1 v2 v3 v4 [keywordblock]
Create elements based on four points forming a quadrilateral, in order. The element local system will point in the opposite direction determined by using the right-
hand rule. The new elements will not be attached to the grid. If you wish to attach it to the grid, then after creating it, position its nodes with the structure node
by-triangle position v1 v2 v3 [keywordblock]
Create elements based on three points forming a triangle. The element local system will point in the opposite direction determined by using the right-hand rule.
The new elements will not be attached to the grid. If you wish to attach it to the grid, then after creating it, position its nodes with the structure node
Keyword Block
The following keywords may be optionally provided on shell creation, using any of the major keywords: by-face, by-nodeids, by-quadrilateral and by-
triangle.
id i
controls potential joining of the element nodes to an existing element, as follows. At each potential new node location, a new node is created unless all of
the following conditions are fulfilled: 1) the ID is given; 2) an existing node is found “near” the potential new node location; and 3) the found node is part
of an element of the same type with ID equal to i.
group s1 <slot s2 >
Assign the created elements to group s1. The group is assigned to the slot named s2 if supplied; it is assigned to the slot named Default if not. Use of the
cross-diagonal 
If specified, a cross-diagonal mesh of four triangles will be created with a node lying at the centroid of all quadrilaterals; otherwise, a cross-hatch mesh of
two triangles will be created dividing the quadrilateral.
When connecting elements to the grid, it is best to locate nodes at gridpoints. If the finite-element type can resist bending (DKT, DKT-CST, or DKT-(CST
Hybrid) elements), then incompatibilities can develop along element faces and zone faces, because the transverse (out-of-plane) displacement field varies
cubically across element faces, but varies only linearly across zone faces. Thus, when connecting bending-resistant elements rigidly to zone faces, it is best
to utilize a cross-hatch mesh, because the middle node of the cross-diagonal mesh will be constrained to translate according to the linear displacement field
of the zone face. This over-constrains the elements and can produce near-zero moments at these mid-nodes when present in a nonzero moment field.
distinct
element-type keyword
Specify the finite element formation used by each structural element. If no element type is specified, then the element type will be DKT-CST. Note that the
type of finite element is associated with each structural element when it is created and cannot subsequently be altered. The finite element type of existing
structural elements is printed by the structure shell list element-type command. The value of the keyword supplied must be one of the following
three-noded finite elements:
Attempt to match the string s to one of the available keywords below, and treats as that option.
cst
CST (6 degrees-of-freedom) finite element. This is a membrane element; it resists membrane, but not bending, loading.
csth
CST Hybrid (9 degrees-of-freedom) finite element. This is a membrane element; it resists membrane, but not bending, loading.
dkt
DKT (9 degrees-of-freedom) finite element. This is a plate-bending element; it resists bending, but not membrane, loading.
dkt-cst
DKT-CST (15 degrees-of-freedom) finite element. This is a shell element that combines the DKT and CST elements to resist both bending and
membrane loading.
dkt-csth
DKT-(CST Hybrid) (18 degrees-of-freedom) finite element. This is a shell element that combines the DKT and CST Hybrid elements to resist both
bending and membrane loading.
internal
This keyword only applies if the from-faces option was used. Specifies that all internal and surface faces in the range will have elements created on them.
Normally only surface faces are considered.
maximum-length f
segments i
size i1 i2
This keyword only applies if the from-quadrilateral option was used. Increases the number of elements created by subdividing the quadrilateral into i1
segments along the first edge and i2 segments along the second. By default, only one quad is created.
structure shell delete command

Syntax
structure shell delete <range>
Delete all shell elements in the range. Structure nodes and links that become disconnected from any element will automatically be deleted as well.
structure shell group command

Syntax
structure shell group s1 <slot s2 >
Primary keywords:
slot | remove
Assign all shell elements in the range to the group with the name s. Use of the group logic is described in Group. Any element may only belong to one group in a given
slot. Assigning an element to a new group in that slot will cause it to be removed from its current group assignment. The command structure shell list group
command lists the existing element group names. The groups can be visualized with the shell plot item.
slot s
remove
structure shell hide command

Syntax
structure shell hide keyword
Primary keywords:
b | undo
This command hides or un-hides all shell elements in the range. By default, commands that use a range filter will skip hidden objects. This can be overruled with the
undo
this will reverse the operation of the last structure shell hide command. FLAC3D keeps a maximum undo stack of size 12.
structure shell history command

Syntax
structure shell history <name s > keyword
Primary keywords:
force | force-x | force-y | force-z | moment | moment-x | moment-y | moment-z | resultant-mx | resultant-my | resultant-mxy | resultant-nx | resultant-ny | resultant-nxy |
resultant-qx | resultant-qy | principal-intermediate | principal-maximum | principal-minimum | stress-xx | stress-xy | stress-xz | stress-yy | stress-yz | stress-zz
Sample shell responses. The nodes of a shell element will be ordered counter-clockwise with respect to the outside of the zone faces upon which the shell was created.
If the optional name keyword is used, the history can be assigned a name for later reference. If not used, the history will be assigned a default name based on the
internally assigned ID number.
The element to be sampled must be identified by either component ID (component-id i) or by position (position v). If position v is used, the shellSEL nearest to v is
taken.
For some structure shell histories, the node of the element to be sampled may be specified optionally with node i (where i = 1, 2, or 3). When node is omitted, node
1 is used by default.
For resultant histories, the surface system corresponds with the given value of Surface-X v (i.e., each time a stress-resultant history is sampled, the logic of the
structure shell recover surface command is invoked for the specified geogridSEL). Surface-X v is required for these histories.
For stress histories, stresses are computed at a shell depth given by Depth-Factor f as follows. The shell depth equals Ft/2, where F is the depth factor and t is the shell
thickness. F equal to +1/-1 corresponds with the outer/inner shell surface (outer surface defined by positive shell z-direction), and F = 0 corresponds with the shell mid-
surface. f defaults to +1 if depth-factor is not specified.
force magnitude, global system
nodal force (x-component, global system)
nodal force (y-component, global system)
nodal force (z-component, global system)
moment magnitude, global system
nodal moment (x-component, global system)
nodal moment (y-component, global system)
nodal moment (z-component, global system)
resultant-mx [keywordblock]
stress resultant Mx (surface system). Uses the surface-x keyword.
resultant-my [keywordblock]
stress resultant My (surface system). Uses the surface-x keyword.
resultant-mxy [keywordblock]
stress resultant Mxy (surface system). Uses the surface-x keyword.
resultant-nx [keywordblock]
stress resultant Nx (surface system). Uses the surface-x keyword.
resultant-ny [keywordblock]
stress resultant Ny (surface system). Uses the surface-x keyword.
resultant-nxy [keywordblock]
stress resultant Nxy (surface system). Uses the surface-x keyword.
resultant-qx [keywordblock]
stress resultant Qx (surface system). Uses the surface-x keyword.
resultant-qy [keywordblock]
stress resultant Qy (surface system). Uses the surface-x keyword.
principal-intermediate [keywordblock]
principal intermediate stress, global system. Uses the depth-factor keyword.
principal-maximum [keywordblock]
principal maximum stress, global system. Uses the depth-factor keyword.
principal-minimum [keywordblock]
principal minimum stress, global system. Uses the depth-factor keyword.
stress-xx [keywordblock]
stress (xx-component, global system). Uses the depth-factor keyword.
stress-xy [keywordblock]
stress (xy-component, global system). Uses the depth-factor keyword.
stress-xz [keywordblock]
stress (xz-component, global system). Uses the depth-factor keyword.
stress-yy [keywordblock]
stress (yy-component, global system). Uses the depth-factor keyword.
stress-yz [keywordblock]
stress (yz-component, global system). Uses the depth-factor keyword.
stress-zz [keywordblock]
stress (zz-component, global system). Uses the depth-factor keyword.
Keyword Block
The following keywords are available to control the location and other details of the history. Some keywords are only available if noted. force, force-x, force-y,
force-z, moment, moment-x, moment-y, moment-z, principal-intermediate, principal-maximum, principal-minimum, resultant-mx, resultant-mxy,
resultant-my, resultant-nx, resultant-nxy, resultant-ny, resultant-qx, resultant-qy, stress-xx, stress-xy, stress-xz, stress-yy, stress-yz and
stress-zz.
component-id i
the element is selected by its individual component ID number
depth-factor f
the depth factor used to determine element stresses. Only available if noted.
node i
the node location to use when retrieving values from the element. Must be from 1 to 3. Only available if noted.
position v
the element with a centroid closest to v is selected
surface-x v
the local x-direction used to determine the local surface coordinate system. Only available if noted.
structure shell import command

Syntax
structure shell import keyword
Primary keywords:
from-file | from-geometry
the optional format keyword can be used to specify the format of the file. The options are dxf, geom, or stl. [CS: work out what needs to happen here later;
Keyword Block
Any of the following keywords may be optionally supplied for use with the major keywords of structure shell import: from-file and from-geometry.
distinct
id i
group s1 <slot s2 >
cross-diagonal 
Specify the finite element formulation used by each structural element. If no element type is specified, then the element type will be DKT-CST. Note that
the type of finite element is associated with each structural element as it is created and cannot subsequently be altered. The finite element type of existing
structural elements is printed by the structure shell list element-type command. The value of the keyword supplied must be one of the following
Attempt to match the string s to one of the available keywords below, and treats as that option
cst
csth
dkt
dkt-cst
membrane loading.
dkt-csth
internal
maximum-length f
segments i
structure shell initialize command

Syntax
structure shell initialize <keyword>
Primary keywords:
coupling
coupling
structure shell list command

Syntax
structure shell list keyword <range>
Primary keywords:
apply | depth-factor | element-type | group | information | force-node | property | resultant | stress | stress-principal | system-local
List properties and response of each shell element in the range.
apply
uniform applied pressure acting on the element
depth-factor
depth factor used during stress recovery
element-type
finite element type used
group <slot s >
list the group assignment(s) of this element. If slot is supplied, list the group assignment for this element, if any, in slot s.
information
force-node keyword
local
global
property keyword
density
density, ρ
thickness
shell thickness
thermal-expansion
thermal expansion coefficient
anisotropic-membrane
anisotropic membrane material-stiffness coefficients {c'11, c'12, c'13, c'22, c'23, c'33}
anisotropic-bending
anisotropic bending material-stiffness coefficients {c'11, c'12, c'13, c'22, c'23, c'33}
anisotropic-both
anisotropic bending and membrane material-stiffness coefficients {c'11, c'12, c'13, c'22, c'23, c'33}
material-x
vector used to determine local x-direction for the material coordinate system
isotropic
isotropic material properties: E and v, where E is Young’s modulus [F/L2] and v is Poisson’s ratio
orthotropic-membrane
orthootropic membrane material-stiffness coefficients {c'11, c'12, c'22, c'33}
orthotropic-bending
orthotropic membrane material-stiffness coefficients {c'11, c'12, c'22, c'33}
orthotropic-both
resultant <nodes>
all eight stress resultant quantities last calculated with the structure shell recover resultants command. If the nodes keyword is given, the values of these
quantities are supplied at each node of the element, in addition to the value at the element centroid.
stress <nodes>
the stress state calculated with the structure shell recover stress command. If the nodes keyword is given, the values of these quantities are supplied at
each node of the element, in addition to the value at the element centroid.
stress-principal <nodes>
principal stresses calculated with the structure shell recover stress command. If the nodes keyword is given, the values of these quantities are supplied at
system-local
element local coordinate system
structure shell property command

Syntax
structure shell property keyword <range>
Primary keywords:
density | thickness | thermal-expansion | anisotropic-membrane | anisotropic-bending | anisotropic-both | material-x | isotropic | orthotropic-membrane | orthotropic-
bending | orthotropic-both
Assigns a property to elements in the range. The element can have isotropic, orthotropic or anisotropic elastic material properties. The following properties are
available:
density f
density (needed if dynamic mode or gravity is active)
thickness f
shell thickness
thermal-expansion f
anisotropic-membrane f1 f2 f3 f4 f5 f6
anisotropic membrane material properties {c'11, c'12, c'13, c'22, c'23, c'33} [F/L2], which define membrane material-stiffness matrices [E'm] and [E'b],
respectively, in the material directions x', y', z'.
anisotropic-bending f1 f2 f3 f4 f5 f6
anisotropic bending material properties {c'11, c'12, c'13, c'22, c'23, c'33} [F/L2], which define bending material-stiffness matrices [E'm] and [E'b], respectively, in
the material directions x', y', z'.
anisotropic-both f1 f2 f3 f4 f5 f6
anisotropic membrane and bending material properties {c'11, c'12, c'13, c'22, c'23, c'33} [F/L2], which define membrane and bending material-stiffness matrices
[E'm] and [E'b], respectively, in the material directions x', y', z'.
material-x v
Specify the vector (Xx, Xy, Xz) whose projection onto the shell surface defines the x'-axis of the material coordinate system. The material directions correspond
with the principal directions of orthotropy (for more information, see below).
isotropic f1 f2
orthotropic-membrane f1 f2 f3 f4
orthotropic membrane material properties {c'11, c'12, c'22, c'33} [F/L2], which define membrane material-stiffness matrices [E'm] and [E'b], respectively, in the
material directions x', y', z'.
orthotropic-bending f1 f2 f3 f4
orthotropic bending material properties { c'11, c'12, c'22, c'33 } [F/L2], which define bending material-stiffness matrices [ E'm ] and [ E'b ], respectively, in the
orthotropic-both f1 f2 f3 f4
orthotropic membrane and bending material properties {c'11, c'12, c'22, c'33} [F/L2], which define membrane and bending material-stiffness matrices [E'm] and
[E'b], respectively, in the material directions x', y', z'.
Further information on the material-x keyword
The material coordinate system, xʹ, yʹ, zʹ, defines the orthotropic and anisotropic properties and satisfies the following conditions: 1) xʹ is the projection of the
given vector onto the surface; 2) zʹ is normal to the surface and aligned with the z-axis of the shell-type element coordinate system; and 3) yʹ = zʹ × xʹ. The
material coordinate system moves with the shell surface during large-strain updates, which means that the relative orientations of this system and the element
local system do not change (the angle β in this figure does not change). If the material-x vector is not specified, then the xʹ-axis will be aligned with the x-axis of
the structural element local coordinate system.
The material coordinate system can be queried with the command structure shell list property material-x and the FISH function struct.shell.beta.
It can be visualized with the Structural Geometry plot item by choosing the corresponding System attribute.
structure shell recover command

Syntax
structure shell recover keyword <range>
Primary keywords:
resultants | stress | surface
Stress-recovery for shell elements. The stress-recovery procedure can be applied to all elements to compute both the stress resultants and the stresses acting at a
specified depth. The range keyword identifies the patch of elements to which the command will apply. Note that the recovered quantities will depend upon the range of
elements over which these quantities are being recovered, because nodal averaging only occurs for elements within this range.
resultants <range>
recover the eight stress resultants for all elements in the optional range. The stress resultants are expressed in terms of the surface coordinate system. This
command assumes that a consistent surface coordinate system has been established for the group of elements in the range (see the surface keyword). The bending
and membrane stress resultants (Mx, My, Mxy, Nx, Ny, and Nxy) vary linearly over each element, whereas the transverse-shear stress resultants (Qx and Qy ) are
constant over each element. The recovery procedure first computes the average values of bending and membrane stress resultants (by averaging, at the nodes, the
contributions from each element in the range), and then spatially differentiates this average bending field over each element to obtain the transverse-shear stress
resultants.
Stress resultants can be queried after recovery with the command structure shell list resultant and the FISH function struct.shell.resultant. The
validity of the stress resultants for a particular element can be queried with the FISH function struct.shell.resultant.valid.
stress <depth-factor f >
recover a stress tensor (expressed in global coordinate system) at a specified depth in all elements in the optional range. The depth equals v times t/2, where t is
shell thickness. The depth factor, v, must be in the range [-1, +1]. v equal to +1 / -1 corresponds with the outer/inner shell surface (outer surface defined by
positive surface system z-direction), and v equal to zero corresponds with the shell mid-surface. If v is not specified, it defaults to +1.
Stresses are recovered at the three nodal points and centroid of each element. If we designate the shell mid-surface by xy-axes, then 1) stress components σxx,
σyy, and σxy vary linearly over each element, 2) stress components σzy and σzx are constant over each element, and 3) σzz = 0 over each element. The stresses
are derived from the internal element forces (see structure shell list force-node). If the stress resultants are not valid when this command is executed,
then an attempt is first made to recover them. If this attempt fails, then an error message is displayed indicating the problem—usually the inconsistency of the
surface system, which then must be established manually using the structure shell recover surface command (see next keyword).
Stresses and principal stresses can be queried after recovery with the commands structure shell list stress and structure shell list stress-
principal, and with the FISH functions struct.shell.stress and struct.shell.stress.prin. The depth at which these stresses have been recovered can
be queried with the structure shell list depth-factor and the FISH function struct.shell.depth.factor. The validity of the stresses and principal
stresses for a particular element can be queried with the FISH function struct.shell.stress.valid.
surface v
The vector v enables a surface coordinate system to be generated for all nodes used by the elements in the optional range. The surface coordinate system, xʹ yʹ zʹ,
has the following properties: 1) zʹ is normal to the surface; 2) xʹ is the projection of the given vector onto the surface; and 3) yʹ is orthogonal to xʹ and zʹ. The zʹ-
direction is found at each node by taking the average normal direction of all elements in the range. If surface v is aligned with zʹ at any node, then processing
stops and an error message is displayed. To proceed, designate a different v, or restrict the range of elements considered.
The surface coordinate system can be queried with structure shell list system-local and the FISH function struct.node.system.surface. It can also
be set for an individual node with the FISH function struct.node.system.local. It can be visualized with the Shell plot item by choose the corresponding
System attribute.
The surface system at a node automatically becomes invalid under the following conditions: 1) large-strain update; or 2) creation or deletion of a element that
uses the node. Validity must be re-established with the command structure shell recover surface.
structure shell refine command

Syntax
structure shell refine i <range>
This command refines elements in the range by subdividing them by a factor of i. A triangular element refined by i = 2 will yield four triangular elements; i = 3 would
yield 16 triangular elements, etc. The original element is deleted.
structure shell select command

Syntax
structure shell select keyword
Primary keywords:
b | new | undo
if a boolean type is specified, and if on it selects all elements in the range. If off, it de-selects all elements in the range. on is the default if no keyword is given.
new
undo
this will reverse the operation of the last structure shell select command. FLAC3D keeps a maximum undo stack of size 12.
FISH Functions
FISH functions operating on structural shells. The type specifiers used in the FISH function signatures are given in the FISH Type Index section.
Note that all shell functions will also work with both geogrid elements and liner elements.
Structural Shell Functions
struct.shell.area(STRUCT_SHELL_PNT)
Get surface area of the shell-type element.
struct.shell.beta(STRUCT_SHELL_PNT)
Get shell-type material system beta angle.
struct.shell.depth.factor(STRUCT_SHELL_PNT)
Get the depth factor at which stresses have been recovered.
struct.shell.element.type(STRUCT_SHELL_PNT)
Get the name of the finite-element type used by this...
struct.shell.force.nodal(STRUCT_SHELL_PNT,INT<,INT>)
Get the generalized nodal force acting on the shell at...
struct.shell.poisson(STRUCT_SHELL_PNT)
Get/set the Poisson's ratio of the element.
struct.shell.pressure(STRUCT_SHELL_PNT)
Get/set the uniform pressure acting on the shell.
struct.shell.prop.anis(STRUCT_SHELL_PNT,INT,INT)
Get the anisotropic material properties.
struct.shell.prop.ortho(STRUCT_SHELL_PNT,INT,INT)
Get the orthotropic material properties.
struct.shell.prop.type(STRUCT_SHELL_PNT)
Get the material property type.
struct.shell.resultant(STRUCT_SHELL_PNT,INT<,INT>)
Get stress resultants last calculated for the element at the...
struct.shell.resultant.valid(STRUCT_SHELL_PNT)
Get stress resultant validity flag.
struct.shell.stress(STRUCT_SHELL_PNT,INT<,INT<,INT>>)
Get the shell stresses at the current depth factor at...
struct.shell.stress.prin(STRUCT_SHELL_PNT,INT<,INT>)
Get the resolved principal stress at the current depth factor...
struct.shell.stress.valid(STRUCT_SHELL_PNT)
Get the stress validity flag for the element.
struct.shell.thickness(STRUCT_SHELL_PNT)
Get/set the element thickness.
struct.shell.volume(STRUCT_SHELL_PNT)
Get the element volume, or surface area times thickness.
struct.shell.young(STRUCT_SHELL_PNT)
Get/set the Young's modulus of the element.
l struct.shell.area
l struct.shell.beta
l struct.shell.depth.factor
l struct.shell.element.type
l struct.shell.force.nodal
l struct.shell.poisson
l struct.shell.pressure
l struct.shell.prop.anis
l struct.shell.prop.ortho
l struct.shell.prop.type
l struct.shell.resultant
l struct.shell.resultant.valid
l struct.shell.stress
l struct.shell.stress.prin
l struct.shell.stress.valid
l struct.shell.thickness
l struct.shell.volume
l struct.shell.young
struct.shell.area
Syntax
f = struct.shell.area(p)
Returns: f - the surface area of the shell element

Arguments: p - a pointer to a shell element
struct.shell.beta
Syntax
a = struct.shell.beta(p)
Get shell-type material system beta angle. This is defined as the angle between the element local system x-axis and the material system x-axis. In radians measured
counter-clockwise from the element local x-axis.
Returns: f - the shell material system beta angle

struct.shell.depth.factor
Syntax
f = struct.shell.depth.factor(p)
Get the depth factor at which stresses have been recovered. The depth equals Ft/2 where t is the shell element thickness. F values equal to +1.0 or -1.0 correspond to the
outer/inner shell surface. The outer surface is defined by the positive z-direction of the local shell element system. F values of 0.0 corresponds to the shell mid-surface.
The depth factor can be modified with the structure shell recover stress, structure geogrid recover stress, or the structure liner recover stress
commands.
Returns: f - the depth factor at which stresses have been recovered

[URGENT: DR: in above, there was :flag2:-Ft/2-, which has been "corrected". Why was it flagged?]
struct.shell.element.type
Syntax
s = struct.shell.element.type(p)
Get the name of the finite-element type used by this shell-type element.
The possible types for shell-type elements are cst, csth, dkt, dkt-cst, and dkt-csth.
Returns: s - the name of the finite-element type used by this element

struct.shell.force.nodal
Syntax
m = struct.shell.force.nodal(p,inode<,idof>)
Get the generalized nodal force acting on the shell at node index inode.
Returns: m - a 1x6 matrix with the generalized force acting on the element at a node, or a single value of degree-of-freedom idof
inode - the node index to use, from 1 to 3
idof - an optional argument indicating a specific degree-of-freedom, from 1 to 6
struct.shell.poisson
Syntax
f = struct.shell.poisson(p)
struct.shell.poisson(p) = f
Get/set the Poisson's ratio of the element. Modifying the value during cycling may be a danger.
Returns: f - the Poisson's ratio of the element

Accepts: f - the Poisson's ratio of the element
struct.shell.pressure
Syntax
f = struct.shell.pressure(p)
struct.shell.pressure(p) = f
Get/set the uniform pressure acting on the shell. A positive value acts in the z-direction of the element local system.
Returns: f - the uniform pressure acting on the shell

Accepts: f - the uniform pressure acting on the shell
struct.shell.prop.anis
Syntax
f = struct.shell.prop.anis(p,index,itype)
The specific property is identified by the index and the type.
The index must be an integer from 1 to 6 and indicates material-stiffness coefficients {c'11, c'12, c'13, c'22, c'23, c'33}, respectively.
Membrane stiffness is indicated by itype = 1, and bending stiffness is indicated by itype = 2.
If the element does not have anisotropic properties, 0.0 will be returned.
See the structure shell property, structure geogrid property, and structure liner property commands.
Returns: f - the shell anisoptric material stiffness coefficient indicated by index and itype
index - the index of the material stiffness coefficient, from 1 to 6
itype - indicates membrane (1) or bending (2) stiffness
struct.shell.prop.ortho
Syntax
f = struct.shell.prop.ortho(p,index,itype)
The specific property is identified by the index and the type.
The index must be an integer from 1 to 4 and indicates material-stiffness coefficients {c'11, c'12, c'22, c'33}, respectively.
Membrane stiffness is indicated by itype = 1, and bending stiffness is indicated by itype = 2.
If the element does not have orthotropic properties, 0.0 will be returned.
See the structure shell property, structure geogrid property, and structure liner property commands.
Returns: f - the shell orthotropic material stiffness coefficient indicated by index and itype
index - the index of the material stiffness coefficient, from 1 to 4
itype - indicates membrane (1) or bending (2) stiffness
struct.shell.prop.type
Syntax
i = struct.shell.prop.type(p)
This is returned as an integer, with 1 = isotropic, 2 = orthotripc, and 3 = anisotropic.
Returns: i - the material property type, encoded as an integer

struct.shell.resultant
Syntax
m = struct.shell.resultant(p,inode<,ires>)
Get stress resultants last calculated for the element at the location corresponding to node index inode.
inode = 0 indicates the element centroid, while inode = 1 to 3 indicates the positions of the nodes with those indices.
Will return a 1x8 matrix of the stress resultants in this order {Mx, My, Mxy, Nx, Ny, Nxy, Qx, Qy}.
Stress resultants are expressed in the node surface system, see the structure shell recover surface, structure geogrid recover surface, and structure
liner recover surface commands.
If the optional argument ires is provided, then the function will return that specific stress resultant (indexed as the order above) as a single value.
Note that stress resultants must be calculated with the structure shell recover, structure geogrid recover, and structure liner recover command. See
also the struct.shell.resultant.valid function.
Returns: m - a 1x8 matrix of all stress resultants, or a single value of a specific resultant
inode - index of the node location of the resultant, from 0 to 3
ires - an optional argument indicating a specific resultant index, from 1 to 8
struct.shell.resultant.valid
Syntax
b = struct.shell.resultant.valid(p)
true indicates that the stress resultant values are valid. false indicates that resultants have not been calculated or that there has been a change since they were last
calculated that would invalidate the results. See the struct.shell.resultant function.
Returns: b - the stress resultant validity flag

struct.shell.stress
Syntax
Tensor Access
t = struct.shell.stress(p,inode<,i1<,i2>>)
Get the shell stresses at the current depth factor at the location corresponding to index inode.
Stresses are expressed in the global system. Note that compressive stresses are negative in FLAC3D.
See the structure shell recover stress, structure geogrid recover stress, and structure shell recover stress commands. See also the
struct.shell.stress.valid and struct.shell.stress.prin functions.
Returns: t - recovered element stress tensor, or a specific component of that tensor

inode - index of the location of the resultant, from 0 to 3
i1 - optional tensor indice that, if given without i2, ranges from 1 to 6, accessing the xx, yy, zz, xy, xz, and yz tensor values
i2 - optional tensor notation that must be given with i1. In this case, i1 corresponds to the first indice of the tensor position and i2 to the second in the
row/column format. For instance, i1 = 1 and i2 = 3 return the xz tensor value.
Value Access
f = struct.shell.stress.xx(p,inode)
Get the xx-value of the recovered element stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - xx-value of the recovered element stress tensor

Arguments: p - zone pointer
f = struct.shell.stress.xy(p,inode)
Get the xy-value of the recovered element stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - xy-value of the recovered element stress tensor

f = struct.shell.stress.xz(p,inode)
Get the xz-value of the recovered element stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - xz-value of the recovered element stress tensor

f = struct.shell.stress.yy(p,inode)
Get the yy-value of the recovered element stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - yy-value of the recovered element stress tensor

f = struct.shell.stress.yz(p,inode)
Get the yz-value of the recovered element stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - yz-value of the recovered element stress tensor
f = struct.shell.stress.zz(p,inode)
Get the zz-value of the recovered element stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - zz-value of the recovered element stress tensor

struct.shell.stress.prin
Syntax
Vector Access
v = struct.shell.stress.prin(p,inode<,i>)
Get the resolved principal stress at the current depth factor and position given by inode.
Returns a vector encoded as (minimum, intermediate, maximum), unless an optional component argument i is supplied, in which case it returns the component value.
Note that compressive stresses are negative in FLAC3D.

Arguments: p - a shell element pointer
Component Access
f = struct.shell.stress.prin.x(p,inode)
Get the x-component principal stress vector. This is the minimum (most negative) principal stress.

f = struct.shell.stress.prin.y(p,inode)
Get the y-component principal stress vector. This is the intermediate principal stress.

f = struct.shell.stress.prin.z(p,inode)
Get the z-component principal stress vector. This is the maximum (most positive) principal stress.

struct.shell.stress.valid
Syntax
b = struct.shell.stress.valid(p)
Get the stress validity flag for the element. true indicates that the stresses last calculated at the current depth factor are valid. false indicates that stresses have not been
calculated, or that there has been a change that invalidates the last stresses calculated. See the struct.shell.stress function.
Returns: b - the stress validity flag

struct.shell.thickness
Syntax
f = struct.shell.thickness(p)
struct.shell.thickness(p) = f
Returns: f - the element thickness

Accepts: f - the element thickness
struct.shell.volume
Syntax
f = struct.shell.volume(p)
Returns: f - the element volume

struct.shell.young
Syntax
f = struct.shell.young(p)
struct.shell.young(p) = f
Get/set the Young's modulus of the element. Modifying the value during cycling may be a danger.
Returns: f - the Young's modulus of the element

Accepts: f - the Young's modulus of the element
Geogrid Structural Elements

Mechanical Behavior
The mechanical behavior of each geogrid element can be divided into the structural response of the geogrid material itself (see Shell-Type Mechanical Behavior) and the way
in which the geogrid element interacts with the FLAC3D grid. By default, geogrid elements are assigned the CST plane-stress element that resists membrane but does not
resist bending loading (see Shell Finite Elements). A membrane structure can be modeled as a collection of geogrid elements. The geogrid behaves as an isotropic or
orthotropic, linear elastic material with no failure limit. A shear-directed (in the tangent plane to the geogrid surface) frictional interaction occurs between the geogrid and the
FLAC3D grid, and the geogrid is slaved to the grid motion in the normal direction. The geogrid can be thought of as the two-dimensional analog of a one-dimensional cable.
Geogrids are used to model flexible membranes whose shear interaction with the soil are important, such as geotextiles and geogrids.
The orientation of the node-local system for all nodes used by geogrid elements is set automatically at the start of a set of cycles (or when the model cycle 0 command is
x
executed), such that the -axis is aligned with the average normal direction of all geogrid elements using the node, and the -axes are arbitrarily oriented in the
geogrid tangent plane (see Figure 2).
A geogrid is embedded in the interior of the FLAC3D grid. The behavior at the geogrid-soil interface is summarized in Figures 1 to 2. The stresses acting on the geogrid are
\sig \
shown in Figure 1. These stresses, consisting of an effective confining stress, , and a total shear stress, t, are balanced by the membrane stresses that
\
develop within the geogrid itself. These membrane stress resultants (see Stresses in Shells) are denoted by b in Figure 1. The interface behavior is represented
numerically at each geogrid node by a rigid attachment in the normal direction and a spring-slider in the tangent plane to the geogrid surface. The orientation of the spring-
{\bf
slider changes in response to relative shear displacement u} between the geogrid and the host medium, as shown in Figure 2. The fact that there is only a single
spring slider at each node makes the geogrid behave in a fashion similar to a coarse mesh of cross-linked bars. The spring-slider carries the total shear force acting over the
tributary area on both sides of the geogrid surface. Also, the effective confining stress is assumed to be acting equally on both sides of the geogrid surface.
../../../../../../_images/stresse
Figure 1: Stresses acting on the geogrid elements surrounding a node
../../../../../../_images/interface-
idealization.png
Figure 2: Idealization of interface behavior at a geogrid node
The normal behavior of the geogrid-soil interface is described below. The shear behavior of the geogrid-soil interface (see Figure 3) is cohesive and frictional in nature, and is
\
controlled by the coupling spring properties of (1) stiffness per unit area, , (2) cohesive strength, , (3) friction angle, , and (4) effective confining stress,
\sig
ma_ . Note that the coupling-spring properties associated with each geogrid element are averaged at geogrid nodes.
\sig
The effective confining stress, ma_ , acts perpendicular to the geogrid surface, and is computed at each geogrid node, based on the stress acting in the single zone to
z \sig
which the node is linked. Denote the geogrid surface normal direction as . The value of is taken as
\sigma_m = \sigma_
{zz} + p
where = pore pressure
behavior.png
Figure 3: Shear-directional interface behavior for geogrid elements
In computing the relative displacement at the geogrid-soil interface, an interpolation scheme is used to calculate the grid displacement, based on the displacement field in the
zone to which the node is linked. The interpolation scheme uses weighting factors that are determined by the distance to each of the zone gridpoints. The same interpolation
scheme is used to apply forces developed in the geogrid-soil interface back to the gridpoints of the zone.
As explained above, an interpolated estimate of grid velocity is made at each geogrid node. The velocity normal to the geogrid surface is transferred directly to the node (i.e.,
the geogrid node is slaved to the grid motion in the normal direction). The node exerts no normal force on the grid if all the geogrid elements that share the node are coplanar;
however, if they are not coplanar, then a proportion of their membrane force will act in the normal direction. This net force acts both on the grid and on the geogrid node (in
opposite directions). Thus, an initially flat geogrid can sustain normal loading if it is allowed finite deflection, using the large-strain solution mode. This normal force is
transferred to the gridpoints of the single zone to which the node is attached. The attachment is to only one zone on one side of the geogrid surface, and this side may not
correspond with the side going into compression. There is no provision for the formation or tracking of gaps between the geogrid and the soil (i.e., the geogrid is assumed to
be fully embedded within the soil at all times).
Geogrids support large-strain sliding (by setting the slide property to on), whereby the interpolation locations (used by the geogrid nodes to transfer forces and velocities to
and from the zones — see Structural Element Links) will migrate through the grid when running in large-strain mode. This allows one to calculate the large-strain, post-failure
behavior of a geogrid, whereby substantial sliding between the geogrid nodes and the zones occurs. If a geogrid node moves out of all zones, then a connection with the zones
will not be reestablished if the node is later moved back into zones; however, the connection remains intact as the geogrid nodes slide between zones.
Response Quantities
Geogrid responses include stresses in the geogrid itself, as well as stress, displacement and yield state in the shear coupling springs. Additional coupling-spring information
includes the current loading direction and the effective confining stress. The geogrid responses can be accessed via FISH, and
1. printed with the structure geogrid list command,

2. monitored with the structure geogrid history command, and
3. plotted with the Geogrid plot item.
Refer to Shell-Type Response Quantities for a summary of the commands that support recovery of stresses acting in the geogrid itself.
Properties
Each geogrid element possesses 5 properties in addition to those common to all shell-type elements described in Shell-Type Properties. These properties control the shear
behavior of the geogrid-soil interface.
c
5. coupling-cohesion-shear, coupling spring cohesion (stress units), [F/L2]
6. coupling-friction-shear, coupling spring friction angle, [degrees]
7. copling-stiffness-shear, coupling spring stiffness per unit area, [F/L3]

l Simple Test of Geogrid-Soil Interface Behavior
l Geogrid Pull-out Test
l Geogrid-Reinforced Embankment
A complete list of examples that use geogrid elements is available in Structural Geogrid Examples.
Commands & FISH

l Commands
l FISH Functions
Simple Test of Geogrid-Soil Interface Behavior

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Geogrid/SoilInterfaceTest" and select "SoilInterfaceTest.f3prj" to load. The
A geogrid is embedded in a soil block and then pulled out of the block. The soil is represented by a single zone, and the geogrid is represented by a single geogrid element.
The shear stress and shear displacement of one of the coupling springs is monitored and plotted to demonstrate the effects of the geogrid-soil interface properties on system
response.
The FLAC3D model consists of one geogrid element embedded in one zone, as shown in Figure 1. The geogrid is initially created, using the structure geogrid create
by-triangle command, to be a single triangle embedded in the zone. The zone is assigned elastic properties, and is fully fixed in all directions. The geogrid is assigned
isotropic material properties and a thickness, and a constant velocity of 1 × 10-6 m/step in the global x-direction is applied to all geogrid nodes. The shear stress and total shear
displacement in a coupling spring are monitored using the structure geogrid history command. The geogrid-soil interface properties are then varied to demonstrate their
effects on the system behavior.
../../../../../_images/soilinterface-system.png
Figure 1: FLAC3D model for simple test of geogrid-soil interface behavior.
The shear stress versus total shear displacement for the two cases is shown in Figure 2. The peak shear stress is given by (see Shear-directional interface behavior for geogrid
elements)
\tau_{\rm max} = c + \sigma_m

\tan\phi
where: = coupling spring cohesion;
\sig = effective confining stress; and
= coupling spring friction angle.
For the initial properties specified, the case with zero and 1.73 kPa confining stress give expected peak shear stresses of 4 and 5 kPa, respectively. The effect of the specified
confinement is to raise the response plots by 1 kPa, and this is what is found. Also, the slope of these curves equals the coupling spring stiffness per unit area (structure
geogrid property coupling-stiffness). When any of the geogrid properties are modified, the system responds accordingly.
../../../../../_images/soilinterface-chart.png
Figure 2: Shear stress versus total shear displacement (unconfined and confining stress of 1.73 kPa).
Data File
SoilInterfaceTest.f3dat
model new
model title "Simple Test of Geogrid-Soil Interface Behavior"
; Test case 1, confining stress = 0
[global confiningStress = 0]
call 'PerformTest'
history export 1 vs 2 table 'unconfined'
model save 'SoilInterfaceTest0'
; Reset
zone delete
struct geogrid delete
history delete
; Test case 2, confining stress = -1.73e3
[confiningStress = -1.73e3]
call 'PerformTest'
history export 1 vs 2 table 'confined'
model save 'SoilInterfaceTest173'
PerformTest.f3dat
; One zone test

zone create brick size=(1,1,1)

zone cmodel assign elastic ; for the rock, sandy shale
zone property bulk=3.33e9 she=2.5e9 ; for the rock, E=6 GPa, nu=0.2
; Initialize confining stress
zone initialize stress-yy=@confiningStress ; apply confining stress, zero or -1.73e3
; Fix all zone gridpoints
zone gridpoint fix velocity
; Create triangular geogrid, and assign properties
struct geogrid create by-triangle (0,0.5,0) (1,0.5,0) (1,0.5,1)
struct geogrid property thickness=0.1 isotropic=( 20e9, 0.2) ...
coupling-stiffness=2.3e6 coupling-cohesion=4e3 ...
coupling-friction=30.0
; Take some histories
struct geogrid history coupling-stress position (0.5,0.5,0.3)
struct geogrid history coupling-displacement position (0.5,0.5,0.3)
; Fix structural node velocities
struct node fix velocity
struct node initialize velocity-x 1e-6 local
; Cycle
model cycle 3000 ; 3e-3 total displacement
; Update coupling properties
struct geogrid property coupling-cohesion=6e3 coupling-stiffness=1.3e6
model cycle 2000 ; 5e-3 total displacement
; Update coupling properties
struct geogrid property coupling-cohesion=5e3
model cycle 500 ; 5.5e-3 total displacement
Geogrid Pull-out Test

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Geogrid/PullOutTest" and select "PullOutTest.f3prj" to load. The main data
A geosynthetic sheet is embedded in a box of soil and then pulled out of the soil, as shown in Figure 1. The total pull-out force and displacement are monitored and plotted.
The test is performed for different values of confining stress. This example provides guidance in selecting geogrid properties, and demonstrates the shear response of the
geogrid-soil system. It makes use of properties described in Beneito and Gotteland (2001).
../../../../../_images/pullout-
diagram.png
Figure 1: Geogrid pull-out test configuration.
E \ E \
It is assumed that both the soil ( = 15 MPa, = 0.3, = 1950 kg/m3) and the geogrid ( = 26 GPa, = 0.33, = 5 mm) remain elastic, and
c \
that all failure occurs at the geogrid-soil interface. The interface properties ( , , ) are estimated as follows.
k
It is assumed that a set of pull-out tests have been performed at different confining pressures. The value of is set equal to the slope of the pull-out stress versus
displacement plot. In Beneito and Gotteland (2001), this slope increases for increasing confinement. For our purposes, the slope for a confinement of 39 kPa (which
corresponds with the weight of the soil above the geogrid) is matched by setting
k = {\Delta S \over \Delta U} = {23\hbox{ kPa} \over 10\hbox{ mm}} = 2.3\times10^6\hbox

(1) { N/m$^3$}
where: = pull-out stress (pull-out force/(embedded geogrid area)); and
= pull-out displacement.
\ \ta
The values of and are found from a plot of maximum pull-out force versus confinement. The slope of this curve equals n\ , and the y-intercept equals
. In Beneito and Gotteland (2001), the cohesion is zero, and the maximum pull-out stress for confinements of 100 and 25 kPa is 54 and 12 kPa, respectively. For our
purposes, these data are matched by setting
c
&
\phi &= \tan^{-1}\left( {54 - 12 \over 100 - 25} \right) = 29.2\hbox

(2) { degrees}
The FLAC3D model consists of 60 geogrid elements and 250 zones, as shown in Figure 2. The grid is customized for the test using the Extruder tool, and the data file is
exported from the State pane. The modeling sequence then proceeds as follows. Begin with a stress-free soil, fix the sides and bottom of the box, install the geogrid, activate
gravity, apply a constant pressure to the top surface (in the initial run, this pressure is zero) and use the zone initialize-stresses command to reach equilibrium. At this
stage, the sides and bottom of the box are being compressed by the soil, and a confining stress of 39 kPa is acting on the geogrid surface.
../../../../../_images/pullout-geom.png
Figure 2: FLAC3D model for geogrid pull-out test.
The pull-out test is performed by applying a constant horizontal velocity to the geogrid nodes along the box front. These nodal velocities are fixed in the geogrid plane (which
corresponds with the node-local xy-axes — see the structure node initialize command), and then specify a velocity in the global x-direction. During the test, the
applied displacement and force are monitored. The applied force is equal to the total out-of-balance force acting on the geogrid nodes along the box front (computed with the
pullOutStress FISH function), and the pull-out stress equals this force divided by the embedded geogrid area. Also monitored is the total shear displacement in the six
coupling springs along the geogrid centerline at 0.5 m intervals from front to back, and the coupling stress in the front node. (The locations of the history monitoring points
are shown in Figure 2).
The pull-out stress versus applied displacement is shown in Figure 3 for the case in which no pressure is applied to the top surface. An applied displacement of approximately
10 mm is necessary to mobilize all of the frictional resistance of the geogrid. During this test, the effective confining stress acting on the geogrid surface is equal to 39 kPa.
For this value of confinement, and for the geogrid interface properties specified, the maximum shear stress should equal 21.8 kPa. The value obtained is 21.6 kPa, which
matches the theoretical value. Also, the slope of this curve equals the coupling spring stiffness (see equation (1)).
Figure 3 also compares the evolution of the shear stress acting in the coupling spring at the front face with the pull-out shear stress. It is found that the front coupling spring
yields before the overall system yields. This is to be expected, because the yielded region begins at the front face and then propagates back into the soil block. Also found is
that the maximum stress in the coupling spring slightly exceeds that of the overall system (22.19 kPa versus 21.6 kPa). Also, the effective confining stress acting on the
coupling spring at the front face (structure geogrid list coupling range component-id 57) equals 40.03 kPa, which is slightly more than the average value of 39 kPa
acting on the entire geogrid. Figure 3 illustrates the difference between the local response at a geogrid node and the global response of the entire geogrid system. In the entire
system, the effective confining stress differs over different parts of the geogrid because of boundary effects from the box walls.
../../../../../_images/pullout-couplinghist.png
Figure 3: Pull-out shear stress and coupling spring stress at versus applied displacement (no pressure applied to top surface).
U
In Figure 4, the geogrid displacements, , are plotted at the locations (from Figure 1) versus the applied displacement over the range from 9 to 12 mm.
In this plot, the histories 10-15 correspond with the points - , respectively. Observe the phenomenon of progressive mobilization of the geogrid as the yielded
region progresses inward from the front face. The equal slopes indicate that all points are moving at the same rate as the front face, and the offsets demonstrate that the front
points have moved farther than the back points (also see Figure 5). The very small offset occurs because the geogrid is much stiffer than the surrounding soil, such that very
little strain develops in the geogrid itself prior to yielding.
../../../../../_images/pullout-disphist.png
Figure 4: Displacements along geogrid centerline versus applied displacement (no pressure applied to top surface).
../../../../../_images/pullout-disp.png
Figure 5: Geogrid displacement field ( = 12 mm; no pressure applied to top surface).
N
At an applied displacement of 30 mm, the shear stresses acting on the geogrid are examined (see Figure 6) as well as the membrane stress resultant, (where the x-
direction is parallel with the global x-direction), acting within the geogrid (see Figure 7). In Figure 8, the yield state of the coupling springs is overlayed. First, note that all of
the coupling springs are yielding. The shear stresses acting on the geogrid have reached a constant maximum value that ranges from 21.2 to 22.2 kPa over the geogrid surface.
The value is largest at the front face, and slightly lower at the far end. The membrane stress resultant acting within the geogrid is largest at the front face (53.7 kN/m), and
declines as one moves away from the face. This occurs because more load is transferred to the soil as one moves away from the front face. The membrane stress is constant
across the geogrid width; thus, the stress in the global x-direction at the mid-surface can be estimated by dividing the value of by the geogrid thickness to yield 10.7
MPa, which is what is seen in the contour plot in Figure 8. The actual xx-stress in a geogrid element adjacent to the front face is found to be 10.01 MPa.
../../../../../_images/pullout-shear.png
Figure 6: Shear stresses acting on the geogrid ( = 12 mm; no pressure applied to top surface).
../../../../../_images/pullout-nx.png
N
Figure 7: Membrane stress resultant acting within the geogrid ( = 12 mm; no pressure applied to top surface).
../../../../../_images/pullout-sxx.png
Figure 8: xx-stress acting within the geogrid ( = 12 mm; no pressure applied to top surface).
The simulation is rerun with an applied pressure of 61 kPa on the top surface. This increases the geogrid confinement to 100 kPa, which corresponds with the laboratory data
used in equation (2), and for which the expected maximum pull-out stress is 54 kPa. The computed value equals 55.4 kPa (see Figure 9).
../../../../../_images/pullout-couplinghist2.png
Figure 9: Pull-out shear stress versus applied displacement (pressure of 61 kPa applied to top surface).
Reference
Beneito, C. and Ph. Gotteland. "Three-Dimensional Numerical Modeling of Geosynthetics Mechanical Behavior," in FLAC and Numerical Modeling in Geomechanics
(Proceedings of the Second International FLAC Symposium on Numerical Modeling in Geomechanics, Lyon, France, 29-31 October 2001). D. Billaux et al., eds. Lisse:
Balkema (2001).
Data File
PullOutTest.f3dat
model new
model title "Geogrid Pull-Out Test"
; Zones created interactively using Extruder, exported to State Pane
call 'geometry' suppress
zone generate from-extruder
; Assign zone model and properties
zone property bulk=12.5e6 shear=5.77e6 density=1950. ; E=15 MPa, nu=0.3
; Create the geogrid, embedded in the zone, and assign properties
struct geogrid create by-quadrilateral (0,0.45,0.5) (2.5,0.45,0.5) (2.5,1.05,0.5) (0,1.05,0.5) size (10,3)
struct geogrid property isotropic=(26e9, 0.33) thickness=5e-3 ...

coupling-stiffness=2.3e6 coupling-cohesion=0.0 ...
coupling-friction=29
; Tag nodes on front
struct node group 'Front' range position-x 2.5
; Init globals and solve
model gravity 10
zone initialize-stresses ratio 0.3
history interval 1
call 'PullOutStress' ; FISH function to calculate pull out stress
struct node fix velocity-x range group 'Front' ; fix velocity in geogrid plane
struct node fix velocity-y range group 'Front' ; (node-local xy-axes)
struct node initialize velocity-x 2e-6 local range group 'Front'
struct node initialize displacement (0,0,0)
struct node initialize displacement-rotational (0,0,0) ; reset nodal displ.
; Nodal displacement histories
struct node history name='dp0' displacement-x position (2.5,0.65,0.5)
struct node history name='dp5' displacement-x position ( 0,0.65,0.5)
fish history name='stress' @pullOutStress
struct geogrid history name='cs' coupling-stress component-id 57 node 2
; Setup model damping
;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; No pressure applied to top surface
model cycle 15000
model save 'Pressure-0k'
;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; 61kPa pressure applied to top surface
zone face apply stress-zz -61e3 range group 'Top'
zone initialize-stresses ratio 0.3 overburden -61e3
model cycle 15000
model save 'Pressure-61k'
Geogrid-Reinforced Embankment
Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ? Examples.... Choose "Structure/Geogrid/ReinforcedEmbankment" and select "RinforcedEmbankment.f3prj"
to load. The main data files used are shown at the end of this example. The remaining data files can be found in the project.
This example illustrates the behavior of a soil embankment reinforced with three geogrid layers. It is similar to the Soil Nailing example, wherein cables are used to reinforce
the embankment. Three geogrids are installed at different levels in a vertical embankment. There is assumed to be no cohesive resistance between the geogrids and the soil.
The friction angle of the geogrid-soil interface necessary to stabilize the embankment is determined.
The FLAC3D model consists of 48 geogrid elements and 121 zones, as shown in Figure 1. The model simulates a one-meter wide section of soil subjected to plane-strain
conditions (no out-of-plane motion). During the construction of the actual embankment, the soil would have been added gradually with each geogrid layer being emplaced and
then covered with soil. Instead, simply emplace all three geogrid layers into a stress-free soil, and then install the soil in-situ stresses that correspond with the soil weight. At
this stage, each geogrid layer is subjected to a different confining stress that increases with depth. The embankment is now created by removing the constraint on the left side
of the model and cycle until either equilibrium is reestablished or it becomes clear that the embankment is collapsing.
../../../../../_images/embankment-geom.png
Figure 1: FLAC3D model for geogrid-reinforced embankment.
The soil is modeled as a Mohr-Coulomb material and assigned the same properties as in Soil Nailing. Geogrids in FLAC3D remain elastic; failure can occur in the geogrid-
\ t
soil interface and/or in the soil zones. The geogrid is assigned the same properties as in Geogrid Pull-out Test ( = 26 GPa, = 0.33, = 5 mm, = 2.3
N/m3, = 0), and the friction angle is varied.
For a geogrid-soil interface friction angle of 0 degrees, the shear resistance of the geogrid is not mobilized, and the soil itself does not have sufficient strength to prevent the
collapse of the embankment. Figure 2 shows that the geogrids are carrying no load, and that the slip condition has been reached at all geogrid nodes. A plot of the x-
displacement of the top-left gridpoint (see Figure 3) indicates that the embankment is collapsing.
../../../../../_images/embankment-result0.png
Figure 2: Tensile stress in geogrids with geogrid-soil interface friction angle of zero (the embankment is collapsing).
../../../../../_images/embankment-xdisp0.png
Figure 3: Total x-displacement of top-left gridpoint with geogrid-soil interface friction angle of zero (the embankment is collapsing).
By including a frictional resistance at the geogrid-soil interface of 5°, the geogrids are sufficient to stabilize the embankment (see Figure 4). Figure 5 plots the tensile stress in
the geogrids for this case. The top geogrid layer has slipped and transferred load to the lower layers. The displacement field of the soil and the geogrids is shown in Figure 6.
The counterclockwise rotation of the system and the decrease in pull-out deformation with depth are evident in this plot.
../../../../../_images/embankment-xdisp5.png
Figure 4: Total x-displacement of top-left gridpoint with geogrid-soil interface friction angle of 5° (the embankment is stable).
../../../../../_images/embankment-result5.png
Figure 5: Tensile stress in geogrids with geogrid-soil interface friction angle of 5° (the embankment is stable).
../../../../../_images/embankment-disp5.png
Figure 6: Displacement field in soil and geogrids with geogrid-soil interface friction angle of 5° (the embankment is stable).
Data File
ReinforcedEmbankment.f3dat
model new
model title "Reinforced embankment (using geogrids)"
; Create soil and assign properties
zone face skin ; Label zone boundaries
zone property bulk 5e9 shear 1e9 cohesion 4e4 friction 30 density 2000
; Create three geogrid layers, and assign properties
struct geogrid create by-quadrilateral (0,0,9.5) (8,0,9.5) (8,1,9.5) (0,1,9.5) size (8,1)
struct geogrid property isotropic=(26e9, 0.33) thick=5e-3 ...
coupling-stiffness=2.3e6 coupling-cohesion=0.0 ...
coupling-friction=0 ; 0 coupling friction!
zone face apply velocity (0,0,0) range group 'Bottom'
model gravity 10
model solve convergence 1
; Histories
zone history name='disp' displacement-x position (0,0,11)
; Case 1 - coupling friction 0

; Remove constraint on left side of model.
; Solve, but stop after 5000 because we expect failure
model solve convergence 1 cycles 5000
model save 'Friction-0'
; Case 2 - coupling friction 5 degrees

struct geogrid property coupling-friction=5
; Remove constraint on left side of model.
; Solve
model save 'Friction-5'
Commands
Operations on structural element geogrids.
Geogrid elements do not support moments. They are, by default, rigidly connected to their surroundings in the direction normal to the element and deformably connected in
the two directions parallel to the element plane.
Structural Element Geogrid Commands
structure geogrid apply

Assign uniform applied pressure f to all geogrid elements in...
structure geogrid create
Create a geogrid.
structure geogrid delete
Delete all geogrid elements in the range.
structure geogrid group
Assign all geogrid elements in the range to the group...
structure geogrid hide
This commands hides or un-hides all geogrid elements in the...
structure geogrid history
Sample geogrid responses.
structure geogrid import
Create geogrid elements from an outside source.
structure geogrid initialize
structure geogrid list
List properties and response of each geogrid element in the...
structure geogrid property
structure geogrid recover
Stress-recovery for geogrid elements.
structure geogrid refine
structure geogrid select
l structure geogrid apply command

l structure geogrid create command
l structure geogrid delete command
l structure geogrid group command
l structure geogrid hide command
l structure geogrid history command
l structure geogrid import command
l structure geogrid initialize command
l structure geogrid list command
l structure geogrid property command
l structure geogrid recover command
l structure geogrid refine command
l structure geogrid select command
structure geogrid apply command

Syntax
structure geogrid apply f <range>
Assign uniform applied pressure f to all geogrid elements in the range. Positive pressure acts in the positive z-direction of the element system and maintains this
orientation during large-strain motion.
structure geogrid create command

Syntax
structure geogrid create keyword
Primary keywords:
Create a geogrid. The four main keywords articulate four different techniques of creation: by creating a collection of elements from a group of zone faces (by-face); by
creating a single element from four existing nodes (by-nodeids); from a specified quadrilateral (by-quadrilateral); or from a triangle (by-triangle).
Create new elements that are attached to the set of three- or four-sided zone-faces in the range. By default, only surface faces will be considered, the internal
will be ordered counterclockwise with respect to the outside of the specified zone faces, thereby making the element z-axis point outward. The element will be
Create elements given an existing set of nodes. The new elements will not be attached to the grid. If you wish to attach it to the grid, then after creating it, position
moved into a zone).
Create elements based on four points forming a quadrilateral, in order. The element local system will point in the opposite direction determined by using the right-
hand rule. The new elements will not be attached to the grid. If you wish to attach it to the grid, then after creating it, position its nodes with the structure node
The new elements will not be attached to the grid. If you wish to attach it to the grid, then after creating it, position its nodes with the structure node
Keyword Block
The following keywords may be optionally provided on geogrid creation using any of the major keywords: by-face, by-nodeids, by-quadrilateral and by-
triangle.
distinct
id i
group s1 <slot s2 >
cross-diagonal 
structural elements is printed by the structure geogrid list element-type command. The value of the keyword supplied must be one of the following
three-noded finite elements.
Attempt to match the string s to one of the available keywords below, and treats as that option.
cst
csth
dkt
dkt-cst
membrane loading.
dkt-csth
internal
maximum-length f
segments i
size i1 i2
structure geogrid delete command

Syntax
structure geogrid delete <range>
Delete all geogrid elements in the range. Structure nodes and links that become disconnected from any element will automatically be deleted as well.
structure geogrid group command

Syntax
structure geogrid group s1 <slot s2 >
Primary keywords:
slot | remove
Assign all geogrid elements in the range to the group with the name s. Use of the group logic is described in Group. Any element may only belong to one group in a
given slot. Assigning an element to a new group in that slot will cause it to be removed from its current group assignment. The command structure geogrid list
group command lists the existing element group names. The groups can be visualized with the geogrid plot item.
slot s
remove
structure geogrid hide command

Syntax
structure geogrid hide keyword
Primary keywords:
b | undo
This commands hides or un-hides all geogrid elements in the range. By default, commands that use a range filter will skip hidden objects. This can be overruled with the
undo
this will reverse the operation of the last structure geogrid hide command. FLAC3D keeps a maximum undo stack of size 12.
structure geogrid history command

Syntax
structure geogrid history keyword
Primary keywords:
coupling-displacement | coupling-stress | coupling-yield | force | force-x | force-y | force-z | moment | moment-x | moment-y | moment-z | resultant-mx | resultant-my |
resultant-mxy | resultant-nx | resultant-ny | resultant-nxy | resultant-qx | resultant-qy | principal-intermediate | principal-maximum | principal-minimum | stress-xx |
stress-xy | stress-xz | stress-yy | stress-yz | stress-zz
Sample geogrid responses. The nodes of an element will be ordered counterclockwise with respect to the outside of the zone faces upon which the geogrid was created.
The element to be sampled must be identified by either component-id or by position. If position v is used, the element nearest to v is taken.
For some history types, the node of the element to be sampled may be specified optionally with the keyword node i (where i = 1, 2, or 3). If node is omitted, node 1 is
used by default.
structure geogrid recover surface command is invoked using that vector for the specified element. Surface-X v is required for these histories.
surface.
coupling-displacement [keywordblock]
displacement magnitude (always positive) in coupling springs at the node of the element. This option uses the node keyword.
coupling-stress [keywordblock]
stress magnitude (always positive) in coupling spring at the node of the element. This option uses the node keyword.
coupling-yield [keywordblock]
yield state in coupling spring at the node of the element. Value {0, 1, 2} denotes never yielded, now yielding, or yielded in the past, respectively. This option uses
the node keyword.
force magnitude, global system. This option uses the node keyword.
nodal force (x-component, global system). This option uses the node keyword.
nodal force (y-component, global system). This option uses the node keyword.
nodal force (z-component, global system). This option uses the node keyword.
moment magnitude, global system. This option uses the node keyword.
nodal moment (x-component, global system). This option uses the node keyword.
nodal moment (y-component, global system). This option uses the node keyword.
nodal moment (z-component, global system). This option uses the node keyword.
stress resultant Mx in the element surface system. This option uses the surface-x keyword.
stress resultant My in the element surface system. This option uses the surface-x keyword.
stress resultant Mxy in the element surface system. This option uses the surface-x keyword.
stress resultant Nx in the element surface system. This option uses the surface-x keyword.
stress resultant Ny in the element surface system. This option uses the surface-x keyword.
stress resultant Nxy in the element surface system. This option uses the surface-x keyword.
stress resultant Qx in the element surface system. This option uses the surface-x keyword.
stress resultant Qy in the element surface system. This option uses the surface-x keyword.
principal intermediate stress, global system. This option uses the depth-factor keyword.
principal maximum stress, global system. This option uses the depth-factor keyword.
principal minimum stress, global system. This option uses the depth-factor keyword.
stress xx-component, global system. This option uses the depth-factor keyword.
stress xy-component, global system. This option uses the depth-factor keyword.
stress xz-component, global system. This option uses the depth-factor keyword.
stress yy-component, global system. This option uses the depth-factor keyword.
stress yz-component, global system. This option uses the depth-factor keyword.
stress zz-component, global system. This option uses the depth-factor keyword.
Keyword Block
The following keywords are available to control the location and other details of the history. Some keywords are only available if noted. coupling-
displacement, coupling-stress, coupling-yield, force, force-x, force-y, force-z, moment, moment-x, moment-y, moment-z, principal-
intermediate, principal-maximum, principal-minimum, resultant-mx, resultant-mxy, resultant-my, resultant-nx, resultant-nxy, resultant-ny,
resultant-qx, resultant-qy, stress-xx, stress-xy, stress-xz, stress-yy, stress-yz and stress-zz.
component-id i
depth-factor f
node i
position v
surface-x v
structure geogrid import command

Syntax
structure geogrid import keyword
Primary keywords:
Keyword Block
Any of the following keywords may be optionally supplied for use with the major keywords of structure geogrid import: from-file and from-geometry.
id i
group s1 <slot s2 >
cross-diagonal 
distinct
structural elements is printed by the structure geogrid list element-type command. The value of the keyword supplied must be one of the following
cst
csth
dkt
dkt-cst
membrane loading.
dkt-csth
internal
maximum-length f
segments i
structure geogrid initialize command

Syntax
structure geogrid initialize <keyword>
Primary keywords:
coupling
coupling
structure geogrid list command

Syntax
structure geogrid list keyword <range>
Primary keywords:
apply | coupling | depth-factor | element-type | group | information | force-node | property | resultant | stress | stress-principal | system-local
List properties and response of each geogrid element in the range.
apply
coupling
Information about the shear coupling springs connecting the liner to the zones. The confining stress, displacement, yield state, and direction is given.
depth-factor
element-type
group <slot s >
information
Lists general element information, including id and component-id numbers, connected nodes, centroids, surface area, volume, and the hide and select status.
force-node keyword
List nodal forces. By default, components are displayed in terms of the element local coordinate systems. These are the forces exerted by the nodes on the
element.
local
List forces in terms of the element local coordinate system (the default).
global
List forces in terms of the global coordinate system.
property
density
density, ρ
thickness
geogrid thickness
thermal-expansion
anisotropic membrane material-stiffness coefficients { cʹ11, cʹ12, cʹ13, cʹ22, cʹ23, cʹ33 }
anisotropic-bending
anisotropic bending material-stiffness coefficients { cʹ11, cʹ12, cʹ13, cʹ22, cʹ23, cʹ33 }
anisotropic-both
anisotropic bending and membrane material-stiffness coefficients { cʹ11, cʹ12, cʹ13, cʹ22, cʹ23, cʹ33 }
material-x
Vector used to determine the local X direction of the material coordinate system.
isotropic
orthotropic membrane material-stiffness coefficients { cʹ11, cʹ12, cʹ22, cʹ33 }
orthotropic-bending
orthotropic-both
coupling-cohesion
coupling spring cohesion (stress units)
coupling-friction
coupling spring friction angle (degrees)
coupling-stiffness
coupling spring stiffness per unit area
slide
large-strain sliding flag
slide-tolerance
large-strain sliding tolerance
resultant <nodes>
all eight stress resultant quantities last calculated with the structure geogrid recover resultants command. If the nodes keyword is given the values of
these quantities is supplied at each node of the element, in addition to the value at the element centroid.
stress <nodes>
the stress state calculated with the structure geogrid recover stress command. If the nodes keyword is given the values of these quantities is supplied at
principal stresses calculated with the structure geogrid recover stress command. If the nodes keyword is given the values of these quantities is supplied at
system-local
structure geogrid property command

Syntax
structure geogrid property keyword
Primary keywords:
bending | orthotropic-both | coupling-cohesion-shear | coupling-friction-shear | coupling-stiffness-shear | slide | slide-tolerance
Assigns a property to elements in the range. The element can have isotropic, orthotropic, or anisotropic elastic material properties. The following properties are
available:
density f
thickness f
geogrid thickness
thermal-expansion f
anisotropic membrane material properties {cʹ11, cʹ12, cʹ13, cʹ22, cʹ23, cʹ33} [F/L2], which define membrane material-stiffness matrices [Eʹm] and [Eʹb],
respectively, in the material directions x', y', z'.
anisotropic bending material properties {cʹ11, cʹ12, cʹ13, cʹ22, cʹ23, cʹ33} [F/L2], which define bending material-stiffness matrices [Eʹm] and [Eʹb], respectively,
in the material directions x', y', z'.
anisotropic membrane and bending material properties {cʹ11, cʹ12, cʹ13, cʹ22, cʹ23, cʹ33} [F/L2], which define membrane and bending material-stiffness matrices
[Eʹm] and [ Eʹb ], respectively, in the material directions x', y', z'.
material-x v
specify the vector v whose projection onto the geogrid surface defines the x'-axis of the material coordinate system. The material directions correspond with the
principal directions of orthotropy (for more information, see below).
isotropic f1 f2
isotropic material properties: E and v where E is Young’s modulus [F/L2] and v is Poisson’s ratio
orthotropic membrane material properties {cʹ11, cʹ12, cʹ22, cʹ33} [F/L2], which define membrane material-stiffness matrices [Eʹm] and [Eʹb], respectively, in the
orthotropic bending material properties {cʹ11, cʹ12, cʹ22, cʹ33} [F/L2], which define bending material-stiffness matrices [Eʹ m] and [Eʹb], respectively, in the
orthotropic membrane and bending material properties {cʹ11, cʹ12, cʹ22, cʹ33} [F/L2], which define membrane and bending material-stiffness matrices [Eʹm] and
[Eʹb], respectively, in the material directions x', y', z'.
slide b
slide-tolerance f
local system do not change (the angle β in this figure does not change). If the material-x vector is not specified, then the xʹ-axis will be aligned with the x-axis of
The material coordinate system can be queried with the command structure geogrid list property material-x and the FISH function
struct.shell.beta. It can be visualized with the Structural Geometry plot item by choosing the corresponding System attribute.
structure geogrid recover command

Syntax
structure geogrid recover keyword <range>
Primary keywords:
Stress-recovery for geogrid elements. The stress-recovery procedure can be applied to all elements to compute both the stress resultants and the stresses acting at a
resultants <range>
and membrane stress resultants (Mx, My, Mxy, Nx, Ny, and Nxy) vary linearly over each element, whereas the transverse-shear stress resultants (Qx and Qy) are
contributions from each element in the range), and then spatially differentiates this average bending field over each element to obtain the transverse-shear stress
resultants.
stress resultants can be queried after recovery with the command structure geogrid list resultant and the FISH function struct.shell.resultant. The
shell thickness. The depth factor, v, must be in the range [-1, +1]. v equal to +1 / -1 corresponds with the outer/inner shell surface (outer surface defined by
positive surface system z-direction), and v equal to zero corresponds with the shell mid-surface. If v is not specified, it defaults to +1.
stresses are recovered at the three nodal points and centroid of each element. If we designate the shell mid-surface by xy-axes, then 1) stress components σxx,
σyy, and σxy vary linearly over each element, 2) stress components σzy and σzx are constant over each element, and 3) σzz = 0 over each element. The stresses
are derived from the internal element forces (see structure geogrid list force-node). If the stress resultants are not valid when this command is executed,
then an attempt is first made to recover them; if this attempt fails, then an error message is displayed indicating the problem—usually the inconsistency of the
surface system, which must then be established manually using the structure geogrid recover surface command (see next keyword).
stresses and principal stresses can be queried after recovery with the commands structure geogrid list stress and structure geogrid list stress-
be queried with the structure geogrid list depth-factor and the FISH function struct.shell.depth.factor. The validity of the stresses and principal
surface v
The vector v enables a surface coordinate system to be generated for all nodes used by the elements in the optional range. The surface coordinate system, x' y' z',
has the following properties: (1) z' is normal to the surface; (2) x' is the projection of the given vector onto the surface; and (3) y' is orthogonal to x' and z'. The z'-
direction is found at each node by taking the average normal direction of all elements in the range. If surface v is aligned with z' at any node, then processing
The surface coordinate system can be queried with structure geogrid list system-local and the FISH function struct.node.system.surface. It can
also be set for an individual node with the FISH function struct.node.system.local. It can be visualized with the Geogrid plot item by choosing the
corresponding System attribute.
The surface system at a node automatically becomes invalid under the following conditions: 1) large-strain update; or 2) creation or deletion of an element that
uses the node. Validity must be re-established with the command structure geogrid recover surface.
structure geogrid refine command

Syntax
structure geogrid refine i <range>
This command refines elements in the range by subdividing them by a factor of i. A triangular element refined by i = 2 will yield four triangular elements; i = 3 would
yield 16 triangular elements, etc. The original element is deleted.
structure geogrid select command

Syntax
structure geogrid select keyword
Primary keywords:
b | new | undo
new
undo
this will reverse the operation of the last structure geogrid select command. FLAC3D keeps a maximum undo stack of size 12.
FISH Functions
FISH functions operating on structural geogrids. The type specifiers used in the FISH function signatures are given in the FISH Type Index section.
Note that all shell functions may also be used on geogrid elements.
struct.geogrid.shear.cohesion(STRUCT_GEOGRID_PNT)
Get/set the (shear) coupling spring cohesion strength of the geogrid...
struct.geogrid.shear.dir(STRUCT_GEOGRID_PNT,INT<,INT>)
Get the direction (unit vector in global system) in which...
struct.geogrid.shear.disp(STRUCT_GEOGRID_PNT,INT)
Get the displacement magnitude in the coupling spring at node...
struct.geogrid.shear.friction(STRUCT_GEOGRID_PNT)
Get/set the (shear) coupling spring friction angle of the geogrid...
struct.geogrid.shear.state(STRUCT_GEOGRID_PNT,INT)
Get the yield state of the coupling spring at node...
struct.geogrid.shear.stiffness(STRUCT_GEOGRID_PNT)
Get/set the (shear) coupling spring stiffness of the geogrid element.
struct.geogrid.shear.stress(STRUCT_GEOGRID_PNT,INT)
Get the stress magnitude in coupling spring at node inode ...
struct.geogrid.slide(STRUCT_GEOGRID_PNT)
Get/set the large-strain sliding flag.
struct.geogrid.slide.tol(STRUCT_GEOGRID_PNT)
Get/set the (shear) coupling spring slide tolerance of the geogrid...
struct.geogrid.stress.confining(STRUCT_GEOGRID_PNT,INT)
Get the confining stress at node inode ( inode ∈ {1,...
l struct.geogrid.shear.cohesion
l struct.geogrid.shear.dir
l struct.geogrid.shear.disp
l struct.geogrid.shear.friction
l struct.geogrid.shear.state
l struct.geogrid.shear.stiffness
l struct.geogrid.shear.stress
l struct.geogrid.slide
l struct.geogrid.slide.tol
l struct.geogrid.stress.confining
struct.geogrid.shear.cohesion
Syntax
f = struct.geogrid.shear.cohesion(p)
struct.geogrid.shear.cohesion(p) = f
Get/set the (shear) coupling spring cohesion strength of the geogrid element.
Returns: f - the (shear) coupling spring cohesive strength of the element

Accepts: f - the (shear) coupling spring cohesive strength of the element
Arguments: p - a pointer to a geogrid element
struct.geogrid.shear.dir
Syntax
Vector Access
v = struct.geogrid.shear.dir(p,inode<,i>)
Get the direction (unit vector in global system) in which the geogrid element is being loaded by the coupling spring at node inode (inode ∈ {1, 2, 3}). Returns a vector,
unless an optional component argument i is supplied, in which case it returns the component value.

inode - node number of the element, inode ∈ {1, 2, 3}
Component Access
f = struct.geogrid.shear.dir.x(p,in)
Get the x-component of the direction (unit vector in global system) in which the geogrid element is being loaded by the coupling spring at node inode (inode ∈ {1, 2,
3}).

f = struct.geogrid.shear.dir.y(p,iend)
Get the y-component of the direction (unit vector in global system) in which the geogrid element is being loaded by the coupling spring at node inode (inode ∈ {1, 2,
3}).

f = struct.geogrid.shear.dir.z(p,iend)
Get the z-component of the direction (unit vector in global system) in which the geogrid element is being loaded by the coupling spring at node inode (inode ∈ {1, 2,
3}).

struct.geogrid.shear.disp
Syntax
f = struct.geogrid.shear.disp(p,inode)
Get the displacement magnitude in the coupling spring at node inode (inode ∈ {1, 2, 3}). The coupling spring lies in the tangent plane of the geogrid surface. The
direction in which force is acting is given by struct.geogrid.shear.dir.
Returns: f - displacement magnitude

inode - node number in the element, inode ∈ {1, 2, 3}
struct.geogrid.shear.friction
Syntax
f = struct.geogrid.shear.friction(p)
struct.geogrid.shear.friction(p) = f
Get/set the (shear) coupling spring friction angle of the geogrid element.
Returns: f - the (shear) coupling spring friction angle of the element

Accepts: f - the (shear) coupling spring friction angle of the element
struct.geogrid.shear.state
Syntax
i = struct.geogrid.shear.state(p,inode)
Get the yield state of the coupling spring at node inode (inode ∈ {1, 2, 3}). Return value i ∈ {1, 2, 3} denotes never yielded, yielding now, or yielded in the past,
respectively.
Returns: i - yield state, i ∈ {1, 2, 3} denotes never yielded, yielding now, or yielded in the past, respectively
struct.geogrid.shear.stiffness
Syntax
f = struct.geogrid.shear.stiffness(p)
struct.geogrid.shear.stiffness(p) = f
Returns: f - the (shear) coupling spring stiffness of the element

Accepts: f - the (shear) coupling spring stiffness of the element
struct.geogrid.shear.stress
Syntax
f = struct.geogrid.shear.stress(p,inode)
Get the stress magnitude in coupling spring at node inode (inode ∈ {1, 2, 3}). The coupling spring lies in the tangent plane of the geogrid surface. The direction in
which force is acting is given by struct.geogrid.shear.dir.
Returns: f - stress magnitude

struct.geogrid.slide
Syntax
b = struct.geogrid.slide(p)
struct.geogrid.slide(p) = b
Get/set the large-strain sliding flag. A true value denotes that the large-strain sliding is on.
Returns: b - large-strain sliding flag

Accepts: b - large-strain sliding flag
struct.geogrid.slide.tol
Syntax
f = struct.geogrid.slide.tol(p)
struct.geogrid.slide.tol(p) = f
Get/set the (shear) coupling spring slide tolerance of the geogrid element.
Returns: f - the (shear) coupling spring slide tolerance of the element

Accepts: f - the (shear) coupling spring slide tolerance of the element
struct.geogrid.stress.confining
Syntax
f = struct.geogrid.stress.confining(p,inode)
Get the confining stress at node inode (inode ∈ {1, 2, 3}). A negative value is compression. The confining stress is the stress component acting perpendicular to the
geogrid surface.
Returns: f - confining stress

Liner Structural Elements

Mechanical Behavior
Single-Side Liner-Grid Interaction
The mechanical behavior of each liner element can be divided into the structural response of the liner material itself (see Shell-Type Mechanical Behavior), and the way in
which the liner element interacts with the FLAC3D grid. By default, liner elements are assigned the DKT-CST shell element that resists both membrane and bending loading
(see Shell Finite Elements). A physical liner can be modeled as a collection of liner elements that are attached to the surface of the FLAC3D grid. In addition to providing the
structural behavior of a shell, a shear-directed (in the tangent plane to the liner surface) frictional interaction occurs between the liner and the FLAC3D grid. Also, in the
normal direction, both compressive and tensile forces can be carried, and the liner may break free from (and subsequently come back into contact with) the grid. Liners are
used to model thin liners for which both normal-directed compressive/tensile interaction and shear-directed frictional interaction with the host medium occurs, such as
shotcrete-lined tunnels or retaining walls.
The orientation of the node-local system for all nodes used by liner elements is set automatically at the start of a set of cycles (or when the model cycle 0 command is
x
executed) such that the -axis is aligned with the average normal direction of all liner elements using the node, and the -axes are arbitrarily oriented in the liner
element tangent plane (see Figure 2 (a)).
A liner is attached to the surface of the FLAC3D grid. The behavior at the liner-zone interface is summarized in Figure 1 to 2. The stresses acting on the liner are shown in
\sig \
Figure 1. These stresses, consisting of a normal stress, , and a shear stress, t, are balanced by stresses that develop within the liner itself (these stress
\
resultants — see Stresses in Shells — are denoted by b in Figure 2). The interface behavior is represented numerically at each liner node by a linear spring with finite
tensile strength in the normal direction, and a spring-slider in the tangent plane to the liner surface. The orientation of the spring-slider changes in response to relative shear
{\bf
displacement u} between the liner and the host medium, as shown in Figure 2. (Note that the liner is drawn below the zones in Figure 1 and above the zones in Figure
2.)
../../../../../../_images/stresses
1.png
Figure 1: Stresses acting on the liner elements surrounding a node
idealization1.png
Figure 2: Idealization of interface behavior at a liner node
k
The normal behavior of the liner-zone interface (see Figure 3) is controlled by the normal coupling spring properties of (1) stiffness per unit area, , and (2) tensile
f
strength, . The shear behavior of the liner-zone interface (see Figure 4) is cohesive and frictional in nature, and is controlled by the shear coupling spring properties of
c c
(1) stiffness per unit area, , (2) cohesive strength, , (3) residual cohesive strength, , and (4) friction angle, , and by the interface normal stress,
\sig c
. If the liner fails in tension, then the effective cohesion drops from to , and the tensile strength is set to zero. The total relative normal displacement,
, continues to be tracked such that compressive normal stresses will again develop when the gap closes. Note that the coupling spring properties associated with each
liner element are averaged at liner nodes.
../../../../../../_images/normal-interface-
behavior.png
Figure 3: Normal-directional interface behavior for liner elements
../../../../../../_images/shear-interface-
behavior.png
Figure 4: Shear-directional interface behavior for liner elements
In computing the relative displacement at the liner-zone interface, an interpolation scheme is used to calculate the grid displacement, based on the displacement field in the
zone to which the node is linked. The interpolation scheme uses weighting factors that are determined by the distance to each of the zone gridpoints. The same interpolation
scheme is used to apply forces developed in the liner-zone interface back to the gridpoints of the zone.
Liners support large-strain sliding (by setting the slide property to on), whereby the interpolation locations (used by the liner nodes to transfer forces and velocities to and
from the zones — see Structural Element Links) will migrate through the grid when running in large-strain mode. This allows one to calculate the large-strain, post-failure
behavior of a liner, whereby substantial sliding between the liner nodes and the zones occurs. At each liner node, if large-strain sliding is on and the tensile stress exceeds the
interface tensile strength, then the link that joins this liner node to a zone surface will be deleted; however, if this node later comes back into contact with any zone face, the
connection will be reestablished (via a new link with appropriate liner properties).
Embedded Liner Behavior
The liner structural element can also be made to interact with FLAC3D zones on both sides of the liner. Additional coupling springs are added to the embedded liner for this
capability. (The default liner only provides a single link on each node, whereas the embedded liner provides two links on each node.) Independent properties are specified on
each side of the embedded liner (side 1 and side 2). The embedded liner mechanical behavior is similar to the default liner behavior described above, except that the zone-liner
interface is active on both sides of the embedded liner.
Response Quantities
Liner responses include stresses in the liner itself, as well as stress, displacement, yield state and loading direction in both the normal and shear coupling springs. The liner
responses can be accessed via FISH, and
1. printed with the structure liner list command,

2. monitored with the structure liner history command, and
3. plotted with the Liner plot item.
Refer to Shell-Type Response Quantities for a summary of the commands that support recovery of stresses acting in the liner itself.
Embedded Liner Response Quantities
Embedded liner response quantities are similar to the default liner response quantities described above, except that links or associated quantities can be associated with side 2
as well as side 1, or can be specified with structure liner history command.
The Liner plot item may be colored differently on each side to help identify side 1 and side 2.
Properties
Each liner elements has 8 or 14 (if embedded) properties in addition to those common to all shell-type elements described in Shell-Type Properties. These properties control
the shear and normal behavior of the liner-soil interface.
f
5. coupling-yield-normal, normal coupling spring tensile strength (stress units), [F/L2]
6. coupling-yield-normal-2, normal coupling spring tensile strength on side 2 (stress units), [F/L2]
7. coupling-stiffness-normal, normal coupling spring stiffness per unit area, [F/L3]
8. coupling-stiffness-normal-2, normal coupling spring stiffness per unit area on side 2, [F/L3]
c
9. coupling-cohesion-shear, shear coupling spring cohesion (stress units), [F/L2]
c
10. coupling-cohesion-shear-2, shear coupling spring cohesion on side 2 (stress units), [F/L2]
11. coupling-cohesion-shear-residual, shear coupling spring residual cohesion (stress units), [F/L2]
12. coupling-cohesion-shear-residual-2, shear coupling spring residual cohesion on side 2 (stress units), [F/L2]
\
13. coupling-friction-shear, shear coupling spring friction angle, [degrees]
14. coupling-friction-shear-2, shear coupling spring friction angle on side 2, [degrees]
k
15. coupling-stiffness-shear, shear coupling spring stiffness per unit area, [F/L3]
k
16. coupling-stiffness-shear-2, shear coupling spring stiffness per unit area on side 2, [F/L3]
f \
These properties can be divided into strength ( , , , p) and stiffness ( , ) properties. Choice of appropriate strength properties should
be relatively straightforward, as these correspond with measurable macroscopic strength properties of the real physical system. Choice of the stiffness properties is more
complex and will be discussed below (refer to Interfaces for a more detailed discussion).
Typically, we want the liner-zone interface to be stiff compared to the surrounding material, but able to slip and perhaps open in response to the anticipated loading. For this
situation, we simply need to provide a means by which the liner elements can slide and/or open relative to the zone surfaces. The strength properties are important, but the
elastic stiffnesses are not. It is recommended that the lowest stiffness consistent with small interface deformation be used. A good rule-of-thumb is that and
be set to ten times the equivalent stiffness of the stiffest neighboring zone. The apparent stiffness (expressed in stress-per-distance units) of a zone in the direction normal to
the surface is
\max \left[ {(K + {4\over3}G) \over \Delta z_{\rm min}}

(1) \right]
where: = the bulk and shear modulus, respectively; and

and
\Delta z_{\rm = the smallest dimension of an adjoining zone in the normal direction.
min}
The max [ ] notation indicates that the maximum value over all zones adjacent to the liner is to be used (e.g., there may be several materials adjoining the liner). Note that (1)
strictly applies only to a planar surface subjected to normal penetration. If the surface is curved, as is the case surrounding a circular excavation, the apparent stiffness should
be increased by a factor of 10 to 100. For a particular problem, it is recommended that one confirm that the interface deformation (i.e., the displacement in the coupling
spring) is small relative to the zone deformation. (The coupling spring displacement is obtained via the structure liner list coupling-normal command; the zone
deformation is obtained via the zone gridpoint list displacement command.)
Simple examples are given to illustrate the use of liner.
l Simple Test of Liner-Zone Interface Behavior

l Demonstration of Large-Strain Sliding
l Advancing Lined Tunnel (Slip at Liner-Soil Interface)
l Liner-Reinforced Beam
l Embedded Retaining Wall
A complete list of examples that use liner elements is available in Structural Liner Examples.
Commands & FISH

l Commands
l FISH Functions
Simple Test of Liner-Zone Interface Behavior

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Liner/LinerZoneInterfaceTest" and select "LinerZoneInterfaceTest.f3prj" to
A liner is placed on top of a soil block and then moved in various directions. The normal and shear stress and displacement of one of the liner coupling springs is monitored
and plotted to demonstrate the effects of the liner-zone interface properties on system response.
The FLAC3D model is a one cubic meter block of soil composed of 144 zones, with a 0.33 m2 concrete liner composed of 8 liner elements centered on top of the soil block,
E
as shown in Figure 1. The soil is assigned elastic properties ( = 15 MPa, = 0.3). The liner material is assigned properties corresponding with a 0.1 m thick
t k
concrete liner ( = 25 GPa, = 0.15, = 0.1 m). The liner-zone interface properties ( , , , , , ) are assigned as
follows.
The interface stiffnesses ( and ) are set equal to 8 × 108 N/m3 to ensure small interface deformation using the liner stiffness rule of thumb. The following
interface strength properties are assigned:
4 MPa
tensile strength ( )
4 MPa
cohesion ( )
2 MPa
residual cohesion ( )
20 degrees
friction angle ( )
In order to demonstrate the liner-zone interface behavior, the following conditions are imposed. The velocities of all gridpoints and nodes are fully fixed. The same velocities
are applied to all nodes such that the liner moves as a rigid body. These conditions prevent internal stresses from developing in both the zones and the liner material; only the
liner-zone interface springs are being exercised. The normal and shear stress and displacement at the center coupling spring is monitored and plotted. In the plots of normal
stress versus normal displacement, the sign convention is that compression and overlap are positive (to correspond with the figure representing normal interface behaviors). In
the plots of shear stress versus shear displacement, the magnitude of both shear stress and shear displacement are plotted (to correspond with the figure representing shear
interface behaviors).
../../../../../_images/linerzonetest-geom6.png
Figure 1: FLAC3D model for simple test of liner-zone interface behavior.
The test is performed in six stages. During each stage, a normal or shear displacement is applied, while the other displacement component is fixed. The displacements applied
during each stage are listed in Table 2, where positive/negative normal displacement indicates separation/overlap, and shear motion along the diagonal in the direction (1,1,0)
is positive. The testing results are shown in Figure 2 to Figure 7.
Table 2: Applied Liner Displacements

Stage Normal (mm) Shear (mm)
1a 0 +15
1b 0 -5
2 -10 0
3 0 +10
4 +20 0
6a -20 0
6b 0 +6
During stage 1, a positive shear displacement of 15 mm is followed by a negative shear displacement of 5 mm. The response is shown in Figure 2, which can be compared
with shear interface behavior. The slope of this plot equals the shear coupling spring stiffness per unit area, , and the maximum value equals the cohesion,
(because, at this stage, the interface normal stress is zero). The unloading slope is the same as the loading slope.
During stage 2, the liner is moved downward by 10 mm. The response is shown in Figure 3, which can be compared with normal interface behavior. The slope of this plot
k \sig
equals the normal coupling spring stiffness per unit area, . At this stage, the interface normal stress, , equals 8 MPa. During stage 3, an additional shear
displacement of 10 mm is applied, and the response is shown in Figure 4. The shear stress increases and reaches a maximum value of 6.91 MPa, which corresponds with the
relation
\tau_{\rm max} = c + \sigma_n

\tan\phi
where: = cohesion;
\sig = interface normal stress; and
= friction angle.
f
During stage 4, the liner is moved upward by 20 mm. The response is shown in Figure 5. When the interface normal stress reaches the tensile strength, , of 4 MPa, the
spring breaks, causing the interface normal stress to drop to zero. When the liner fails in tension, the effective cohesion becomes , and the tensile strength is set to zero.
The total relative normal displacement continues to be tracked such that compressive normal stress will again develop when the gap closes. During stage 5, an additional shear
displacement of 2 mm is applied, and the response is shown in Figure 6. The peak shear stress drops from 6.91 to 2 MPa, because the interface normal stress is zero, and the
residual cohesion is now being used. During stage 6, the liner is moved downward by 20 mm, and then an additional shear displacement of 6 mm is applied. The response is
shown in Figure 7. The gap has closed, and the interface normal stress is again 8 MPa. The peak shear stress is 4.91 MPa, in accord with the residual cohesion.
../../../../../_images/linerzonetest-sstress1.png
Figure 2: Shear stress versus shear displacement (after stage 1).
../../../../../_images/linerzonetest-nstress2.png
Figure 3: Normal stress versus normal displacement (after stage 2).
../../../../../_images/linerzonetest-nstress4.png
Figure 5: Normal stress versus normal displacement (after stage 4).
Data File
LinerZoneInterfaceTest.f3dat
; Liner example application

; Simple test of Liner-Zone Interface Behavior
model new
model title 'Simple Test of Liner-Zone Interface Behavior'
; Create the soil.

zone create brick size 6,6,4 point 0 (0,0,0) point 1 (1.0,0,0) point 2 (0,1.0,0) point 3 (0,0,1.0)
zone property bulk=12.5e6 shear=5.77e6 ; soil
; Create the concrete liner.
struct liner create by-face range position (0.33,0.33,1) (0.66,0.66,1)
struct liner property isotropic=( 25e9, 0.15) thickness=0.1 ; concrete
struct liner property coupling-stiffness-normal=8e8 coupling-stiffness-shear=8e8 coupling-yield-normal=4e6 coupling-cohesion-shear=4e6 ...
coupling-cohesion-shear-residual=2e6 coupling-friction-shear=20.0
;
zone gridpoint fix velocity ; fully fix all zones
struct node fix velocity ; fully fix all nodes
struct liner history name='nstr' coupling-stress-normal node 3 component-id 3
struct liner history name='ndis' coupling-displacement-normal node 3 component-id 3
struct liner history name='sstr' coupling-stress-shear node 3 component-id 3
struct liner history name='sdis' coupling-displacement-shear node 3 component-id 3
; Apply six sets of normal/shear displacements to liner.

struct node initialize velocity (0.707e-5,0.707e-5,0) local ; norm disp= 0 mm
model cycle 1500 ; shr disp= +15 mm
struct node initialize velocity (-0.707e-5,-0.707e-5,0) local ; norm disp= 0 mm
model cycle 500 ; shr disp= -5 mm
model save 'stage1'
struct node initialize velocity (0,0,-1e-5) local ; norm disp= -10 mm

model cycle 1000 ; shr disp= 0 mm
model save 'stage2'

model save 'stage3'
struct node initialize velocity (0,0,1e-5) local ; norm disp= +20 mm

model save 'stage4'

model save 'stage5'
struct node initialize velocity (0,0,-1e-5) local ; norm disp= -20 mm


model save 'stage6'
Demonstration of Large-Strain Sliding

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Liner/LargeStrainSliding" and select "LargeStrainSliding.f3prj" to load.
The main data files used are shown at the end of this example. The remaining data files can be found in the project.
A 0.33 m2 liner is placed on top of a one cubic meter soil block, moved down into the soil, and then moved laterally across the soil surface. The problem is run in large-strain
mode. The liner is moved downward by 10 cm, and then it is moved laterally along the diagonal until the liner lies at the original corner of the top surface. For such large
relative motion between the liner and the zones, it is necessary to set the large-strain sliding flag of the liner to on. (Liners interact with the grid via node-to-zone links. These
links store the zone and an interpolation location within the zone to allow transfer of forces and velocities between the nodes and the zones. By default, these interpolation
locations will not change, even if running in large-strain mode. The interpolation locations can be allowed to migrate through the grid by setting the large-strain sliding flag to
structure liner property slide on.)
The FLAC3D model is a one cubic meter block of soil composed of 144 zones, with a 0.33 m2 concrete liner composed of 8 liner elements centered on top of the soil block,
E
as shown in Figure 1. The soil is assigned elastic properties ( = 15 MPa, = 0.3). The liner material is assigned properties corresponding with a concrete liner 0.1
\ t
m thick ( = 25 GPa, n= 0.15, = 0.1 m), and the following liner-zone interface properties are assigned:
k 8 × 108 N/m3
interface normal stiffness ( )
k 8 × 108 N/m3
interface shear stiffness ( )
0 MPa
tensile strength ( )
0 MPa
cohesion ( )
0 MPa
residual cohesion ( )
0 degrees
friction angle ( )
../../../../../_images/largestrainsliding-geom.png
Figure 1: FLAC3D model for demonstration of large-strain sliding.
First, the problem is run with large-strain sliding off by removing the structure liner property slide command from the data file. The zz-stresses in the zones after
applying the first 10 cm downward displacement are shown in Figure 2. At this stage, the response is reasonable because large relative motion between the liner nodes and the
zones has not occurred. However, after moving the liner along the diagonal, we see in Figure 3 that the zz-stresses and the zone deformation field no longer correspond with
the liner location. This is incorrect. The interpolation locations have not moved from their original locations; therefore, the grid is still feeling a compressive force acting in
the block center.
When the problem is rerun with large-strain sliding on, the behavior is correct (see Figure 4 and Figure 5). The zz-stresses and zone deformation field correspond with the
liner location, because the interpolation locations have migrated through the grid to follow the liner motion. In fact, it is even possible to move the liner completely off the
grid, as shown in Figure 6. If any liner nodes later come back into contact with any zone faces, then the corresponding links will be reestablished (see Figure 7).
../../../../../_images/largestrainsliding-vstress1off.png
Figure 2: Vertical stresses in the soil (large-strain sliding off; normal displacement of 10 cm).
../../../../../_images/largestrainsliding-vstress2off.png
Figure 3: Vertical stresses in the soil (large-strain sliding off; shear displacement of 47.6 cm).
../../../../../_images/largestrainsliding-vstress1.png
Figure 4: Vertical stresses in the soil (large-strain sliding on; normal displacement of 10 cm).
Figure 5: Vertical stresses in the soil (large-strain sliding on; shear displacement of 47.6 cm).
Figure 6: Vertical stresses in the soil (large-strain sliding on; shear displacement of 105 cm).
Figure 7: Vertical stresses in the soil (large-strain sliding on; shear displacement of -453 cm).
Data File
LargeStrainSliding.f3dat
; SEL Liner example application

; Demonstration of Large-Strain Sliding for a Liner
model new
model title 'Demonstration of Large-Strain Sliding for a Liner'
; Create the soil.

zone create brick size (6,6,4) point 0 (0,0,0) point 1 (1,0,0) point 2 (0,1,0) point 3 (0,0,1)
zone prop bulk=12.5e6 shear=5.77e6 ; soil
zone face apply velocity-normal 0 range position-z 0
; Create the concrete liner.

struct liner create by-face range position (0.33,0.33,1) (0.66,0.66,1)
struct liner property isotropic=(25e9,0.15) thickness=0.1 ; concrete
struct liner property coupling-stiffness-normal=8e8 coupling-stiffness-shear=8e8 coupling-yield-normal=0.0 coupling-cohesion-shear=0.0 ...
coupling-cohesion-shear-residual=0.0 coupling-friction-shear=0.0
struct node fix velocity ; fully fix all nodes

zone history name='szz' stress-zz position (0.5,0.5,1)
model save 'slide0'
; Apply liner displacements - liner large strain-sliding off

struct node initialize velocity (0,0,-1e-4) local ; norm disp= -10 cm
model cycle 1000 ; shr disp= 0
model save 'slide1-off'
struct node initialize velocity (3.3e-4,-3.3e-4,0.0) local ; norm disp= 0

model cycle 1000 ; shr disp= +476 cm
model save 'slide2-off'
model restore 'slide0'

; Activate liner large strain-sliding
struct liner property slide on
; Apply liner displacements

model save 'slide1'
struct node initialize velocity (3.3e-4,-3.3e-4,0.0) local ; norm disp= 0

model save 'slide2'

model save 'slide3'
struct node initialize velocity (0,0,1e-3) local ; norm disp= +12 cm

struct node initialize velocity (-3.3e-3,3.3e-3,0.0) ; norm disp= 0
model cycle 315 ; shr disp= -1500 cm
model save 'slide4'
Advancing Lined Tunnel (Slip at Liner-Soil Interface)

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Liner/AdvancingLinedTunnel" and select "AdvancingLinedTunnel.f3prj" to
This example demonstrates how to simulate the sequential operations of excavating and adding support to an advancing tunnel. The tunnel has a circular cross-section and is
\ E
located at 5 m depth in a soft elastic soil ( = 48.2 MPa, = 0.34) with isotropic in-situ stresses of 1 MPa. The tunnel is supported by shotcrete ( = 10.5
\
GPa, = 0.25) with a thickness of 0.2 m. The shotcrete remains elastic; however, the liner-soil interface can separate and/or slip. This example replicates the Advancing
Lined Tunnel (Rigidly Connected) example, but replaces the shell elements used in that example with the liner elements used here. The shell elements provide a rigid
connection with the soil, whereas the liner elements provide an elastic connection that allows gaps to form and slip to occur. In this example, first a large cohesive strength is
assigned to the soil-liner interface to reproduce the rigid behavior from the shell element version, and then we set the cohesive strength to zero and observe the slip and
resulting stress redistribution.
Begin with an initial tunnel of 2 m total length. For simplicity, it is assumed that the excavation proceeds simultaneously on both tunnel faces; therefore, it is only necessary to
model one quarter-section of the tunnel by applying symmetry boundary conditions on the three symmetry planes. (Specifying the proper symmetry conditions to the nodes on
these planes requires first aligning the node-local systems, as described below.) The excavation process is modeled by assigning the null material model to zones, then
allowing the stresses to redistribute. The model at this stage is shown in Figure 1. Now the shotcrete is installed by creating liner elements and attaching them to the tunnel
surface with the structure liner create by-face command. The next tunnel segment is excavated and, again, the stresses are allowed to redistribute. The model at this
stage is shown in Figure 2. This excavation sequence can be repeated to follow the entire tunnel construction.
../../../../../_images/advancingliner-system1.png
Figure 1: Stage 1: Excavate tunnel section 1.
../../../../../_images/advancingliner-system2t1.png
There are three symmetry planes in this model. Symmetry boundary conditions (zero displacement normal to the plane, and zero rotation about two axes that lie in the plane)
must be specified for the nodes that lie upon these planes. These conditions are specified using the structure node fix command; however, this command operates on the
degrees of freedom associated with the node-local system, and the node-local systems of all nodes used by liner elements are set automatically at the start of a set of cycles (or
when the model cycle 0 command is executed), such that the z-axis is aligned with the average normal direction of all liner elements using the node, and the xy-axes are
arbitrarily oriented in the liner element tangent plane. For this model, the default orientation is shown in Figure 3.
Nodes lying on the x = 0 and z = 0 planes must be reoriented in order to specify the proper symmetry boundary conditions. This is accomplished with the commands
struct node system-local x (1,0,0) y (0,-1,0) range position-x 0

struct node fix system-local range position-x 0
struct node fix velocity-x rotation-y rotation-z range position-x 0
struct node system-local x (0,0,-1) y (0,-1,0) range position-z 0
struct node fix system-local range position-z 0
struct node fix velocity-x rotation-y rotation-z range position-z 0
These commands realign and then fix the appropriate node-local systems and also specify the proper velocity-fixity conditions. The realigned systems must be fixed with the
structure node fix system-local command in order to prevent automatic realignment to the default orientation during the next set of cycles. When realigning these
systems, we must ensure that the local z-axis remains normal to the liner tangent plane, because the node-local orientations define the liner-zone attachment conditions. The
final, realigned node-local system orientations are shown in Figure 4.
../../../../../_images/advancingliner-localt1.png
Figure 3: Default orientation of node-local systems.
../../../../../_images/advancingliner-localt2.png
Figure 4: Orientation of node-local systems after realignment.
k
The liner-zone interface stiffnesses ( and ) are set equal to 7.4 × 1010 N/m3 to ensure that the interface deformation is small relative to the zone deformation
using the liner stiffness equation, and increasing the value by a factor of 100, as suggested in the text following this equation. (We will confirm below that the criterion of
small interface deformation is met for our system.)
In the first run, a large cohesive strength is assigned to the liner-zone interface. The behavior of this model should be similar to the behavior of the rigidly connected system.
Figure 5 and Figure 6 show the displacements that occur during the second excavation stage for the case with no support and with support, respectively. The z-displacement
history at the tunnel crown is included in each figure. See that the support reduces the crown displacement from approximately 12 mm to 1 mm.
../../../../../_images/advancingliner-dispcontns.png
Figure 5: Displacements during stage 2—no support.
../../../../../_images/advancingliner-dispcont2a.png
Figure 6: Displacements during stage 2—shotcrete support (liner-zone cohesion = 1020).
M
The bending stress resultant, , where the x-direction lies along the tunnel axis, is shown in Figure 7. We see that bending is most extreme at the front of the liner near
the tunnel face. A plot of the deformed shape of the liner in Figure 8 indicates that this intense bending arises from the large pinching deformation. These two plots can be
compared with the corresponding figures from the shell element version. The close similarity indicates that the system is behaving like the rigidly connected case.
../../../../../_images/advancingliner-bending2a.png
Figure 7: Bending stress resultant, , at end of stage 2 (liner-zone cohesion = 1020).
../../../../../_images/advancingliner-deform2a.png
Figure 8: Deformed (magnification of 150) shape of shotcrete at end of stage 2 (liner-zone cohesion = 10 20).
It is confirmed that the interface deformation is small relative to the zone deformation (and thus confirm that our values of and are large enough) by plotting
the normal displacement of the gridpoint, node and coupling spring at the tunnel crown (see Figure 9). If the model is rerun with values of and that are 100
times smaller than the current values, it is found that the interface deformation is no longer small relative to the zone deformation (see Figure 10). This leads to lower loads
M
being carried in the liner. The maximum value of bending stress resultant, , is 44% less than its previous value (compare Figure 11 and Figure 7). In order to obtain
k
the proper system response, the values of and must be large enough to keep the interface deformation small relative to the zone deformation.
../../../../../_images/advancingliner-ndisphist2a.png
Figure 9: Normal displacement of gridpoint, node, and coupling spring at tunnel crown at end of stage 2 (liner-zone cohesion = 1020).
../../../../../_images/advancingliner-ndisphistls.png
Figure 10: Normal displacement of gridpoint, node, and coupling spring at tunnel crown at end of stage 2 ( and reduced by factor of 100; liner-zone cohesion
= 1020).
../../../../../_images/advancingliner-bendingls.png
Figure 11: Bending stress resultant, , at end of stage 2 ( and reduced by factor of 100; liner-zone cohesion = 1020).
The normal and shear stresses acting on the liner at the end of stage 2 are shown in Figure 12 and Figure 13. Both stresses are largest near the front of the liner near the tunnel
face. These stresses are causing the pinching deformation seen in Figure 8. If the cohesive strength of the soil-liner interface is set to zero and cycled to equilibrium, it is
observed that the liner springs back in the negative global y-direction (see Figure 14) as the shear stresses acting on the liner go to zero. The normal stresses acting on the liner
M
and the bending stress resultant, , are only minimally affected.
../../../../../_images/advancingliner-nstress2a.png
Figure 12: Normal stress acting on liner surface at end of stage 2 (liner-zone cohesion = 1020).
../../../../../_images/advancingliner-sstress2a.png
Figure 13: Shear stress acting on liner surface at end of stage 2 (liner-zone cohesion = 1020).
../../../../../_images/advancingliner-disp2b.png
Figure 14: Liner displacement produced by setting the liner-zone cohesion to zero after stage 2.
One additional excavation stage is performed. The model at the end of this stage is shown in Figure 15. The shotcrete support has been extended into tunnel section 2 by
issuing another structure liner create by-face command and specifying an ID number that differs from the ID number of the liner in tunnel section 1. This creates a
"cold-joint" between the two shotcrete segments. (There will be a collection of double nodes lying along the interface, one of which is used by segment one, and one used by
segment two. Forces and moments will not be transferred between the adjoining liner elements; instead, only forces will be transmitted into the surrounding zones at the
common locations. This mimics two separate liner segments lying next to one another.) The deformation that occurs during stage 3 begins to load the new liner segment and
produces additional load in the previous liner segment. Both the displacement and the bending stress fields (see Figure 16) are discontinuous across the joint.
../../../../../_images/advancingliner-system3.png
../../../../../_images/advancingliner-bending3.png
Figure 16: Bending stress resultants, , at end of stage 3 (liner-zone cohesion of zero).
Data File
AdvancingLinedTunnel.f3dat
; SEL Liner example application :

; Advancing Lined Tunnel with Slip at Liner-Soil interface
model new
model title 'Advancing Lined Tunnel with Slip (using liners)'
; Create model geometry
zone create radial-cylinder dim 1.0 point 0 0 0 0 point 1 5 0 0 point 2 0 2 0 point 3 0 0 5 ...
ratio 1.0 1.0 1.0 1.2 size 1 8 4 4 ...
group 'rock' fill group 'tunnel'
zone create radial-cylinder dim 1.0 point 0 0 2 0 point 1 5 2 0 point 2 0 5 0 point 3 0 2 5 ...
ratio 1.0 1.0 1.0 1.2 size 1 3 4 4 ...
group 'rock' fill group 'tunnel'
; Name regions of the model
zone group 'section1' range position-y 0 1 group 'tunnel'
zone face group 'shotcrete1' internal range group 'rock' group 'section1'
; Material model and properties

zone property bulk 50e6 shear 18e6
; Initial Conditions
zone initialize stress xx -1e6 yy -1e6 zz -1e6
; Boundary Conditions
zone gridpoint fix velocity-x range position-x 0.0
zone gridpoint fix velocity-y range position-y 0.0
zone gridpoint fix velocity-z range position-z 0.0
zone gridpoint fix velocity range union position-x 5.0 position-y 5.0 position-z 5.0
zone cmodel assign null range group 'section1'
model save 'tun1'
;
zone history name 'zdisp' displacement-z position (0,1,1)
zone history name 'zvel' velocity-z position (0,1,1)
model save 'tun2-initial'
; --- Solve case with no support
model save 'tun2-nosupport'
; --- Solve case with shotcrete
model restore 'tun2-initial'
struct liner create by-face id=1 range group 'shotcrete1'
struct liner property isotropic=(10.5e9, 0.25) thickness=0.2
struct liner property coupling-stiffness-normal=7.4e10 coupling-stiffness-shear=7.4e10 coupling-cohesion-shear=1e20
model cycle 0
model save 'tun2-temp1'
; --- Specify symmetry conditions for nodes along the 3 symmetry planes
struct node history name 'znode' displacement-z component-id=25
struct liner history name 'ndis' coupling-displacement-normal node 2 component-id=32
model cycle 0
model save 'tun2-temp2'
model save 'tun2a'
; Repeat excavation with lower stiffnesses (factor 100)

model restore 'tun2-temp2'
struct liner property coupling-stiffness-normal=7.4e8 coupling-stiffness-shear=7.4e8 coupling-cohesion-shear=1e20
model save 'tun2a-lowstiff'
; Pursue excavation with larger stiffnesses (reduce cohesion)

model restore 'tun2a'
struct node initialize displacement (0,0,0)
struct liner property coupling-cohesion-shear=0.0
model save 'tun2b'

struct liner create by-face id=2 range group 'shotcrete2'
; --- Specify symmetry conditions for nodes along the 3 symmetry planes
struct liner property isotropic=(10.5e9, 0.25) thickness=0.2 range id 2
struct liner property coupling-stiffness-normal=7.4e10 coupling-stiffness-shear=7.4e10 coupling-cohesion-shear=0.0 range id 2
model save 'tun3'
Liner-Reinforced Beam
Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Liner/ReinforcedBeam" and select "ReinforcedBeam.f3prj" to load. The
E \
A simply supported wooden beam ( = 8.6 GPa, = 0, length of 2.5 m, cross-section of 45 by 90 mm) has a concentrated load of 2000 N applied at its center. The
beam is modeled with 40 FLAC3D zones. (Note that more zones are required to obtain the correct beam-theory solution. The system, as modeled, is too stiff; however, it is
sufficient for the present example.) The FLAC3D model and the displacement field are shown in Figure 1.
E
The problem is rerun with a 10 mm thick steel liner ( = 200 GPa, = 0.3) attached to the beam bottom. By setting the liner cohesive strength to a large value, no
slip is allowed to occur at the liner-beam interface. (The liner stiffnesses are chosen using the liner stiffness equation.) The displacement field of the liner-reinforced beam is
shown in Figure 2. The presence of the liner has reduced the maximum mid-span deflection from 9.4 to 5.4 mm. Shear stresses have developed along the liner-beam interface
(see Figure 3), and the maximum tensile xx-stress at the outer fiber of the liner is approximately 35 MPa (see Figure 4). The maximum tensile xx-stress at the liner mid-
surface is 35 MPa. By setting the liner cohesive strength to zero, slip is allowed to occur along the liner-beam interface. The interface shear stresses go to zero, and the
displacement field increases to almost match that of the unlined beam (see Figure 5). The liner continues to provide some stiffness to the composite system.
../../../../../_images/linerbeam-systemunlined.png
Figure 1: Displacement field of unlined wooden beam.
../../../../../_images/linerbeam-systemnoslip.png
Figure 2: Displacement field of liner-reinforced wooden beam (no slip at liner-beam interface).
../../../../../_images/linerbeam-sstressnoslip.png
Figure 3: Shear stresses acting on the liner (no slip at liner-beam interface).
../../../../../_images/linerbeam-xxstressnoslip.png
Figure 4: xx-stress carried in the outer fiber of the liner (no slip at liner-beam interface).
../../../../../_images/linerbeam-systemslip.png
Figure 5: Displacement field of liner-reinforced wooden beam (full slip at liner-beam interface).
We illustrate the effect of mesh configuration when connecting liner elements to the FLAC3D grid by rerunning this example, but generating a cross-diagonal mesh by adding
the keyword cross-diagonal to the structure liner create command. The bending stress resultant field is shown for the two different mesh types in Figure 6 and Figure 7.
It can be seen that a near-zero bending moment is occurring at the center of each zone face for the cross-diagonal mesh that has a node at the face center, whereas this
anomaly is absent for the crosshatch mesh. The reason for this behavior is described in the structure liner create command reference, and will be repeated here.
When connecting elements to the grid, it is best to locate nodes at gridpoints. If the finite-element type can resist bending (DKT, DKT-CST or DKT- (CST
cubically across element faces, but varies only linearly across zone faces. Thus, when connecting bending-resistant elements rigidly to zone faces, it is best to
utilize a crosshatch mesh, because the middle node of the cross-diagonal mesh will be constrained to translate according to the linear displacement field of the
zone face. This overconstrains the elements and can produce near-zero moments at these mid-nodes when present in a nonzero moment field.
../../../../../_images/linerbeam-mxnoslip.png
Figure 6: Bending stress resultants, , near liner center (crosshatch mesh).
../../../../../_images/linerbeam-mxcross.png
Figure 7: Bending stress resultants, , near liner center (cross-diagonal mesh).
Data File
ReinforcedBeam.f3dat
; SEL Liner example application - Liner Reinforced Beam

model new
model title 'Bending of a liner'
; Create zone geometry
zone create brick size (20,1,2) ...
point 0 (0,0,0) point 1 (2.5,0,0) point 2 (0,45e-3,0) point 3 (0,0,90e-3)
; Constitutive model and properties
zone property young 8.6e9 poisson 0
; Boundary Conditions
zone gridpoint fix velocity-x range position-x 0 position-z 0
zone gridpoint fix velocity-z range position-x 0 position-z 0
zone gridpoint fix velocity-z range position-x 2.5 position-z 0
zone gridpoint fix force-applied-z -1000 range position-x=1.25 position-z=90e-3
model save 'Start'
; --- Unlined case

model save 'Unlined'
; Lined Case

; Create liner and properties
struct liner create by-face range position-z 0
struct liner property isotropic=(200e9, 0.3) thickness=10e-3 ; steel
struct liner property coupling-stiffness-normal=1.9e12 coupling-stiffness-shear=1.9e12 coupling-cohesion-shear=1e20 coupling-yield-normal=1e20
model save 'Lined-NoSlip'
; Reduce liner shear strength

struct liner property coupling-cohesion-shear=0.0
model save 'Lined-Slip'
; Recreate liner with cross-diagonal elements

struct liner create by-face cross-diagonal range position-z=0
struct liner property isotropic=(200e9, 0.3) thickness=10e-3 ; steel
struct liner property coupling-stiffness-normal=1.9e12 coupling-stiffness-shear=1.9e12 coupling-cohesion-shear=1e20 coupling-yield-normal=1e20
model save 'Lined-Cross'
Embedded Retaining Wall

Problem Statement
Note
To view this project in FLAC3D, use the menu command Help ► Examples.... Choose "Structure/Liner/EmbeddedRetainingWall" and select
"EmbeddedRetainingWall.f3prj" to load. The main data files used are shown at the end of this example. The remaining data files can be found in the project.
The following example illustrates the use of the embedded liner to simulate a retaining wall (e.g., a sheetpile wall). The soil/wall properties chosen for this example are for
demonstration purposes; actual values for wall friction and adhesion can be found in the literature (e.g., Clayton et al. 1993).
The initial geometry for this example is shown in Figure 1.
The model uses zone initialize-stresses to initialize stresses due to gravitational loading, and the liner coupling springs are initialized with the structure liner
initialize coupling command. Note that while this command accounts for the stress state in the surrouding zones, some cycling must take place to account for the
gravitational weight of the liners.
The model is stepped to an equilibrium state with the embedded liner within the grid. Then the zone relax excavate command is use to excavate in a way that does not
cause spurious tensilve failure, and the model is stepped to equilibrium again. The resulting displacements in the soil are plotted in Figure 2. The moment distribution in the
wall is shown in Figure 3.
../../../../../_images/embeddedwall-system.png
Figure 1: Initial geometry, showing the liner embedded within the grid.
../../../../../_images/embeddedwall-disp.png
Figure 2: Displacements of the soil behind the wall.
../../../../../_images/embeddedwall-stress1.png
Figure 3: bending stress resultant.
Reference
Clayton, C. R. I., J. Milititsky and R. T. Woods. Earth Pressure and Earth-Retaining Structures, pp. 145-148. London: Blackie Academic & Professional (1993).
Data File
EmbeddedRetainingWall.f3dat
; Liner example application Embedded Retaining Wall

model new
model title 'Demonstration of Embedded Liner'
; Create the soil.

zone create brick size 11,1,11 group 'right'
zone prop bulk=5e9 shear=1e9 density 2000 cohesion 1e4 friction 30 tension 0
model gravity 10
; Name regions
zone group 'left' range position-x 0 4 position-z 1 50
zone face group 'Liner' internal range group 'right' group 'left' position-z 1.0 not
zone gridpoint fix velocity-x range union position-x=0 position-x=11
zone gridpoint fix velocity-y

zone gridpoint fix velocity-z range position-z=0
; create the embedded liner (side1 and and side2 properties are assumed to be the same)
struct liner create by-face separate range group 'Liner'
struct liner property isotropic=( 2e9, 0.25) thickness=1.0 density 2000
struct liner property coupling-stiffness-normal=1e11 coupling-stiffness-shear=1e11 coupling-yield-normal=0.0 coupling-cohesion-shear=0 ...
coupling-cohesion-shear-residual=0 coupling-friction-shear=30.0
struct liner property coupling-stiffness-normal-2=1e11 coupling-stiffness-shear-2=1e11 coupling-yield-normal-2=0.0 coupling-cohesion-shear-2
coupling-cohesion-shear-residual-2=0 coupling-friction-shear-2=30.0
struct liner initialize coupling
model save 'Start'
; Solve to equilibrium
; Excavate
zone relax excavate range position-x 0 4 position-z 4 50
struct liner property slide=on
model solve convergence 0.1
model save 'Weaken'
Commands
Operations on structural element liners.
Liner elements use the same internal formulation as shell elements. By default, they are deformable, connected to their surroundings in all directions. They are assumed to be
placed on a surface of the model, and, therefore, link interactions normal to the element surface are directional. They are unique in the structural element logic for the ability
to support two links on each node, allowing liners to be embedded between two surfaces (using the embedded keyword during creation).
Structural Element Liner Commands
structure liner apply

Assign uniform applied pressure f to all liner elements in...
structure liner create
Create a liner.
structure liner delete
Delete all liner elements in the range.
structure liner gap-factor
Sets the gap factor used during large-strain sliding of liner...
structure liner group
Assign all liner elements in the range to the group...
structure liner hide
This commands hides or un-hides all liner elements in the...
structure liner history
Sample liner responses.
structure liner import
Create liner elements from an outside source.
structure liner initialize
structure liner list
List properties and responses of each liner element in the...
structure liner property
structure liner recover
Stress recovery for liner elements.
structure liner refine
this command refines elements in the range by subdividing them...
structure liner select
l structure liner apply command

l structure liner create command
l structure liner delete command
l structure liner gap-factor command
l structure liner group command
l structure liner hide command
l structure liner history command
l structure liner import command
l structure liner initialize command
l structure liner list command
l structure liner property command
l structure liner recover command
l structure liner refine command
l structure liner select command
structure liner apply command

Syntax
structure liner apply f <range>
Assign uniform applied pressure f to all liner elements in the range. Positive pressure acts in the positive z-direction of the element system and maintains this orientation
during large-strain motion.
structure liner create command

Syntax
structure liner create keyword
Primary keywords:
Create a liner. The four main keywords articulate four different techniques of creation: by creating a collection of elements from a group of zone faces (by-face); by
creating a single element from four existing nodes (by-nodeids), from a specified quadrilateral (by-quadrilateral), or from a triangle (by-triangle).
Create new elements that are attached to the set of three- or four-sided zone-faces in the range. By default, only surface faces will be considered; the internal
will be ordered counter-clockwise with respect to the outside of the specified zone faces, thereby making the element z-axis point outward. The element will be
Create elements given an existing set of nodes. The new elements will not be attached to the grid; if you wish to attach it to the grid, then after creating it, position
moved into a zone).
create elements based on four points forming a quadrilateral, in order. The element local system will point in the opposite direction determined by using the right-
hand rule. The new elements will not be attached to the grid; if you wish to attach it to the grid, then after creating it, position its nodes with the structure node
The new elements will not be attached to the grid; if you wish to attach it to the grid, then after creating it, position its nodes with the structure node
Keyword Block
The following keywords may be optionally provided on liner creation, using any of the major keywords: by-face, by-nodeids, by-quadrilateral and by-
triangle.
id i
group s1 <slot s2 >
Assign the created elements to group s1. The group is assigned to the slot named s2 if supplied; it is assigned to the slot named Default if not supplied. Use
of the group logic is described in Group.
cross-diagonal 
distinct
Specify the finite element formation used by each structural element. If no element type is specified, then the element type will be DKT-CST. Note that the
type of finite element is associated with each structural element as it is created, and cannot subsequently be altered. The finite element type of existing
structural elements is printed by the structure liner list element-type command. The value of the keyword supplied must be one of the following
cst
csth
dkt
dkt-cst
membrane loading.
dkt-csth
embedded
Specify that this liner is two-sided. If the embedded keyword is used, then the internal keyword is implied, even if not explicitly given.
internal
maximum-length f
segments i
separate keyword
Select a group of internal faces, and separate them into surfaces as with the zone separate command. A liner will be created between the two surfaces.
This keyword implies both embedded and internal. The following keywords are available:
origin v
The point v is used to determine which side of the faces selected will be considered side 1, and which will be side 2. The vector from v to the face
centroid is compared with the normal to the face. The side pointing toward v will be side 1, and the side pointing away from v will be side 2. If the
origin keyword is not specified, it is assumed to be (0,0,0).
clear-attach
If specified, causes any attach conditions on the boundary to be cleared. By default, an existing attach condition causes an error.
size i1 i2
structure liner delete command

Syntax
structure liner delete <range>
Delete all liner elements in the range. Structure nodes and links that become disconnected from any element will automatically be deleted as well.
structure liner gap-factor command

Syntax
structure liner gap-factor f
Sets the gap factor used during large-strain sliding of liner elements. During large-strain sliding, if the gap that forms between a node used by a liner element and the
zone to which it is attached becomes greater than f times the zone size (where zone size is the maximum x-, y-, or z-dimension of the zone bounding box), and the
normal spring is in tension, then the simulation stops and an error message is displayed. If this large gap is physically reasonable, then the simulation can be continued
by either increasing f or reducing the liner tensile strength such that the normal spring breaks. By default, f equals 0.1.
structure liner group command

Syntax
structure liner group s1 <slot s2 >
Primary keywords:
slot | remove
Assign all liner elements in the range to the group with the name s. Use of the group logic is described in Group. Any element may only belong to one group in a given
slot. Assigning an element to a new group in that slot will cause it to be removed from its current group assignment. The command structure liner list group
command lists the existing element group names. The groups can be visualized with the liner plot item.
slot s
remove
structure liner hide command

Syntax
structure liner hide <keyword> <range>
Primary keywords:
b | undo
This commands hides or un-hides all liner elements in the range. By default, commands that use a range filter will skip hidden objects. This can be overruled with the
If a boolean type is specified, then if on it hides all elements in the range. If off it un-hides (or shows) all elements in the range, and the use-hidden keyword is
undo
This will reverse the operation of the last structure liner hide command. FLAC3D keeps a maximum undo stack of size 12.
structure liner history command

Syntax
structure liner history keyword
Primary keywords:
coupling-displacement-normal | coupling-displacement-shear | coupling-stress-normal | coupling-stress-shear | coupling-yield | force | force-x | force-y | force-z |

moment | moment-x | moment-y | moment-z | resultant-mx | resultant-my | resultant-mxy | resultant-nx | resultant-ny | resultant-nxy | resultant-qx | resultant-qy |
principal-intermediate | principal-maximum | principal-minimum | stress-xx | stress-xy | stress-xz | stress-yy | stress-yz | stress-zz
Sample liner responses. The nodes of an element will be ordered counterclockwise with respect to the outside of the zone faces upon which the liner was created.
The element to be sampled must be identified by either component-id or by position. If position v is used, the element nearest to v is taken.
For some history types, the node of the element to be sampled may be specified optionally with the keyword node i (where i = 1, 2, or 3). If node is omitted, node 1 is
used by default.
For some history types, the side of an embedded liner element may be specified with the keyword side i (where i = 1 or 2). If side is omitted, side 1 is used by default.
structure liner recover surface command is invoked using that vector for the specified element). Surface-X v is required for these histories.
surface.
coupling-displacement-normal [keywordblock]
displacement in the normal coupling spring at a node of the element. Sign convention for a normal spring is +/-, indicating separation/overlap. This option uses
the node and side keywords.
coupling-displacement-shear [keywordblock]
displacement in the shear coupling spring at a node of the element. Shear springs store displacement magnitude, and this is always positive. This option uses the
node and side keywords.
coupling-stress-normal [keywordblock]
stress in the normal coupling spring at a node of the element. The sign convention for normal spring is +/-, indicating separation/overlap. This option uses the
node and side keywords.
coupling-stress-shear [keywordblock]
stress in the shear coupling spring at a node of the element. This option uses the node and side keywords.
coupling-yield [keywordblock]
yield state in the coupling spring at a node of the element. Value {0, 1, 2} denotes never yielded, now yielding, or yielded in the past, respectively. This option
uses the node and side keywords.
force magnitude, global system. This option uses the node keyword.
nodal force (x-component, global system). This option uses the node keyword.
nodal force (y-component, global system). This option uses the node keyword.
nodal force (z-component, global system). This option uses the node keyword.
moment magnitude, global system. This option uses the node keyword.
nodal moment (x-component, global system). This option uses the node keyword.
nodal moment (y-component, global system). This option uses the node keyword.
nodal moment (z-component, global system). This option uses the node keyword.
stress resultant Mx in the element surface system. This option uses the surface-x keyword.
stress resultant My in the element surface system. This option uses the surface-x keyword.
stress resultant Mxy in the element surface system. This option uses the surface-x keyword.
stress resultant Nx in the element surface system. This option uses the surface-x keyword.
stress resultant Ny in the element surface system. This option uses the surface-x keyword.
stress resultant Nxy in the element surface system. This option uses the surface-x keyword.
stress resultant Qx in the element surface system. This option uses the surface-x keyword.
stress resultant Qy in the element surface system. This option uses the surface-x keyword.
principal intermediate stress, global system. This option uses the depth-factor keyword.
principal maximum stress, global system. This option uses the depth-factor keyword.
principal minimum stress, global system. This option uses the depth-factor keyword.
stress xx-component, global system. This option uses the depth-factor keyword.
stress xy-component, global system. This option uses the depth-factor keyword.
stress xz-component, global system. This option uses the depth-factor keyword.
stress yy-component, global system. This option uses the depth-factor keyword.
stress yz-component, global system. This option uses the depth-factor keyword.
stress zz-component, global system. This option uses the depth-factor keyword.
Keyword Block
The following keywords are available to control the location and other details of the history. Some keywords are only available if noted. coupling-
displacement-normal, coupling-displacement-shear, coupling-stress-normal, coupling-stress-shear, coupling-yield, force, force-x, force-y,
force-z, moment, moment-x, moment-y, moment-z, principal-intermediate, principal-maximum, principal-minimum, resultant-mx, resultant-mxy,
resultant-my, resultant-nx, resultant-nxy, resultant-ny, resultant-qx, resultant-qy, stress-xx, stress-xy, stress-xz, stress-yy, stress-yz
and stress-zz.
component-id i
depth-factor f
node i
position v
side i
specifies the side of an embedded liner from which to retrieve coupling values. By default, this is side 1.
surface-x v
structure liner import command

Syntax
structure liner import keyword
Primary keywords:
Create elements from the geometry file s
Keyword Block
The following keywords may be optionally provided on liner creation using any of the major keywords: from-file and from-geometry.
distinct
id i
controls potential joining of the element nodes to an existing element as follows. At each potential new node location, a new node is created unless all of
group s1 <slot s2 >
cross-diagonal 
structural elements is printed by the structure liner list element-type command. The value of the keyword supplied must be one of the following
cst
csth
dkt
dkt-cst
membrane loading.
dkt-csth
embedded
Specify that this liner is two-sided. If the embedded keyword is used, then the internal keyword is implied, even if not explicitly given.
internal
maximum-length f
segments i
separate <origin v >
Select a group of internal faces and separate them into surfaces as with the zone separate command. A liner will be created set between the two surfaces.
This keyword implies both embedded and internal. The origin point v is used to determine which side of the faces selected will be considered side 1 and
which will be side 2. The vector from v to the face centroid is compared with the normal to the face. The side pointing toward v will be side 1, and the side
pointing away from v will be side 2. If the origin keyword is not specified, it is assumed to be (0,0,0).
size i1 i2
structure liner initialize command

Syntax
structure liner initialize <keyword>
Primary keywords:
coupling
coupling
structure liner list command

Syntax
structure liner list keyword
Primary keywords:
apply | coupling-normal | coupling-shear | depth-factor | element-type | group | information | force-node | property | resultant | stress | stress-principal | system-local
List properties and responses of each liner element in the range.
apply
coupling-normal
information about the normal coupling springs connecting the liner to the zones. The confining stress, displacement, and direction is given.
coupling-shear
information about the shear coupling springs connecting the liner to the zones. The confining stress, displacement, yield state, and direction is given.
depth-factor
element-type
group <slot s >
information
force-node keyword
local
global
property
density
density, ρ
thickness
liner thickness
thermal-expansion
anisotropic membrane material-stiffness coefficients {c'11, c'12, c'13, c'22, c'23, c'33}
anisotropic-bending
anisotropic bending material-stiffness coefficients {c'11, c'12, c'13, c'22, c'23, c'33}
anisotropic-both
anisotropic bending and membrane material-stiffness coefficients {c'11, c'12, c'13, c'22, c'23, c'33}
material-x
material property type: isotropic, orthotropic, or anisotropic
isotropic
orthotropic-bending
orthotropic-both
coupling-cohesion-shear
coupling-cohesion-shear-2
coupling spring cohesion (stress units) on side 2
coupling-cohesion-shear-residual
coupling-cohesion-residual-2
coupling spring cohesion (stress units) on side 2
coupling-friction-shear
coupling-friction-shear-2
coupling spring friction angle (degrees) on side 2
coupling-stiffness-normal
coupling-stiffness-normal-2
coupling spring stiffness per unit area on side 2
coupling-stiffness-shear
coupling-stiffness-shear-2
coupling spring stiffness per unit area on side 2
coupling-yield-normal
normal coupling spring tensile strength
coupling-yield-normal-2
normal coupling spring tensile strength on side 2
slide
slide-tolerance
effective
the effective stress flag for computing coupling normal stress
resultant <nodes>
all eight stress resultant quantities last calculated with the structure liner recover resultants command. If the nodes keyword is given, the values of these
quantities is supplied at each node of the element, in addition to the value at the element centroid.
stress <nodes>
the stress state calculated with the structure liner recover stress command. If the nodes keyword is given, the values of these quantities is supplied at
principal stresses calculated with the structure liner recover stress command. If the nodes keyword is given, the values of these quantities is supplied at
system-local
structure liner property command

Syntax
structure liner property keyword
Primary keywords:
bending | orthotropic-both | slide | slide-tolerance | coupling-yield-normal | coupling-yield-normal-2 | coupling-stiffness-normal | coupling-stiffness-normal-2 | coupling-
stiffness-shear | coupling-stiffness-shear-2 | coupling-cohesion-shear | coupling-cohesion-shear-2 | coupling-cohesion-shear-residual | coupling-cohesion-shear-residual-
2 | coupling-friction-shear | coupling-friction-shear-2 | effective
Assigns a property to elements in the range. The element can have isotropic, orthotropic, or anisotropic elastic material properties. Note that if the liner is embedded,
then coupling spring properties must be entered separately on side 2. The following properties are available:
density f
thickness f
liner thickness
thermal-expansion f
anisotropic membrane material properties {c'11, c'12, c'13, c'22, c'23, c'33} [F/L2], which define membrane material-stiffness matrices [E'm] and [E'b],
respectively, in the material directions x', y', z'
anisotropic bending material properties {c'11, c'12, c'13, c'22, c'23, c'33} [F/L2], which define bending material-stiffness matrices [E'm] and [E'b], respectively, in
the material directions x', y', z'
anisotropic membrane and bending material properties {c'11, c'12, c'13, c'22, c'23, c'33} [F/L2], which define membrane and bending material-stiffness matrices
[E'm] and [E'b], respectively, in the material directions x', y', z'
material-x v
specify the vector v whose projection onto the geogrid surface defines the xʹ-axis of the material coordinate system. The material directions correspond with the
principal directions of orthotropy (for more information, see below).
isotropic f1 f2
isotropic material properties: E and v where E is Young’s modulus [F/L2] and v is Poisson’s ratio
orthotropic membrane material properties { c'11, c'12, c'22, c'33 } [F/L2], which define membrane material-stiffness matrices [ E'm ] and [ E'b ], respectively, in
the material directions x', y', z'.
orthotropic bending material properties { c'11, c'12, c'22, c'33 } [F/L2], which define bending material-stiffness matrices [ E'm ] and [ E'b ], respectively, in the
orthotropic membrane and bending material properties { c'11, c'12, c'22, c'33 } [F/L2], which define membrane and bending material-stiffness matrices [ E'm ]
and [ E'b ], respectively, in the material directions x', y', z'.
slide b
slide-tolerance f
coupling-yield-normal f
normal coupling spring tensile strength (stress units)
coupling-yield-normal-2 f
normal coupling spring tensile strength on side 2 (stress units)
coupling-stiffness-normal f
normal coupling spring stiffness per unit area
coupling-stiffness-normal-2 f
normal coupling spring stiffness per unit area on side 2
shear coupling spring stiffness per unit area
coupling-stiffness-shear-2 f
shear coupling spring stiffness per unit area on side 2
shear coupling spring cohesion (stress unit)
coupling-cohesion-shear-2 f
shear coupling spring cohesion (stress unit) on side 2
coupling-cohesion-shear-residual f
shear coupling spring residual cohesion
coupling-cohesion-shear-residual-2 f
shear coupling spring residual cohesion on side 2
shear coupling spring friction angle (degrees)
coupling-friction-shear-2 f
shear coupling spring friction angle (degrees) on side 2
effective b
effective stress flag (default to on). If off, then pore-pressures are not removed from the stress normal to the liner when determining shear failure limits.
local system do not change (the angle β in this figure does not change). If the material x-vector is not specified, then the xʹ-axis will be aligned with the x-axis of
The material coordinate system can be queried with the command structure liner list property material-x and the FISH function struct.shell.beta.
It can be visualized with the structural geometry plot item by choosing the corresponding System attribute.
structure liner recover command

Syntax
structure liner recover keyword
Primary keywords:
Stress recovery for liner elements. The stress-recovery procedure can be applied to all elements to compute both the stress resultants and the stresses acting at a
resultants <range>
and membrane stress resultants (Mx, My, Mxy, Nx, Ny, and Nxy) vary linearly over each element, whereas the transverse-shear stress resultants (Qx and Qy ) are
contributions from each linerSEL in the range), and then spatially differentiates this average bending field over each element to obtain the transverse-shear stress
resultants.
Stress resultants can be queried after recovery with the command structure liner list resultant and the FISH function struct.shell.resultant. The
shell thickness. The depth factor, v, must be in the range [-1, +1]. v equal to +1/-1 corresponds with the outer/inner shell surface (outer surface defined by positive
surface system z-direction), and v equal to zero corresponds with the shell mid-surface. If v is not specified, it defaults to +1.
Stresses are recovered at the three nodal points and centroid of each element. If we designate the shell mid-surface by xy-axes, then 1) stress components sxx,
syy, and sxy vary linearly over each element, 2) stress components szy and szx are constant over each element, and 3) szz = 0 over each element. The stresses are
derived from the internal element forces (see structure liner list force-node). If the stress resultants are not valid when this command is executed, then an
attempt is first made to recover them. If this attempt fails, then an error message is displayed indicating the problem—usually the inconsistency of the surface
system, which must then be established manually using the structure liner recover surface command (see next).
Stresses and principal stresses can be queried after recovery with the commands structure liner list stress and structure liner list stress-
be queried with the structure liner list depth-factor and the FISH function struct.shell.depth.factor. The validity of the stresses and principal
surface v
the vector v enables a surface coordinate system to be generated for all nodes used by the elements in the optional range. The surface coordinate system, x' y' z',
has the following properties: 1) z' is normal to the surface; 2) x' is the projection of the given vector onto the surface; and 3) y' is orthogonal to x' and z'. The z'-
direction is found at each node by taking the average normal direction of all elements in the range. If surface v is aligned with z' at any node, then processing
The surface coordinate system can be queried with structure liner list system-local and the FISH function struct.node.system.surface. It can also
be set for an individual node with the FISH function struct.node.system.local. It can be visualized with the liner plot item by choosing the corresponding
System attribute.
The surface system at a node automatically becomes invalid under the following conditions: 1) large-strain update; or 2) creation or deletion of an element that
uses the node. Validity must be re-established with the command structure liner recover surface.
structure liner refine command

Syntax
structure liner refine i <range>
this command refines elements in the range by subdividing them by a factor of i. A triangular element refined by i = 2 will yield four triangular elements; i
= 3 would yield 16 triangular elements, etc. The original element is deleted.
structure liner select command

Syntax
structure liner select <keyword>
Primary keywords:
b | new | undo
new
undo
this will reverse the operation of the last structure liner select command. FLAC3D keeps a maximum undo stack of size 12.
FISH Functions
FISH functions operating on structural liners. The type specifiers used in the FISH function signatures are given in the FISH Type Index section.
Note that all shell functions may also be used on liner elements.
struct.liner.embedded(STRUCT_LINER_PNT)
Get the embedded flag.
struct.liner.normal.dir(STRUCT_LINER_PNT,INT<,INT>)
struct.liner.normal.disp(STRUCT_LINER_PNT,INT)
Get the displacement magnitude in the normal coupling spring at...

struct.liner.normal.stiffness(STRUCT_LINER_PNT<,INT>)
Get/set the normal coupling spring stiffness of the liner element.
struct.liner.normal.strength(STRUCT_LINER_PNT<,INT>)
Get/set the normal coupling spring tensile strength of the liner...
struct.liner.normal.stress(STRUCT_LINER_PNT,INT)
Get the stress magnitude in the normal coupling spring at...
struct.liner.shear.cohesion(STRUCT_LINER_PNT<,INT>)
Get/set the shear coupling spring cohesion of the liner element.
struct.liner.shear.dir(STRUCT_LINER_PNT,INT<,INT>)
struct.liner.shear.disp(STRUCT_LINER_PNT,INT)
Get the displacement magnitude in the shear coupling spring at...
struct.liner.shear.friction(STRUCT_LINER_PNT<,INT>)
Get/set the shear coupling spring friction angle of the liner...
struct.liner.shear.residual(STRUCT_LINER_PNT<,INT>)
Get/set the shear coupling spring residual cohesion of the liner...
struct.liner.shear.state(STRUCT_LINER_PNT,INT)
struct.liner.shear.stiffness(STRUCT_LINER_PNT<,INT>)
Get/set the shear coupling spring stiffness of the liner element.
struct.liner.shear.stress(STRUCT_LINER_PNT,INT)
Get the stress magnitude in the shear coupling spring at...
struct.liner.slide(STRUCT_LINER_PNT)
struct.liner.slide.tol(STRUCT_LINER_PNT)
Get/set the shear coupling spring slide tolerance of the liner...
l struct.liner.embedded
l struct.liner.normal.dir
l struct.liner.normal.disp
l struct.liner.normal.stiffness
l struct.liner.normal.strength
l struct.liner.normal.stress
l struct.liner.shear.cohesion
l struct.liner.shear.dir
l struct.liner.shear.disp
l struct.liner.shear.friction
l struct.liner.shear.residual
l struct.liner.shear.state
l struct.liner.shear.stiffness
l struct.liner.shear.stress
l struct.liner.slide
l struct.liner.slide.tol
struct.liner.embedded
Syntax
b = struct.liner.embedded(p)
Get the embedded flag. A value true denotes that the liner element is embedded.
Returns: b - a boolean flag to denote whether the liner element is embedded

Arguments: p - a pointer to the structure liner element
struct.liner.normal.dir
Syntax
Vector Access
v = struct.liner.normal.dir(p,inode<,i>)
Get the direction (unit vector in global system) in which the liner element is being loaded by the normal coupling spring at node inode (inode ∈ {1, 2, 3}). Returns a
vector, unless an optional component argument i is supplied, in which case it returns the component value.

Arguments: p - a pointer to a liner element
Component Access
f = struct.liner.normal.dir.x(p,in)
Get the x-component of the direction (unit vector in global system) in which the liner element is being loaded by the normal coupling spring at node inode (inode ∈ {1,
2, 3}).

f = struct.liner.normal.dir.y(p,iend)
Get the y-component of the direction (unit vector in global system) in which the liner element is being loaded by the normal coupling spring at node inode (inode ∈ {1,
2, 3}).

f = struct.liner.normal.dir.z(p,iend)
Get the z-component of the direction (unit vector in global system) in which the liner element is being loaded by the normal coupling spring at node inode (inode ∈ {1,
2, 3}).

struct.liner.normal.disp
Syntax
f = struct.liner.normal.disp(p,inode)
Get the displacement magnitude in the normal coupling spring at node inode (inode ∈ {1, 2, 3}). The coupling spring lies in the tangent plane of the liner surface. The
direction in which force is acting is given by struct.liner.normal.dir.

struct.liner.normal.stiffness
Syntax
f = struct.liner.normal.stiffness(p<,i>)
struct.liner.normal.stiffness(p<,i>) = f

Accepts: f - the normal coupling spring stiffness of the element
i - optional side indicator. 1 or 2. The default value is 1.
struct.liner.normal.strength
Syntax
f = struct.liner.normal.strength(p<,i>)
struct.liner.normal.strength(p<,i>) = f
Get/set the normal coupling spring tensile strength of the liner element.
Returns: f - the normal coupling spring tensile strength of the element

Accepts: f - the normal coupling spring tensile strength of the element
struct.liner.normal.stress
Syntax
f = struct.liner.normal.stress(p,inode)
Get the stress magnitude in the normal coupling spring at node inode (inode ∈ {1, 2, 3}). The coupling spring lies in the tangent plane of the liner surface. The direction
in which force is acting is given by struct.liner.normal.dir.

struct.liner.shear.cohesion
Syntax
f = struct.liner.shear.cohesion(p<,i>)
struct.liner.shear.cohesion(p<,i>) = f
Returns: f - the shear coupling spring cohesion of the element

Accepts: f - the shear coupling spring cohesion of the element
struct.liner.shear.dir
Syntax
Vector Access
v = struct.liner.shear.dir(p,inode<,i>)
Get the direction (unit vector in global system) in which the liner element is being loaded by the shear coupling spring at node inode (inode ∈ {1, 2, 3}). Returns a
vector, unless an optional component argument i is supplied, in which case it returns the component value.

Component Access
f = struct.liner.shear.dir.x(p,in)
Get the x-component of the direction (unit vector in global system) in which the liner element is being loaded by the shear coupling spring at node inode (inode ∈ {1, 2,
3}).

f = struct.liner.shear.dir.y(p,iend)
Get the y-component of the direction (unit vector in global system) in which the liner element is being loaded by the shear coupling spring at node inode (inode ∈ {1, 2,
3}).

f = struct.liner.shear.dir.z(p,iend)
Get the z-component of the direction (unit vector in global system) in which the liner element is being loaded by shear coupling spring at node inode (inode ∈ {1, 2, 3}).

struct.liner.shear.disp
Syntax
f = struct.liner.shear.disp(p,inode)
Get the displacement magnitude in the shear coupling spring at node inode (inode ∈ {1, 2, 3}). The coupling spring lies in the tangent plane of the liner surface. The
direction in which force is acting is given by struct.liner.shear.dir.

struct.liner.shear.friction
Syntax
f = struct.liner.shear.friction(p<,i>)
struct.liner.shear.friction(p<,i>) = f
Get/set the shear coupling spring friction angle of the liner element.
Returns: f - the shear coupling spring friction angle of the element

Accepts: f - the shear coupling spring friction angle of the element
struct.liner.shear.residual
Syntax
f = struct.liner.shear.residual(p<,i>)
struct.liner.shear.residual(p<,i>) = f
Get/set the shear coupling spring residual cohesion of the liner element.
Returns: f - the shear coupling spring residual cohesion of the element

Accepts: f - the shear coupling spring residual cohesion of the element
struct.liner.shear.state
Syntax
i = struct.liner.shear.state(p,inode)
Get the yield state of the coupling spring at node inode (inode ∈ {1, 2, 3}). Return a value i ∈ {1, 2, 3} denotes never yielded, yielding now, or yielded in the past,
respectively.
Returns: i - yield state, i ∈ {1, 2, 3} denotes never yielded, yielding now or yielded in past, respectively
struct.liner.shear.stiffness
Syntax
f = struct.liner.shear.stiffness(p<,i>)
struct.liner.shear.stiffness(p<,i>) = f

Accepts: f - the shear coupling spring stiffness of the element
struct.liner.shear.stress
Syntax
f = struct.liner.shear.stress(p,inode)
Get the stress magnitude in the shear coupling spring at node inode (inode ∈ {1, 2, 3}). The coupling spring lies in the tangent plane of the liner surface. The direction
in which force is acting is given by struct.liner.shear.dir.

struct.liner.slide
Syntax
b = struct.geogrid.slide(p)
struct.liner.slide(p) = b
Get/set the large-strain sliding flag. A true value denotes that the large-strain sliding is on.
Returns: b - large-strain sliding flag

Accepts: b - large-strain sliding flag
struct.liner.slide.tol
Syntax
f = struct.liner.slide.tol(p)
struct.liner.slide.tol(p) = f
Get/set the shear coupling spring slide tolerance of the liner element.
Returns: f - the shear coupling spring slide tolerance of the element

Accepts: f - the shear coupling spring slide tolerance of the element
General Formulation of Structural-Element Logic

The low-level implementation details of the structural-element logic are presented here. This information need only be read by users interested in gaining a thorough
understanding of the implementation (perhaps, in order to implement nonstandard interaction between structural elements and the grid). The structural-element logic has been
developed in a general and flexible fashion in order to support various (as yet unforeseen) application scenarios.
Structural-Element Links
Structural elements only interact with one another via nodes; and nodes, in turn, only interact with the grid via links. Thus, structural-element links provide the sole means by
which structural elements interact with the grid. Each link connects a node to a target entity. Each node may only have one link associated with itself. There are two types of
links: (1) node-to-zone, which connect nodes to zones (not simply to gridpoints); and (2) node-to-node, which connect nodes to other nodes.
In addition to localizing the interaction between structural elements and the grid, links also provide a general mechanism for implementing nonlinear constitutive behavior at a
node, in terms of that node's local coordinate system. A link supports the following three attachment conditions, which are specified independently for each local direction of
its source node:
1. free Velocity of the source node in this local direction is unrelated to the velocity of the target entity.
2. rigid Velocity of the source node in this local direction is slaved to remain equal to the component of the velocity of the target entity in this direction (see
Figure 1).
{\bf n}^
3. deformable Denote the attachment direction by {[{\rm S}]} . The source node and target entity are connected by a spring oriented in the direction
{\bf n}^
{[{\rm S}]} . The spring stiffness is an average stiffness per unit area associated with the link (see Figure 2).
../../../../../../_images/rigid-
attachment.png
Figure 1: Physical analog of a rigid attachment condition
../../../../../../_images/deformable-
attachment.png
Figure 2: Physical analog of a deformable attachment condition
Deformable attachment conditions allow generalized constitutive models, which relate increments of displacement and total force in a particular local direction, to be included
in the model. There are a total of five such models used to implement the grid interactions of cables, piles, geogrids and liners (see Table 1). Only the linear and normal-yield
springs are available for general use (see the structure link attach command). A normal-yield spring can be used to introduce plastic hinges between beam elements or
pile elements (see Plastic Hinge Formation in a Beam Structure), and plastic-hinge lines along edges between shell-type elements (see Plastic Hinge Formation in a Shell
Structure). The normal-yield spring provides elastic perfectly plastic behavior in both tension and compression, as well as the ability to track the formation of a gap that may
form during yield in each direction.
Table 1: Default link attachment conditions for element types

DOF beam cable pile shell geogrid liner
1 rigid SY SY rigid PY PY
2 rigid rigid PY rigid PYDP PYDP
3 rigid rigid PYDP rigid rigid NY
4 free free free free free free
In Table 1, the symbols are defined as follows. "Rigid" means rigidly connected to the zone in which the element is embedded; "free" means that there is no connection in this
degree of freedom. SY means shear-yield spring. PY and PYDP mean pile-yield and pile-yield dependent springs, which act together to produce the behavior of a single
nonlinear spring acting in the plane defined by these two directions. NY means normal-yield spring. The nonlinear spring behaviors are not described here; instead, the overall
element-to-grid interaction behavior of each element type that uses these springs is described in its own section.
A plastic hinge may be introduced between two nodes by creating a node-to-node link between the two nodes, aligning the node-local system for the target node such that a
normal-yield spring can be inserted in the direction of the axis about which the hinge is to rotate, while all other directions are kept free (see Plastic Hinge Formation in a
Beam Structure and Plastic Hinge Formation in a Shell Structure). The properties of the normal-yield spring should be set:
1. Set the area equal to unity, and set the stiffness per unit area approximately ten times larger than the stiffness of the structural components using the node.
2. Set the compressive- and tensile-yield strengths equal to the plastic-moment capacity (for beams and piles), or plastic-moment capacity per unit length (for
shell-type elements).
The orientation of the node-local system is set automatically at the start of a set of cycles (or when the model cycle 0 command is executed), based on the type of elements
that use the node (see Structural Element Nodes). When using the element creation commands (structure shell create etc.), if any of the nodes making up the newly
created elements lie within zones, then node-to-zone links will be created and assigned the default attachment conditions shown in Figure 1:
Element-to-grid interaction occurs via node-to-zone links. These links store the zone, and an interpolation location within the zone, to allow transfer of forces and velocities
between the nodes and the zones. By default, these interpolation locations will not change, even if running in large-strain mode. The interpolation locations can be allowed to
migrate through the grid by setting the large-strain sliding flag of the link to on. Typically, one sets this flag to on for cables, piles, geogrids and liners, which then
automatically set the flag to on for all links used by these elements. The migration process employs the large-strain sliding tolerance (see the tolerance options available to the
structure link command).
Finite Element Stiffness Matrices

The structural response of each structural element is described by the stiffness that it provides to the surrounding system by means of its nodes. Each structural element has an
[
associated stiffness matrix that is formed using finite-element techniques. The stiffness matrix \ relates generalized nodal displacements (translations and rotations)
\{\ \{\b \{ {\bf F} \} = [{\bf k}] \{ {\bf [
bfto generalized nodal forces (forces and moments) by means of the relation
fF d} \} , in which \ is a square symmetric matrix
of a size equal to the number of degrees of freedom associated with the finite element.
Six finite-element stiffness matrices have been implemented in FLAC3D: a 2-noded beam finite element, and five 3-noded shell finite elements. These stiffness-matrix
formulations are described in the following two subsections. Beam elements and pile elements utilize the beam finite element; cable elements utilize a degenerate form of the
beam finite element in which only the local axially directed degrees-of-freedom are employed; and, shell elements, geogrid elements and liner elements utilize different shell
finite elements. Note that the elements-to-grid interaction occurs by means of the links which connect the nodes used by elements to the zones.
Beam Finite Element
The beam finite element in FLAC3D is a two-noded, straight, finite element with six degrees of freedom per node: three translational components and three rotational
components (see Beam Sign Convention). The beam finite element stiffness matrix formulation is given in explicit form by McGuire and Gallagher (1979, pp. 81-91). The
element models the structural behavior of a beam that is straight, prismatic and symmetrical about both principal cross-sectional axes (bisymmetrical), and composed of
isotropic material. The formulation considers displacements resulting from uniform axial deformation, flexural deformation, and twisting deformation. It neglects
displacements resulting from transverse-shearing deformations, and displacements resulting from the out-of-plane (longitudinal) warping of a cross section that torsional
forces may cause. According to McGuire and Gallagher, the equations embodied by the resulting stiffness matrix are sufficient for the analysis of the large majority of the
frameworks encountered in structural-engineering practice.
Shell Finite Elements
There are five 3-noded, triangular finite elements available for shell-type elements: 2 plane-stress elements, 1 plate-bending element and 2 shell elements. The plane-stress
elements model membrane action only, the plate-bending element models bending action only, and the shell elements model general shell behavior as a superposition of
membrane and bending actions (see Bending Action and Membrance Action). These elements operate upon the 18 degrees of freedom available to the shell-type elements (see
Shell-Type Coordinate System).
CST Plane-Stress Element (6 degrees of freedom)
The CST plane-stress element is a three-noded plane-stress finite element with two translational degrees-of-freedom per node (shown in Figure Figure #sel-
[{\bf k}_{\rm
dkt-cst-element (a) by removing the rotational degree-of-freedom). The CST hybrid element is described, and an explicit formulation of CST}] is
given by Cook et al. (1989).
CST Hybrid Plane-Stress Element (9 degrees of freedom)
The CST hybrid plane-stress element is a three-noded plane-stress finite element with three degrees of freedom per node: two translational components and one
rotational component (shown in Figure Figure #sel-dkt-cst-element (a)). The CST hybrid plane-stress element is formulated by the assumed-stress hybrid
\th
approach. It provides a more competent membrane response than a constant strain triangle (CST) through the inclusion of "drilling freedoms," eta , among
[{\bf k}_{\rm
its degrees of freedom. The CST hybrid element is described, and an explicit formulation of CSTH}] is given by Cook (1987).
DKT Plate Bending Element (9 degrees of freedom)
The DKT plate bending element is a three-noded plate finite element with three degrees of freedom per node: one translational component and two rotational
components (shown in Figure Figure #sel-dkt-cst-element (b)). The DKT plate bending element enforces the Kirchhoff plate theory assumptions at six
discrete locations (corners and mid-sides) within the element; thus, the designation DKT for Discrete Kirchhoff Triangle. The element is described by Batoz et al.
(1980), who conclude that it is one of the most efficient and reliable three-node (9 degrees of freedom) plate bending elements available at the time of publication.
[{\bf k}_{\rm
An explicit formulation of DKT}] is given by Batoz (1982).
DKT-CST Hybrid Shell Element (18 degrees of freedom)
The DKT-CST hybrid shell element is a three-noded, flat, thin-shell finite element with six degrees of freedom per node: three translational components and three
rotational components. It combines a nine degrees-of-freedom CST hybrid plane element to model membrane action in the shell with a nine degrees-of-freedom
DKT plate element to model bending action in the shell. This composite flat shell element is referred to as a DKT-CST hybrid, and is described by Cook et al.
(1989, pp. 351-352).
Let a typical element lie in the xy-plane of a local coordinate system xyz. Nodal degrees-of-freedom are shown in Figure Figure #sel-dkt-cst-element,
\lfloor \theta_x \quad \theta_y \rfloor = \lfloor {\partial w \over \partial y} \quad -{\partial w \over \partial x} \{{\bf
where \rfloor
. Let these degrees of freedom be called d'} \} , and be arranged
in the order
\begin{Bmatrix} {\bf d^{\prime}} \end{Bmatrix} =

{\lfloor {\bf u}_i \; {\bf v}_i \; {\bf \theta}_{zi} \; {\bf w}_i \; {\bf \theta}_{xi} \; {\bf \theta}_{yi}
\lfloor {\bf u}_i \rfloor = \lfloor u_1\quad u_2 \quad u_3 \lfloor {\bf\theta}_{xi} \rfloor = \lfloor \theta_{x1}\quad \theta_{x2} \quad \theta_{x3}
where \rfloor , \rfloor , and so on. For the DKT-CST hybrid
[{\
shell element, whose stiffness matrix in local xyz-coordinates is called bf , we have
\begin{bmatrix} {\bf k^{\prime}} \end{bmatrix} \begin{Bmatrix} {\bf d^{\prime}} \end{Bmatrix} =

\begin{bmatrix} \begin{matrix} \begin{bmatrix} {\bf k}_{CSTH} \end{bmatrix} \\
9\times 9 \end{matrix} &
\begin{matrix} \begin{bmatrix} {\bf 0} \end{bmatrix} \\
9\times 9 \end{matrix} \\
\begin{matrix} \begin{bmatrix} {\bf k}_{DKT} \end{bmatrix} \\
9\times 9 \end{matrix} \end{bmatrix}
\begin{Bmatrix} {\bf u}_i \\ {\bf v}_i \\ {\bf \theta}_{zi} \\ {\bf w}_i \\ {\bf \theta}_{xi} \\ {\bf \theta}_{yi} \end
(1)
[{\bf k}_{\rm [{\bf k}_{\rm

where CSTH}] is the stiffness matrix of a CST hybrid plane-stress element, and DKT}] is the stiffness matrix of a DKT plate-bending
element.
The following observations about the DKT-CST hybrid element are appropriate (also see the observations about the DKT-CST element in the next section).
[{\bf k}_{\rm [{\bf k}_{\rm

1. CSTH}] only contains degrees of freedom associated with membrane action, and DKT}] only contains degrees of
freedom associated with bending action. Although membrane-bending coupling is present throughout an actual curved shell, it is absent in an
individual element (as evidenced by the 9 by 9 null matrices of (1)). Nevertheless, the element works well enough to be competitive with
curved elements, as demonstrated by Carpenter et al. (1986).
2. The element provides a solution which converges to the classical Kirchhoff thin-plate solution. Thus, the element is appropriate for modeling
thin shells in which the displacements caused by transverse-shearing deformations can be neglected.
../../../../../../_images/dkt-cst-
element.png
Figure 3: DKT-CST hybrid flat shell finite element in a local xy-plane: (a) degrees of freedom associated with membrane action (CST hybrid sub-element); (b)
degrees of freedom associated with bending action (DKT sub-element)
DKT-CST Shell Element (15 degrees of freedom)
The DKT-CST shell element is a three-noded, flat, thin-shell finite element with five degrees of freedom per node: three translational components and two
rotational components. It combines a six degrees-of-freedom CST plane element to model membrane action in the shell with a nine degrees-of-freedom DKT
plate element to model bending action in the shell. This composite flat shell element is referred to as a DKT-CST, and is described by Cook et al. (1989, pp. 351-
352).
Let a typical element lie in the xy-plane of a local coordinate system xyz. Nodal degrees-of-freedom are shown in Figure Figure #sel-dkt-cst-element by
\th \lfloor \theta_x \quad \theta_y \rfloor = \lfloor {\partial w \over \partial y} \quad -{\partial w \over \partial x}
removing eta , where \rfloor
. Let these degrees of freedom be called
\{{\bf
d^\star} \} , and be arranged in the order
\begin{Bmatrix} {\bf d^{\star}} \end{Bmatrix} =

{\lfloor {\bf u}_i \, {\bf v}_i \, {\bf w}_i \, {\bf \theta}_{xi} \, {\bf \theta}_{yi}
where $lfloor {bf u}_i rfloor = lfloor u_1quad u_2 quad u_3 rfloor$, $lfloor {ubmtheta}_{xi} rfloor = lfloor theta_{x1}quad theta_{x2} quad theta_{x3} rfloor$,
and so on. For the DKT-CST shell element, whose stiffness matrix in local $xyz$-coordinates is called $[{bf k^star}]$, we have
\begin{bmatrix} {\bf k^{\prime}} \end{bmatrix} \begin{Bmatrix} {\bf d^{\star}} \end{Bmatrix}

=
\begin{bmatrix} \begin{matrix} \begin{bmatrix} {\bf k}_{CST} \end{bmatrix} \\
6\times 9 \end{matrix} \\
\begin{matrix} \begin{bmatrix} {\bf k}_{DKT} \end{bmatrix} \\
9\times 9 \end{matrix} \end{bmatrix}
(2)
[{\bf k}_{\rm [{\bf k}_{\rm

where CST}] is the stiffness matrix of a CST plane-stress element, and DKT}] is the stiffness matrix of a DKT plate bending element.
The following observations about the DKT-CST element are appropriate.
[{\bf k}_{\rm [{\bf k}_{\rm

1. CST}] only contains degrees of freedom associated with membrane action, and DKT}] only contains degrees of
freedom associated with bending action. Although membrane-bending coupling is present throughout an actual curved shell, it is absent in an
individual element (as evidenced by the null matrices of (2).
2. The element provides a solution which converges to the classical Kirchhoff thin-plate solution. Thus, the element is appropriate for modeling
thin shells in which the displacements caused by transverse-shearing deformations can be neglected.
3. The element differs from the DKT-CST hybrid element by not having drilling degrees-of-freedom. This makes the element overly stiff for
problems with large membrane-stress gradients. For such problems, the DKT-CST hybrid element will perform better. For problems without
large membrane-stress gradients, the performance of the DKT-CST element will be much improved, making it competitive with the DKT-CST
hybrid element.
4. The lack of drilling degrees-of-freedom makes this element more suitable for coupling with the FLAC3D grid than the DKT-CST hybrid
element. The FLAC3D zones have a linear displacement variation, and the 3 drilling degrees-of-freedom give the DKT-CST hybrid a quadratic
in-plane displacement variation along its edges. When a shell-type element is rigidly connected to the grid, only the translational degrees-of-
freedom are slaved to move with the grid, while the rotational degrees-of-freedom are left free. Because we are not constraining the drilling
degrees-of-freedom, it is possible for gaps to form between the element and the grid. These incompatibilities seem to be activated when shell-
type elements of different sizes meet along a common line. The DKT-CST element has a linear in-plane displacement variation along its edges,
which is fully compatible with that of the FLAC3D zones and, thus, gaps cannot form when these elements are rigidly connected to zones.
5. The two preceding observations lead to the following general recommendation regarding choice of shell finite element. For problems in which
a shell element is being connected to FLAC3D zones, use the DKT-CST element. For all other problems, use the DKT-CST hybrid element.
Stress Recovery Procedure

The stress-recovery procedure is outlined in Stress Recovery Procecure. A more detailed description of the process is provided here. Stress recovery is applied to a group of
shell-type elements. Nodal averaging of bending and membrane stress resultants only occurs for elements within this group. Stress recovery consists of two steps:
1. Compute stress-resultant field.
1a. Define the surface coordinate system at each node.
This system has its z-direction equal to the average z-direction of all shell-type elements using the node, and has its x-direction equal to the projection
of a user-specified surface vector onto the z-plane.
1b. Compute the bending and membrane stress resultants
(Mx, My, Mxy, Nx, Ny, and Nxy) at each node. These values are found by first computing them within each shell-type element at its nodes, and then
averaging the contributions from all shell-type elements that use each node. Note that these six stress resultants vary linearly over each element.
The bending and membrane stress resultants within each shell-type element are found using the flexibility-stiffness transformation from McGuire and
Gallagher (1979, pp. 76-77) to determine which displacements are consistent with a given set of nodal forces acting on the element. This is done by
forming a flexibility matrix that is derived from the element stiffness matrix. The flexibilities are derived from the stiffnesses by defining a stable,
statically determinate support system, removing from the stiffness matrix the rows and columns corresponding to the support components, and
inverting the remainder. These displacements are then fed into stress-recovery procedures appropriate to the particular finite element.
1c. Compute the transverse-shear stress resultants (Qx and Qy)
within each shell-type element by enforcing the equilibrium equations
Q_x = {\partial M_x \over \partial x} + {\partial M_{xy} \over

\partial y}
by assuming that the bending resultant field varies linearly over each element. Note that Qx and Qy are constant over each shell-type element, and are
not averaged at nodes.
2. Compute stress field at specified shell depth using Stresses From Resultants, and then rotating the stresses into the global system.
Governing Equations
The discretization and time integration of the equations that govern the dynamic response of the structural elements and their associated entities (i.e., nodes and links) utilize
standard finite-element practice. The description given here is similar to that given in Chapter 13 of Cook et al. (1989).
The equations that govern the dynamic response of a structure can be derived by requiring the work of external forces to be absorbed by the work of internal, inertial and
damping forces for any small, kinematically admissible motion. For a single element, this work balance becomes
\int_{V_e} \begin{Bmatrix} \delta {\bf u} \end{Bmatrix}^T \begin{Bmatrix} {\bf F} \end{Bmatrix} dV +

\int_{S_e} \begin{Bmatrix} \delta {\bf u} \end{Bmatrix}^T \begin{Bmatrix} {\bf \Phi} \end{Bmatrix} dS +\
\sum_{i=1}^n \begin{Bmatrix} \delta {\bf u} \end{Bmatrix}_i^T \begin{Bmatrix} {\bf p} \end{Bmatrix}_i
&= \int_{V_e} \bigg( \begin{Bmatrix} \delta {\bf \epsilon} \end{Bmatrix}^T \begin{Bmatrix} {\bf \sigma} \end
{Bmatrix} +
\begin{Bmatrix} \delta {\bf u} \end{Bmatrix}^T \rho \begin{Bmatrix} {\ddot{\bf u}} \end{Bmatrix} +
(3)
\begin{Bmatrix} \delta {\bf u} \end \begin{Bmatrix} \delta {\bf \epsilon} \end

where {Bmatrix} and {Bmatrix} are, respectively, small arbitrary displacements and their corresponding strains,
\begin{Bmatrix} {\bf F} \end \begin{Bmatrix} {\bf \Phi} \end S
{Bmatrix} are body forces, {Bmatrix} are prescribed surface tractions that act over a portion of the element surface ,
\begin{Bmatrix} {\bf p}_i \end \begin{Bmatrix} {\bf u} \end
{Bmatrix} are concentrated loads that act at a total of n points on the element, {Bmatrix}_i^T is the displacement of the point at
\begin{Bmatrix} {\bf p}_i \end \begin{Bmatrix} {\bf \sigma} \end \ \kap
which load {Bmatrix} is applied, {Bmatrix} are stresses, is the mass density of the material, is a material-
V
damping parameter analogous to viscosity, and volume integration is carried out over the element volume, .
\begin{Bmatrix} {\bf u} \end

If we express the displacement field {Bmatrix} (which is a function of both space and time) and its first two time derivatives as
\{ {\bf u} \} = [{\bf N}] \{ {\bf d} \}

\quad\quad
\{ \dot{\bf u} \} = [{\bf N}] \{ \dot{\bf d} \}
(4)
[{\ \{{\b
where shape functions bf are functions of space only, and nodal degrees-of-freedom f d} are functions of time only, then (4) represent a local separation of
\{ \delta{\bf \{ \delta{\bf
variables. By substituting (4) into (3), and noting that u} \} , and thus d} \} , are arbitrary, one obtains
[{\bf m}] \{ \ddot{\bf d} \} + [{\bf c}] \{ \dot{\bf d} \} + \{ {\bf r}^{\rm int} \} = \{ {\bf r}^{\rm
(5) ext} \}
where the element mass and damping matrices are defined as
[{\bf m}] = \int_{V\!{\scriptscriptstyle e}} \rho [{\bf N}]^T [{\bf

N}]\,dV
[{\bf c}] = \int_{V\!{\scriptscriptstyle e}} \kappa_{\scriptscriptstyle d} [{\bf N}]^T [{\bf

(6) N}]\,dV
and the element internal force and external load vectors are defined as
\begin{Bmatrix} {\bf r}^{int} \end{Bmatrix} =

\int_{V_e} \begin{bmatrix} {\bf B} \end{bmatrix}^T \begin{Bmatrix} {\bf \sigma} \end{Bmatrix}
dV +
\begin{Bmatrix} {\bf r}^{ext} \end{Bmatrix} =

\int_{V_e} \begin{bmatrix} {\bf N} \end{bmatrix}^T \begin{Bmatrix} {\bf F} \end{Bmatrix} dV +
\int_{S_e} \begin{bmatrix} {\bf N} \end{bmatrix}^T \begin{Bmatrix} {\bf \Phi} \end{Bmatrix}
\begin{bmatrix} {\bf B} \end

where {bmatrix} is the strain-displacement matrix that satisfies
\begin{Bmatrix} \delta {\bf \epsilon} \end{Bmatrix} = \begin{bmatrix} {\bf B} \end{bmatrix} \begin{Bmatrix} {\bf d} \end
{Bmatrix} .
(5) is a system of coupled, second-order, ordinary differential equations in time, and is called a finite-element semi-discretization because, although displacements
\begin{bmatrix} {\bf d} \end
{bmatrix} are discrete functions of space, they are still continuous functions of time. The FLAC3D structural-element logic employs an explicit, direct-
integration method which discretizes (5) in time, using the central-difference method to obtain a sequence of uncoupled algebraic equations.
Recall that (5) was written for a single element. Equations for the assembled structural system can be written as
\begin{bmatrix} {\bf M} \end{bmatrix} \begin{Bmatrix} \ddot{\bf D} \end{Bmatrix} +

\begin{bmatrix} {\bf C} \end{bmatrix} \begin{Bmatrix} \dot{\bf D} \end{Bmatrix} =
\begin{Bmatrix} {\bf R}^{ext} \end{Bmatrix} - \begin{Bmatrix} {\bf R}^{int} \end
{Bmatrix} =
(7)
\begin{Bmatrix} {\bf A} \end

where {Bmatrix} designates the accumulated out-of-balance force, and uppercase English alphabet characters designate structure matrices which are
constructed by the conceptual expansion of element matrices to "structure size," followed by addition of overlapping coefficients. See any standard finite-element text (e.g.,
Cook et al. 1989) for a detailed description of the assembly procedure.
The equations of motion, (7), are written for a specific instant of time:
\begin{bmatrix} {\bf M} \end{bmatrix} \begin{Bmatrix} \ddot{\bf D} \end

{Bmatrix}_n +
\begin{bmatrix} {\bf C} \end{bmatrix} \begin{Bmatrix} \dot{\bf D} \end{Bmatrix}
(8)
n\D \D
where subscript n denotes time elta , and elt is the size of the time increment or timestep.
Central-Difference Approximations
n\D (n - {\scriptstyle 1/2}) n\D
The central-difference approximations for acceleration at time elta , velocity at time \Delta t , and velocity at time elta are given by
\{ \ddot{\bf D} \}_n = {1\over\Delta t} \biggl( \{ \dot{\bf D} \}_{n \scriptscriptstyle + 1/2} - \{ \dot{\bf D} \}_{n \scriptscriptstyle - 1/2} \biggr) + O( \Delta
(9) t^2 )
\{ \dot{\bf D} \}_{n \scriptscriptstyle - 1/2} = {1\over\Delta t} \biggl( \{ {\bf D} \}_{n} - \{ {\bf D} \}_{n \scriptscriptstyle - 1} \biggr) + O( \Delta
(10) t^2 )
\{ \dot{\bf D} \}_n = {1\over2} \biggl( \{ \dot{\bf D} \}_{n \scriptscriptstyle - 1/2} + \{ \dot{\bf D} \}_{n \scriptscriptstyle + 1/2} \biggr) + O( \Delta
(11) t^2 )
These expressions are second-order accurate, which implies that halving the timestep should approximately quarter the error in the approximation.
Accumulated Out-of-Balance Force Vector

\begin{Bmatrix} {\bf A} \end{Bmatrix}_n' in :eq:`sel-dom-
The structure internal force vector that makes up one portion of the accumulated out-of-balance force vector discretized is obtained
by assembling the contributions from each structural element and from each deformable direction of each link
\{ {\bf R}^{\rm int} \}_n = \sum_{j} \left( \{ {\bf r}^{\rm int} \}_n
\right)_j
with
\{ {\bf r}^{\rm int} \}_n &= \{ {\bf r}^{\rm int} \}_{n \scriptscriptstyle - 1} + \{ \Delta {\bf r}^{\rm int} \}
= \{ {\bf r}^{\rm int} \}_{n \scriptscriptstyle - 1} + [{\bf k}]_{n \scriptscriptstyle - 1/2} \bigl( \{ {\bf d} \}_n - \{ {\bf d} \}_{n \scriptscriptstyle - 1}
\bigr)
\{ {\bf r}^{\rm
in which the central-difference approximation of (10) has been employed. The internal-force vector int} \} that is maintained by each structural element and each
\{ {\bf R}^{\rm
deformable direction of each link is also updated during the computation of int} \} .
{\bf n}^
After distributing all of the internal forces to the appropriate nodes, each rigidly attached direction, {[{\rm S}]} , of each link contributes the following portion of the
{\bf A}^ {\bf A}^
accumulated out-of-balance force of its source node {[{\rm S}]} to the accumulated out-of-balance force {[{\rm T}]} of its target entity as
{\bf A}^{[{\rm T}]} \leftarrow {\bf A}^{[{\rm T}]} + \left( {\bf A}^{[{\rm S}]} \cdot {\bf n}^{[{\rm S}]} \right) {\bf n}^
{[{\rm S}]}
Mass Matrix
The structure mass matrix in (8) is obtained by utilizing a nodal-lumping scheme, and assembling the contributions from each structural element
[ {\bf M} ] = \lceil {\bf M} \rfloor = \sum_{j=1}^{\rm numel} \lceil {\bf m}

\rfloor_j
with
\lceil {\bf m} \rfloor_j = \begin{cases} \frac{\rho_j V_j}{n_j}, & \text{all 3 translational d.o.f.} \\
\frac{2}{5}\Bigg(\frac{\rho_j V_j}{n_j}\Bigg)\Bigg(\frac{3V_j}{4\pi n_j}\Bigg)^{2/3}, & \text{all 3 rotational d.o.f.} \end
\
where , Vj and nj are the mass density, volume and number of nodes of element j. The rotational inertias are found by assuming that the portion of element mass
seen by each node is distributed as a sphere.
After distributing the mass associated with all of the structural elements to the appropriate nodes, each rigidly attached direction of each link contributes the following portion
m_k^ m_i^
of its source mass in direction- k {[{\rm S}]} to the accumulated mass in target direction- {[{\rm T}]} , using the weighting function
m_i^{[{\rm T}]} \leftarrow m_i^{[{\rm T}]} + m_k^{[{\rm S}]} \left( { \left| {\bf n}_k^{[{\rm S}]} \cdot {\bf n}_i^{[{\rm T}]} \right| \over \sum^3_{l=1} \left| {\bf n}_k^{[{\rm S}]} \cdot {\bf n}_l^{[{\rm T}]} \right| }
(12) \right)
{\bf n}_i^ {\bf n}_i^

where {[{\rm S}]} and {[{\rm T}]} are, respectively, the unit-vector triads of the source and target local coordinate systems.
Damping Formulation
The derivation of equation (6) utilized a viscous-damping parameter that is suitable for modeling a Newtonian fluid; however, when modeling structural systems, we are less
interested in viscous damping than in dry friction and hysteresis loss. These energy-loss mechanisms are not well-understood and, from a practical standpoint, (6) does not
correctly represent structural damping. Thus, three ad hoc damping schemes (local damping, combined local damping and Rayleigh or proportional damping) are provided.
The implementation details of the three damping schemes are presented here; refer to Mechanical Damping and Rayleigh Damping for a description of the rationale behind
each scheme.
The starting point for all three damping schemes is given by rewriting (8) as
[{\bf M}] \{ \ddot{\bf D} \}_n + \{ {\bf R}^{\rm d} \}_n = \{ {\bf

(13) A} \}_n
\{ {\bf R}^{\rm n\D

where d} \}_n represents the force produced by the damping mechanism at time elta .
Local Damping
Substitution of (9) into (13) yields
\{ \dot{\bf D} \}_{n \scriptscriptstyle + 1/2} = \{ \dot{\bf D} \}_{n \scriptscriptstyle - 1/2} + \Delta t [{\bf M}]^{-1} \left( \{ {\bf A} \}_n - \{ {\bf R}^{\rm d} \}_n
(14) \right)
The use of a diagonal mass matrix (as described in Mass Matrix) uncouples this set of equations such that we can rewrite them for a single degree of freedom i as
( \dot D_i )_{n \scriptscriptstyle + 1/2} = ( \dot D_i )_{n \scriptscriptstyle - 1/2} + {\Delta t \over M_i} \left( (A_i)_n - ( R_i^{\rm d} )_n
\right)
Local damping is provided by setting
( R_i^{\rm d} )_n = \lambda_i \> \bigl| (A_i)_n \bigr| \> {\rm sgn} ( \dot
(15) D_i )_n
\lam
where bda_ is the local-damping factor for degree-of-freedom i, and
{\rm sgn}(x) =
\begin{cases} +1, & \text{if} x
\geq 0 \\
(\dot D_i )^ ( \dot D_i )^

The local-damping formulation is implemented by computing an undamped {\rm ud} and a damped {\rm d} new velocity:
( \dot D_i )^{\rm ud} = ( \dot D_i )_{n \scriptscriptstyle - 1/2} + {\Delta t \over M_i} (A_i)_n
( \dot D_i )^{\rm d} = ( \dot D_i )_{n \scriptscriptstyle - 1/2} + {\Delta t \over M_i} \biggl( (A_i)_n - \lambda_i \> | (A_i)_n | \> {\rm sgn} ( \dot D_i )_{n \scriptscriptstyle - 1/2}
and setting the actual new velocity equal to the damped velocity (only if the velocity has not changed sign) as
\begin{pmatrix} \dot{D}_i \end{pmatrix}_{n+1/2} =

\begin{cases} \begin{pmatrix} \dot{D}_i \end{pmatrix}^{ud}, &
\text{if} \begin{pmatrix} \dot{D}_i \end{pmatrix}_{n-1/2}\begin{pmatrix} \dot{D}_i \end{pmatrix}^d
\leq 0 \\
\begin{pmatrix} \dot{D}_i \end{pmatrix}^{d}, &
(16)
It can be shown that this implementation maintains second-order accuracy as follows. Assume that
( \dot D_i )_{n \scriptscriptstyle + 1/2} ( \dot D_i )_{n \scriptscriptstyle -

(17) 1/2} > 0
This implies that
{\rm sgn}( \dot D_i )_n = {\rm sgn}( \dot D_i )_{n \scriptscriptstyle
1/2}
which makes (16) an exact expression of (15). Note that if the assumption of (17) is not satisfied (i.e., the velocity either changes sign or is zero), then no damping is applied
to this degree of freedom.
Combined Local Damping
Combined local damping is provided by utilizing the same procedure as described for local damping, but with (15) replaced by
( R_i^{\rm d} )_n = \lambda_i \> \bigl| (A_i)_n \bigr| \> {1\over2} \bigl( {\rm sgn} ( \dot D_i )_n - {\rm sgn} ( \dot A_i )_n
\bigr)
where
{\rm sgn} ( \dot A_i )_n = {\rm sgn} \bigl( ( A_i )_n - ( A_i )_{n-1}
\bigr)
Rayleigh Damping
[ {\b
Rayleigh damping results by forming the damping matrix f as a linear combination of the stiffness and mass matrices:
[ {\bf C} ] = \beta [ {\bf K} ] + \alpha

[ {\bf M} ]
\ \ \ \
where b and are called, respectively, the stiffness- and mass-proportional damping constants. The relation between b , and the fraction of
\o
critical damping at frequency is given by
\xi = {1\over2} \left( \beta\omega + {\alpha\over\omega}

\right)
Damping attributable to stiffness increases with increasing frequency, whereas damping attributable to mass increases with decreasing frequency.
\ \ \ome \ome
Damping constants b and a are related to the fractions of critical damping ( and ) at frequencies ( ga_1 and ga_2 ) by
\beta &= 2(\xi_2\omega_2 - \xi_1\omega_1) / (\omega_2^2 - \omega_1^2)
\alpha &= 2\omega_1\omega_2(\xi_1\omega_2 - \xi_2\omega_1) / (\omega_2^2 -
\{ {\bf R}^{\rm
The governing equation of motion used when Rayleigh damping is active is derived as follows. Express the force produced by the damping mechanism ( d} \}_n
in (13)) as the sum of the stiffness and mass contributions:
\{ {\bf R}^{\rm d} \}_n = \{ {\bf R}^{\beta} \}_n + \{ {\bf R}^{\alpha} \}_n = \{ {\bf R}^{\beta} \}_n + \alpha [{\bf M}] \{ \dot{\bf
D} \}_n
and substitute this expression into (13) to obtain
[{\bf M}] \{ \ddot{\bf D} \}_n + \alpha [{\bf M}] \{ \dot{\bf D} \}_n = \{ {\bf A} \}_n - \{ {\bf R}^
(18) {\alpha} \}_n
Substitution of the central-difference approximations given by (9) and (11) into (18), followed by rearrangement of terms, yields
(19)
\{ \dot{\bf D} \}_{n \scriptscriptstyle + 1/2} = \left( {2 - \alpha\Delta t \over 2 + \alpha\Delta t} \right) \{ \dot{\bf D} \}_{n \scriptscriptstyle - 1/2} + \left( {2\Delta t \over 2 + \alpha\Delta t} \right) [{\bf M}]^{-1} \biggl( \{ {\bf A} \}_n - \{ {\bf R}^{\beta} \}_n
\biggr)
in which the stiffness contribution to the damping force is obtained by assembling the contributions from each structural element and from each deformable direction of each
link:
\{ {\bf R}^{\beta} \}_n = \sum_j \left( \{ {\bf r}^{\beta} \}_n

(20) \right)_j
with
\{ {\bf r}^{\beta} \}_n & = \beta [{\bf k}]_{n \scriptscriptstyle - 1/2} \bigl( \{ {\bf d} \}_n - \{ {\bf d} \}_{n \scriptscriptstyle - 1} \bigr) /
\Delta t
(21)
Computation of Stable Timestep

Time integration carried out using the central-difference method is a conditionally stable process. The stable timestep for our central-difference equations ((14) if local or
combined local damping is active, or (18) if Rayleigh damping is active) is given by (Belytschko 1983)
\Delta t_{\rm stab} = {2\over\omega_{\rm max}} F(\xi_{\rm max})\quad\hbox{where } F(\xi) = \sqrt

(22) {1+\xi^2} \xi
\omega_{\rm \xi_{\rm \omega_{\rm

where max} is the highest natural frequency of the discretized system, and max} is the fraction of critical damping at max} . The value of
\xi_{\rm
max} is dependent upon the damping scheme,
\xi_{max} =
\begin{cases} \frac{1}{2} ( \beta\omega_{max} + \alpha / \omega_{max} ), & \text{(Rayleigh Damping)}
\\
(23)
\ome
The natural frequencies, , of the discretized system are given by solution of the eigenproblem,
\left( [{\bf K}] - \omega^2 [{\bf M}] \right) \{ \tilde{\bf D} \} = \{ {\bf

(24) 0} \}
The maximum frequency can be bounded by applying Gerschgorin's Theorem (Isaacson and Keller 1963) to (24) which, for a diagonal mass matrix, states that
\omega_{\rm max}^2 \leq \max_i \left( G_i / M_i \right) \qquad\hbox{with}\quad i =

(25) 1,2,\ldots,n_e
where n/ e is the number of degrees of freedom, and Gi is the stiffness sum for the ith row of the assembled stiffness matrix
G_i = K_{ii} + \sum_{j=1 \atop j \neq i}^{n_e} \left| K_{ij}

\right|
The six components of Gi are stored at each structural-element node and expressed in terms of the node-local system. Stiffness contributions are provided by all structural
elements and by all deformable directions of all links. After distributing all of the stiffnesses to the appropriate nodes, each rigidly attached direction of each link contributes
G_k^ G_i^
the following portion of its source stiffness in direction-k {[{\rm S}]} to the accumulated stiffness in target direction-i {[{\rm T}]} , using the same weighting function
as given by (12), namely
G_i^{[{\rm T}]} \leftarrow G_i^{[{\rm T}]} + G_k^{[{\rm S}]} \left( { \left| {\bf n}_k^{[{\rm S}]} \cdot {\bf n}_i^{[{\rm T}]} \right| \over \sum^3_{l=1} \left| {\bf n}_k^{[{\rm S}]} \cdot {\bf n}_l^{[{\rm T}]} \right| }
\right)
{\bf n}_i^ {\bf n}_i^

where {[{\rm S}]} and {[{\rm T}]} are, respectively, the unit-vector triads of the source and target local coordinate systems.
The final timestep computed by the structural-element portion of FLAC3D is
\Delta t = \beta_u \Delta t_{\rm

stab}
\b \Delta t_{\rm
where et is a user-specified safety factor, and stab} is computed using (22), (23) and (25), in which (25) is only applied to active degrees-of-freedom.
Mass Scaling
The structural-element portion of FLAC3D may be run in one of three modes (fully dynamic, fully static or partially dynamic):
l
When run in the fully dynamic mode (structure scale-rotational-mass off),
mass scaling is not applied; instead, the mass matrix reflects the actual mass of the structural system and is assembled as described in Mass Matrix.
The timestep necessary to ensure a stable integration of the equations of motion is determined as described in Computation of Stable Timestep.
l
When run in the fully static mode,
the values in the mass matrix are adjusted to ensure that all degrees of freedom have the same frequency response — one that is appropriate to ensure
a stable integration of the equations of motion for a fixed value of timestep. The procedure by which this is accomplished is described below.
l
When run in the partially dynamic mode (structure scale-rotational-mass on),
the mass matrix reflects the actual mass of the translational degrees-of-freedom, and only the translational degrees-of-freedom are considered when
determining the timestep necessary to ensure a stable integration of the equations of motion. The masses of the rotational degrees-of-freedom are
adjusted to ensure that all rotational degrees-of-freedom have the same frequency response — one that is appropriate to ensure a stable integration of
the equations of motion for the fixed value of timestep determined for the translational degrees-of-freedom. The procedure by which this is
accomplished is described below.
Fully Static Mode
\Delta\t
For a given value of timestep ilde t , stability requires that
\Delta t_{\rm stab} = {2\Delta\tilde t \over \beta_u} = {2\over\omega_{\rm max}} F(\xi_{\rm

max})
where the estimated stable timestep has been multiplied by a safety factor of one-half.
By setting the maximum frequency equal to its bounding value provided by (25), one can write
\omega_{\rm max}^2 = \left( {F(\xi_{\rm max}) \beta_u \over \Delta\tilde t} \right)^2 \equiv \psi^2 = \max_i \left( G_i / M_i
\right)
\
in which has been introduced to represent the second term. One can ensure that all degrees of freedom have the same frequency response by setting each
Mi such that
M_i = G_i /
\psi^2
\xi_{\rm
can be computed directly because max} is given by (23).
Partially Dynamic Mode
1. Set all translational masses using the procedure described in Mass Matrix.
2. Determine the timestep necessary to ensure a stable integration of the equations of motion by only considering the translational degrees-of-freedom when
using the procedure described in Computation of Stable Timestep.
3. Determine the highest natural frequency of the discretized system by applying (25) to only the translational degrees-of-freedom, and call this value
\omega
^\star . Set all masses associated with rotational degrees-of-freedom such that they satisfy
M_i = G_i /
{\omega^\star}^2
\omega
in order to ensure that the rotational degrees-of-freedom do not produce a larger natural frequency than ^\star .
Computational Algorithm
\{{\bf R}^{\rm
1. Assume that boundary conditions consisting of externally applied loads, ext}\} , as well as structural element, link and nodal properties have been specified.
2. Set initial conditions:
n &= 0
\{ {\bf D} \}_0 &= \{ {\bf D}(t = 0) \}
\{ \dot{\bf D} \}_{\scriptscriptstyle - 1/2} &= \{ \dot{\bf D}(t = 0) \}
[{\bf k}]_{\scriptscriptstyle - 1/2} &= [{\bf k}(t=0)] \quad\hbox{for all elements}
\{ {\bf r}^{\rm int} \}_{\scriptscriptstyle - 1} &= \{ {\bf 0} \} \quad\hbox{for all
\lceil {\bf M}
3. Assemble the structure mass matrix \rfloor by considering the mode in which the structural-element portion of FLAC3D is being run. For the fully dynamic
case, employ the procedure described in Mass Matrix. For the fully static or partially dynamic cases, employ the procedures described in Mass Scaling.
\D
4. Compute stable timestep elt , as described in Computation of Stable Timestep.
\{ {\bf
5. Compute the accumulated out-of-balance force vector A} \}_n :
\{ {\bf A} \}_n = \{ {\bf R}^{\rm

1. Set ext} \}_n .
2. Assemble the contributions from each structural element, each deformable direction of each link, and each rigidly attached direction of each link, as described in
Accumulated Out-of-Balance Force Vector.
\{ {\bf R}^
3. If Rayleigh damping is active, assemble the stiffness contribution to the damping force {\beta} \}_n using (20) and (21).
\{ \dot{\bf D} \}_{n \scriptscriptstyle
6. Update all nodal velocities + 1/2} :
1. For all active degrees-of-freedom (i.e., those that are not fixed and are not slaved), update velocities using (14) if local or combined local damping is active, or
(18) if Rayleigh damping is active.
{\bf n}^ \dot{\bf D}^
2. For each rigidly attached direction {[{\rm S}]} of each link, set velocity of source node {[{\rm S}]} equal to component of velocity of target entity
in the attached direction: \quad\dot{\bf D}^{[{\rm S}]} = \left( \dot{\bf D}^{[{\rm T}]} \cdot {\bf n}^{[{\rm S}]} \right) {\bf n}^
{[{\rm S}]}
7. Update all nodal positions. Each node stores:
{\bf x}^
1. its reference position {\rm ref} , which corresponds to its position at the time that all related stiffness matrices were formed,
{\bf x}^
2. its current position {\rm cur} , and
{\bf \theta}^{\text {\bf x}^{\text
3. its accumulated rotation {cur}} since the last update of {ref}} .
{\bf x}^{\text
The displacement that has occurred since the last update of {ref}} is given by
\begin{Bmatrix} {\bf d} \end{Bmatrix} =

\begin{Bmatrix} {\bf d}^{\text{tran}} \\ {\bf d}^{\text{rot}} \end{Bmatrix} =
\begin{Bmatrix} {\bf x}^{\text{cur}} - {\bf x}^{\text{ref}} \\ {\bf \theta}^{\text{cur}} \end
and the current positions and rotations are updated using the central-difference approximation of (10):
\begin{Bmatrix} {\bf x}^{\text{cur}} \end{Bmatrix}_{n+1} =

\begin{Bmatrix} {\bf x}^{\text{cur}} \end{Bmatrix}_n + \begin{Bmatrix} {\bf \dot{d}}^{\text{tran}} \end{Bmatrix}_{n+1/2}
\Delta t
\begin{Bmatrix} {\bf \theta}^{\text{cur}} \end{Bmatrix}_{n+1} =
8. Update all structural element stiffness matrices if a large-strain update is due; otherwise, set
[{\bf k}]_{n \scriptscriptstyle + 1/2} = [{\bf k}]_{n \scriptscriptstyle - 1/2} \; \text{for all
elements}
n \leftarrow
9. Set n+1 , and go to step 3.
References
AISC. Manual of Steel Construction, Eighth Edition. Chicago: American Institute of Steel Construction Inc. (1980).
Batoz, J. L. "An Explicit Formulation for an Efficient Triangular Plate-Bending Element," Int. J. Num. Meth. Engng., 18(7), 1077-1089 (1982).
Batoz, J. L., K. J. Bathe and L. W. Lo. "A Study of Three-Node Triangular Plate Bending Elements," Int. J. Num. Meth. Engng., 15(12), 1771-1812 (1980).
Belytschko, T. "An Overview of Semidiscretization and Time Integration Procedures," in Computational Methods for Transient Analysis, Chapter 1, pp. 1-65. T. Belytschko
and T. J. R. Hughes, eds. New York: Elsevier Science Publishers, B. V. (1983).
Beneito, C. and Ph. Gotteland. "Three-Dimensional Numerical Modeling of Geosynthetics Mechanical Behavior," in FLAC and Numerical Modeling in Geomechanics
(Proceedings of the Second International FLAC Symposium on Numerical Modeling in Geomechanics, Lyon, France, 29-31 October 2001). D. Billaux et al., eds. Lisse:
Balkema (2001).
Carpenter, N., H. Stolarski and T. Belytschko. "Improvements in 3-Node Triangular Shell Elements," Int. J. Num. Meth. Engng., 23(9), 1643-1667 (1986).
Cernica, J. N. Geotechnical Engineering: Foundation Design, New York: John Wiley & Sons Inc. (1995).
Clayton, C. R. I., J. Milititsky and R. T. Woods. Earth Pressure and Earth-Retaining Structures, pp. 145-148. London: Blackie Academic & Professional (1993).
Cook, R. D. "A Plane Hybrid Element with Rotational D. O. F. and Adjustable Stiffness," Int. J. Num. Meth. Engng., 24(8), 1499-1508 (1987).
Isaacson, E., and H. B. Keller. Analysis of Numerical Methods, pp. 135-136. New York: John Wiley & Sons Inc. (1963).
Massonnet, C. E. Résistance Des Matériaux. Sciences Et Lettres, Liége (1960).
McGuire, W., and R. H. Gallagher. Matrix Structural Analysis. New York: John Wiley & Sons Inc. (1979).
St. John, C. M., and D. E. Van Dillen. "Rockbolts: A New Numerical Representation and Its Application in Tunnel Design," in Rock Mechanics — Theory - Experiment -
Practice (Proceedings of the 24th U.S. Symposium on Rock Mechanics, Texas A&M University, June 1983), pp. 13-26. New York: Association of Engineering Geologists
(1983).
Ugural, A. C. Stresses in Plates and Shells, pp. 1-16. New York: McGraw-Hill Publishing Company Inc. (1981).
Commands
Commands that operate on structural elements.
Structural elements are explicit finite-element based objects formulated using shell and beam theory. As with zones, all element force-displacement calculations are
incremental.
Each individual element is connected to others via structural nodes. Interactions with other objects (primarily zones) are handled by structural links associated with the nodes.
There are six types of structural elements supported—each specifies both a default internal behavior and a default link formulation. There are three linear elements (beam,
cable, and pile) and three two-dimensional plate elements (shell, liner, and geogrid).
The structural element logic differs from other modules in how it handles id numbers. Within this module, id numbers refer to collections of elements, identifying a given
beam or cable structure that may be constructed of any number of individual elements. Each element is identified by a component-id number, which is unique to that element.
Nodes and links may be selected by id number, which selects nodes that are attached to element collections with those numbers. Nodes and links also have their own
individual component-id numbers.
For more detail, please see General Formulation of Structural-Element Logic.
[CS: previous sentence had this following "see": the detailed :flag2:-structural element formulation- section. : check with DR that link supplied above is correct; also check
whether that section is properly located (it could reasonably be moved adjacent to this topic)]
Structural Commands
Commands that affect the structural element logic in general.
structure damping
Set the structural element logic damping scheme.
structure list information
Lists general information about structural element settings.
structure results
Controls if and what values are saved from zones in...
structure safety-factor
Set the safety factor.
structure scale-rotational-mass
This value applies to dynamic analysis only.
Commands that apply to beam elements.
structure beam apply

structure beam create
structure beam delete
Delete all beam elements in the range.
structure beam group
Assign all beam elements in the range to the group...
structure beam hide
This commands hides or un-hides all beam elements in the...
structure beam history
Samples beam responses that include force and moment carried by...
structure beam import
structure beam initialize
structure beam list
structure beam property
structure beam refine
structure beam select
Commands that apply to cable elements.
structure cable apply
Applies conditions to cable elements in the range.

structure cable create
structure cable delete
Delete all cable elements in the range.
structure cable group
Assign all cable elements in the range to the group...
structure cable hide
This commands hides or un-hides all cable elements in the...
structure cable history
Sample cable responses.
structure cable import
structure cable initialize
structure cable list
structure cable property
structure cable refine
structure cable select
Commands that apply to geogrid elements.
structure geogrid apply

Assign uniform applied pressure f to all geogrid elements in...
structure geogrid create
Create a geogrid.
structure geogrid delete
Delete all geogrid elements in the range.
structure geogrid group
Assign all geogrid elements in the range to the group...
structure geogrid hide
This commands hides or un-hides all geogrid elements in the...
structure geogrid history
Sample geogrid responses.
structure geogrid import
structure geogrid initialize
structure geogrid list
List properties and response of each geogrid element in the...
structure geogrid property
structure geogrid recover
Stress-recovery for geogrid elements.
structure geogrid refine
structure geogrid select
Commands that apply to liner elements.
structure liner apply

Assign uniform applied pressure f to all liner elements in...
structure liner create
Create a liner.
structure liner delete
Delete all liner elements in the range.
structure liner gap-factor
Sets the gap factor used during large-strain sliding of liner...
structure liner group
Assign all liner elements in the range to the group...
structure liner hide
This commands hides or un-hides all liner elements in the...
structure liner history
Sample liner responses.
structure liner import
structure liner initialize
structure liner list
List properties and responses of each liner element in the...
structure liner property
structure liner recover
Stress recovery for liner elements.
structure liner refine
this command refines elements in the range by subdividing them...
structure liner select
Commands that apply to pile elements.
structure pile apply

structure pile create
structure pile delete
Delete all pile elements in the range.
structure pile group
Assign all pile elements in the range to the group...
structure pile hide
This commands hides or un-hides all pile elements in the...
structure pile history
Sample pile responses.
structure pile import
structure pile initialize
structure pile list
structure pile property
structure pile refine
this command refines an existing element in the range by...
structure pile select
Commands that apply to shell elements.
structure shell apply

Assign uniform applied pressure f to all shell elements in...
structure shell create
Create a shell.
structure shell delete
Delete all shell elements in the range.
structure shell group
Assign all shell elements in the range to the group...
structure shell hide
This command hides or un-hides all shell elements in the...
structure shell history
Sample shell responses.
structure shell import
structure shell initialize
structure shell list
List properties and response of each shell element in the...
structure shell property
structure shell recover
Stress-recovery for shell elements.
structure shell refine
structure shell select
Commands that apply to structural nodes elements.
structure node apply

Set generalized point loads for all nodes in the range.
structure node create
Create a structural node at location v .
structure node damping-local
Sets the local-damping factor to f for all nodes in...
structure node delete
Delete all nodes in the range.
structure node fix
Fix conditions for all nodes in the range, thereby preventing...
structure node free
structure node group
Assign all nodes in the range to the group with...
structure node hide
This command hides or un-hides all nodes in the range.
structure node history
Samples nodal responses.
structure node initialize
Initialize quantities on all structure nodes in the range.
structure node join
This command creates node-to-node links on all nodes in the...
structure node list
structure node select
This commands selects or de-selects all structural nodes in the...
structure node system-local
Set the orientation of the node-local system for all nodes...
Commands that apply to structural links elements.
structure link attach

Set attachment conditions for the specified link directions.
structure link create
Creates new links on structure nodes in the range.
structure link delete
structure link group
Assign all links in the range to the group with...
structure link hide
This commands hides or un-hides all links in the range.
structure link history
Samples relative displacement or force from a single degree-of-freedom in...
structure link list
structure link property
List a property of a deformable force-displacement model in the...
structure link select
This commands selects or de-selects all links in the range.
structure link slide
Set the large-strain sliding flag.
structure link tolerance-contact
Set the tolerance used when establishing node-to-zone links.
structure link tolerance-node
Set the tolerance used when establishing node-to-node links.
structure link tolerance-slide
Set the tolerance used when updating node-to-zone links in response...
l structure damping command

l structure list command
l structure results command
l structure safety-factor command
l structure scale-rotational-mass command
structure damping command

Syntax
structure damping keyword
Primary keywords:
combined-local | local | none | rayleigh
Set the structural element logic damping scheme. The values of this setting can be printed using the structure list information command. The following
keywords are available:
combined-local
sets the damping scheme used by the structural element logic to combined-local damping. The local damping constants are stored separately for each node and set
by the command structure node damping-local.
local
sets the damping scheme used by the structural element logic to local damping. This is the default setting for static mode. The local-damping constants are stored
separately for each node and set by the command structure node damping-local.
none
sets the damping scheme used by the structural element logic to no damping. This is the default setting for dynamic mode.
rayleigh f1 f2
sets the damping scheme used by the structural element logic to Rayleigh damping. The stiffness-proportional constant is f1 = beta, and the mass-proportional
constant is f2 = alpha. This command must be used when the dynamic option is configured and turned on.
structure list command

Syntax
structure list information
Lists general information about structural element settings. This list includes the timestep safety factor, the mass scaling settings, the damping scheme in place, the link
tolerances, the default large-strain sliding settings, the number of elements, nodes, and links, etc.
structure results command

Syntax
structure results keyword
Primary keywords:
active | displacements | extra | forces | groups | links | properties | velocities
Controls if and what values are saved from zones in an exported results file. See the model results export command. By default, zones values are
active. The values being exported by default are forces, groups, and displacements.
active b
controls if any structural element values will be exported
displacements b
displacement vectors at nodes
extra b
all extra variables at elements, nodes, and links
forces b
force information at nodes, including nodal forces necessary for stress recovery
groups b
group assignments to elements, nodes, and links
links b
all link information is stored, including models and properties
properties b
element properties
velocities b
velocity vectors at nodes
structure safety-factor command

Syntax
structure safety-factor f
Set the safety factor. This is the factor by which the timestep necessary for solution stability of the structural element computations will be multiplied. The actual
timestep used will be the minimum of the structural element timestep and the timesteps for the zones and other active modules (e.g., fluid, thermal or creep). In static
mode, the final safety factor is one-half of f; in dynamic mode, the final safety factor is f. By default, f equals 1.0.
structure scale-rotational-mass command

Syntax
structure scale-rotational-mass 
This value applies to dynamic analysis only. If set to off, then the rotational degree-of-freedom masses are computed using a sphere with a volume equal to that
contributed by elements using the node. This is described as fully dynamic mode in Mass Scaling. If set to on, then the rotational degree-of-freedom masses are scaled
based on rotational stiffnesses. This is described as partially dynamic mode in the structural element section Mass Scaling.
FISH Functions
l General Structural Element Functions

l Beam Functions
l Cable Functions
l Pile Functions
l Shell Functions
l Geogrid Functions
l Liner Functions
l Structural Node Functions
l Structural Link Functions
General Structural Element Functions
These functions apply to all structure element types. Pointers to any of the six types of structural elements may be used or may be returned.
struct.connectivity(STRUCT_PNT,INT)
Get the index of the node with component-ID id in...
struct.delete(STRUCT_PNT)
Delete the structural element.
struct.density(STRUCT_PNT)
Get/set the structural element density.
struct.extra(STRUCT_PNT<,INT>)
struct.find(INT)
Get the structural element with internally assigned component-ID number i .
struct.force.update
Flags the cycling logic so that a geometry update is...
struct.group(STRUCT_PNT<,STR>)
Get/set the group name assigned to structural element p in...
struct.group.remove(STRUCT_PNT,STR)
Remove the group s from structural element p in all...
struct.head
Get the first element in the list of all structural...
struct.id(STRUCT_PNT)
Get the structural element ID number.
struct.id.component(STRUCT_PNT)
Get the structural element component-ID number.
struct.isgroup(STRUCT_PNT,STR<,STR>)
struct.list
Get the list of all structural elements in the model,...
struct.local.system(STRUCT_PNT<,INT><,INT>)
Get the local coordinate system for the structural element.
struct.mark(STRUCT_PNT)
Get/set the mark flag on the structural element.
struct.maxid
Get the maximum component-ID number assigned to any structural element...
struct.mech.convergence
Get the maximum convergence value (local ratio divided by target...
struct.mech.ratio.avg
Get the average convergence ratio of all structural nodes in...
struct.mech.ratio.local
Get the maximum local convergence ratio of all structural nodes...
struct.mech.ratio.max
Get the ratio of maximum unbalanced force to average applied...
struct.near
Get the structural element (of any type) whose centroid is...
struct.next(STRUCT_PNT)
Get the next element after p in the list of...
struct.node(STRUCT_PNT,INT)
Get a pointer to the node at index i in...
struct.num
Get the total number of structural elements in the model.
struct.pos(STRUCT_PNT<,INT>)
Get the position vector of the element, defined as the...
struct.therm.expansion(STRUCT_PNT)
Get/set the thermal expansion coefficient for the structural element.
struct.type(STRUCT_PNT)
Get the name of the structural element type.
struct.typeid
struct.was.updated
Returns TRUE if the last validation check actually performed a...
Beam Functions
Note that all beam functions can also be used with pile elements.
struct.beam.area(STRUCT_BEAM_PNT)
struct.beam.force(STRUCT_BEAM_PNT,INT<,INT>)
Get the force at one end of the beam in...
struct.beam.force.nodal(STRUCT_BEAM_PNT,INT<,INT>)
struct.beam.length(STRUCT_BEAM_PNT)
struct.beam.load(STRUCT_BEAM_PNT<,INT>)
Get/set the uniform applied distributed load acting on the beam...

struct.beam.moi(STRUCT_BEAM_PNT<,INT>)
struct.beam.moment(STRUCT_BEAM_PNT,INT<,INT>)
Get the moment at one end of the beam in...
struct.beam.moment.plastic(STRUCT_BEAM_PNT)
struct.beam.poisson(STRUCT_BEAM_PNT)
struct.beam.volume(STRUCT_BEAM_PNT)
Get the beam element volume, or the cross-sectional area times...
struct.beam.ydir(STRUCT_BEAM_PNT<,INT>)
Get the y -axis of the beam element local system.
struct.beam.young(STRUCT_BEAM_PNT)
Cable Functions
struct.cable.area(STRUCT_CABLE_PNT)
struct.cable.force.axial(STRUCT_CABLE_PNT)
Get the average axial force of the element (positive: tension;...
struct.cable.force.nodal(STRUCT_CABLE_PNT,INT<,INT>)
Get the generalized nodal force acting at end iend .
struct.cable.grout.cohesion(STRUCT_CABLE_PNT)
struct.cable.grout.confining(STRUCT_CABLE_PNT,INT)
Get the confining stress acting on the grout at end...
struct.cable.grout.dir(STRUCT_CABLE_PNT,INT<,INT>)
Get the direction vector in which cableSEL is being loaded...
struct.cable.grout.disp(STRUCT_CABLE_PNT,INT)
Get displacement in grout (shear coupling spring) at end iend ...
struct.cable.grout.friction(STRUCT_CABLE_PNT)
struct.cable.grout.perimeter(STRUCT_CABLE_PNT)
struct.cable.grout.slip(STRUCT_CABLE_PNT,INT)
Get the slip state of grout (shear coupling spring) at...
struct.cable.grout.stiffness(STRUCT_CABLE_PNT)
struct.cable.grout.stress(STRUCT_CABLE_PNT,INT)
Get stress in grout (shear coupling spring) at end iend ...
struct.cable.length(STRUCT_CABLE_PNT)
struct.cable.slide(STRUCT_CABLE_PNT)
Get the boolean flag of the large-strain sliding.
struct.cable.slide.tol(STRUCT_CABLE_PNT)
struct.cable.state.compression(STRUCT_CABLE_PNT)
Get the compression yield state of the cable element.
struct.cable.state.tension(STRUCT_CABLE_PNT)
Get the tension yield state of cable element.
struct.cable.stress.axial(STRUCT_CABLE_PNT)
Get the average axial stress of the cable element (positive:...
struct.cable.volume(STRUCT_CABLE_PNT)
Get the cable element volume, or the cross-sectional area times...
struct.cable.yield.compression(STRUCT_CABLE_PNT)
struct.cable.yield.tension(STRUCT_CABLE_PNT)
struct.cable.young(STRUCT_CABLE_PNT)
Pile Functions
Note that beam functions may also be used on pile elements
struct.pile.area(STRUCT_PILE_PNT)
struct.pile.axial.yield(STRUCT_PILE_PNT)
Get/set the axial tensile yield strength (force units) of the...
struct.pile.force(STRUCT_PILE_PNT,INT<,INT>)
Get the nodal force acting on the pile element at...
struct.pile.force.nodal(STRUCT_PILE_PNT,INT<,INT>)
struct.pile.gap(STRUCT_PILE_PNT,INT,INT)
Get the gap component in normal spring at end iend ...
struct.pile.length(STRUCT_PILE_PNT)
struct.pile.load(STRUCT_PILE_PNT<,INT>)
Get/set the uniform applied distributed load acting on the pile...

struct.pile.moi(STRUCT_PILE_PNT<,INT>)
struct.pile.moment(STRUCT_PILE_PNT,INT<,INT>)
Get the nodal moment acting on the pile element at...
struct.pile.moment.plastic(STRUCT_PILE_PNT)
struct.pile.normal.cohesion(STRUCT_PILE_PNT)
Get/set the normal coupling spring cohesive strength of the pile...
struct.pile.normal.dir(STRUCT_PILE_PNT,INT<,INT>)
struct.pile.normal.disp(STRUCT_PILE_PNT,INT)
Get the displacement in the coupling normal spring at end...
struct.pile.normal.friction(STRUCT_PILE_PNT)
Get/set the normal coupling spring friction angle of the pile...
struct.pile.normal.gap(STRUCT_PILE_PNT)
Get the normal coupling spring gap-use flag.
struct.pile.normal.state(STRUCT_PILE_PNT,INT)
Get the yield state of the coupling normal spring at...
struct.pile.normal.stiffness(STRUCT_PILE_PNT)
struct.pile.normal.stress(STRUCT_PILE_PNT,INT)
Get the stress in the coupling normal spring at end...
struct.pile.perimeter(STRUCT_PILE_PNT)
struct.pile.poisson(STRUCT_PILE_PNT)
struct.pile.rockbolt(STRUCT_PILE_PNT)
Get a boolean flag of the rockbolt.
struct.pile.shear.cohesion(STRUCT_PILE_PNT)
Get/set the shear coupling spring cohesive strength of the pile...
struct.pile.shear.dir(STRUCT_PILE_PNT,INT<,INT>)
struct.pile.shear.disp(STRUCT_PILE_PNT,INT)
Get the displacement in coupling shear spring at end iend ...
struct.pile.shear.flag(STRUCT_PILE_PNT)
Get the shear direction incremental confining stress flag.
struct.pile.shear.friction(STRUCT_PILE_PNT)
Get/set the shear coupling spring friction angle of the pile...
struct.pile.shear.state(STRUCT_PILE_PNT,INT)
Get the yield state of the coupling shear spring at...
struct.pile.shear.stiffness(STRUCT_PILE_PNT)
struct.pile.shear.stress(STRUCT_PILE_PNT,INT)
Get the stress in coupling shear spring at end iend ...
struct.pile.slide(STRUCT_PILE_PNT)
Get a boolean flag of slide.
struct.pile.slide.tol(STRUCT_PILE_PNT)
struct.pile.strain.failure(STRUCT_PILE_PNT)
struct.pile.stress.confining(STRUCT_PILE_PNT,INT)
Get the confining stress at end iend ∈ {1, 2}...
struct.pile.table.cohesion(STRUCT_PILE_PNT)
Get/set the shear direction cohesion strength table number for the...
struct.pile.table.factor(STRUCT_PILE_PNT)
Get/set the shear direction friction table number for the pile...
struct.pile.table.friction(STRUCT_PILE_PNT)
Get/set the shear direction incremental confining stress factor table number...
struct.pile.volume(STRUCT_PILE_PNT)
struct.pile.ydir(STRUCT_PILE_PNT<,INT>)
Get the y -axis of the pile element local system.
struct.pile.young(STRUCT_PILE_PNT)
Shell Functions
Note that all shell functions will also work with both geogrid elements and liner elements.
struct.shell.area(STRUCT_SHELL_PNT)
struct.shell.beta(STRUCT_SHELL_PNT)
Get shell-type material system beta angle.
struct.shell.depth.factor(STRUCT_SHELL_PNT)
Get the depth factor at which stresses have been recovered.
struct.shell.element.type(STRUCT_SHELL_PNT)
Get the name of the finite-element type used by this...
struct.shell.force.nodal(STRUCT_SHELL_PNT,INT<,INT>)
Get the generalized nodal force acting on the shell at...
struct.shell.poisson(STRUCT_SHELL_PNT)
Get/set the Poisson's ratio of the element.
struct.shell.pressure(STRUCT_SHELL_PNT)
Get/set the uniform pressure acting on the shell.
struct.shell.prop.anis(STRUCT_SHELL_PNT,INT,INT)
struct.shell.prop.ortho(STRUCT_SHELL_PNT,INT,INT)
struct.shell.prop.type(STRUCT_SHELL_PNT)
struct.shell.resultant(STRUCT_SHELL_PNT,INT<,INT>)
Get stress resultants last calculated for the element at the...
struct.shell.resultant.valid(STRUCT_SHELL_PNT)
struct.shell.stress(STRUCT_SHELL_PNT,INT<,INT<,INT>>)
Get the shell stresses at the current depth factor at...
struct.shell.stress.prin(STRUCT_SHELL_PNT,INT<,INT>)
Get the resolved principal stress at the current depth factor...
struct.shell.stress.valid(STRUCT_SHELL_PNT)
Get the stress validity flag for the element.
struct.shell.thickness(STRUCT_SHELL_PNT)
struct.shell.volume(STRUCT_SHELL_PNT)
struct.shell.young(STRUCT_SHELL_PNT)
Get/set the Young's modulus of the element.
Geogrid Functions
Note that all shell functions may also be used on geogrid elements.
struct.geogrid.shear.cohesion(STRUCT_GEOGRID_PNT)
Get/set the (shear) coupling spring cohesion strength of the geogrid...
struct.geogrid.shear.dir(STRUCT_GEOGRID_PNT,INT<,INT>)
struct.geogrid.shear.disp(STRUCT_GEOGRID_PNT,INT)
Get the displacement magnitude in the coupling spring at node...
struct.geogrid.shear.friction(STRUCT_GEOGRID_PNT)
Get/set the (shear) coupling spring friction angle of the geogrid...
struct.geogrid.shear.state(STRUCT_GEOGRID_PNT,INT)
struct.geogrid.shear.stiffness(STRUCT_GEOGRID_PNT)
struct.geogrid.shear.stress(STRUCT_GEOGRID_PNT,INT)
Get the stress magnitude in coupling spring at node inode ...
struct.geogrid.slide(STRUCT_GEOGRID_PNT)
struct.geogrid.slide.tol(STRUCT_GEOGRID_PNT)
Get/set the (shear) coupling spring slide tolerance of the geogrid...
struct.geogrid.stress.confining(STRUCT_GEOGRID_PNT,INT)
Get the confining stress at node inode ( inode ∈ {1,...
Liner Functions
Note that all shell functions may also be used on liner elements.
struct.liner.embedded(STRUCT_LINER_PNT)
Get the embedded flag.
struct.liner.normal.dir(STRUCT_LINER_PNT,INT<,INT>)
struct.liner.normal.disp(STRUCT_LINER_PNT,INT)
Get the displacement magnitude in the normal coupling spring at...
struct.liner.normal.stiffness(STRUCT_LINER_PNT<,INT>)
struct.liner.normal.strength(STRUCT_LINER_PNT<,INT>)
Get/set the normal coupling spring tensile strength of the liner...
struct.liner.normal.stress(STRUCT_LINER_PNT,INT)
Get the stress magnitude in the normal coupling spring at...
struct.liner.shear.cohesion(STRUCT_LINER_PNT<,INT>)
struct.liner.shear.dir(STRUCT_LINER_PNT,INT<,INT>)
struct.liner.shear.disp(STRUCT_LINER_PNT,INT)
Get the displacement magnitude in the shear coupling spring at...
struct.liner.shear.friction(STRUCT_LINER_PNT<,INT>)
Get/set the shear coupling spring friction angle of the liner...
struct.liner.shear.residual(STRUCT_LINER_PNT<,INT>)
Get/set the shear coupling spring residual cohesion of the liner...
struct.liner.shear.state(STRUCT_LINER_PNT,INT)
struct.liner.shear.stiffness(STRUCT_LINER_PNT<,INT>)
struct.liner.shear.stress(STRUCT_LINER_PNT,INT)
Get the stress magnitude in the shear coupling spring at...
struct.liner.slide(STRUCT_LINER_PNT)
struct.liner.slide.tol(STRUCT_LINER_PNT)
Get/set the shear coupling spring slide tolerance of the liner...
Node Functions
struct.node.acc.global(STRUCT_NODE_PNT<,INT>)
Get the acceleration of structure node expressed in a global...
struct.node.acc.local(STRUCT_NODE_PNT<,INT>)
Get the acceleration of structure node expressed in a local...
struct.node.apply(STRUCT_NODE_PNT<,INT>)
Get/set the generalized applied force expressed in a system defined by...
struct.node.apply.local(STRUCT_NODE_PNT)
Get whether the coordinate system in which generalized applied forces...
struct.node.convergence(STRUCT_NODE_PNT)
struct.node.damp.local(STRUCT_NODE_PNT)
struct.node.disp.global(STRUCT_NODE_PNT<,INT>)
Get the displacement of structure node expressed in a global...
struct.node.disp.local(STRUCT_NODE_PNT<,INT>)
Get the displacement of structure node expressed in a local...
struct.node.extra(STRUCT_NODE_PNT<,INT>)
struct.node.find(INT)
Get the structural node with internally assigned component-ID number i .
struct.node.fix(STRUCT_NODE_PNT,INT)
Get velocity-fixity flag expressed in the node-local system (degree-of-freedom component i1 ...
struct.node.fix.local(STRUCT_NODE_PNT)
struct.node.force.unbal.global(STRUCT_NODE_PNT<,INT>)
struct.node.force.unbal.local(STRUCT_NODE_PNT<,INT>)
struct.node.group(STRUCT_NODE_PNT<,STR>)
Get/set the group name assigned to structure node sn in...
struct.node.group.remove(STRUCT_NODE_PNT,STR)
Remove the group s from structure node sn in all...
struct.node.head
Get the first structure node in the list of all...
struct.node.id(STRUCT_NODE_PNT)
Get the structural node ID number.
struct.node.id.component(STRUCT_NODE_PNT)
Get the structural node component-ID number.
struct.node.isgroup(STRUCT_NODE_PNT,STR<,STR>)
struct.node.link(STRUCT_NODE_PNT<,INT>)
Get the link associated with structure node sn .
struct.node.list
Get the list of all structure nodes in the model.
struct.node.mark(STRUCT_NODE_PNT)
Get/set the mark flag.
struct.node.mass.added(STRUCT_NODE_PNT<,INT>)
Get/set the extra mass in addition to the inertial mass...
struct.node.mass.local(STRUCT_NODE_PNT<,INT>)
Get the mass at the degree-of-freedom i ∈ {1, 2,...
struct.node.maxid
Get the maximum component-ID number assigned to any structural node...
struct.node.near(VEC+)
Get the structure node nearest v .
struct.node.next(STRUCT_NODE_PNT)
Get the next structure node after sn in the list...
struct.node.num
struct.node.pos(STRUCT_NODE_PNT<,INT>)
Get the current position vector for the structure node.
struct.node.pos.reference(STRUCT_NODE_PNT<,INT>)
Get the reference position vector for the structure node.
struct.node.ratio(STRUCT_NODE_PNT)
struct.node.ratio.target(STRUCT_NODE_PNT)
Get/set the target mechanical force ratio in the node.
struct.node.resultant(STRUCT_NODE_PNT<,INT>)
Get stress resultants last calculated for the elements connected to...
struct.node.stiff.local(STRUCT_NODE_PNT<,INT>)
Get the stiffness of structure node expressed in a local...
struct.node.surface.valid(STRUCT_NODE_PNT)
Get a boolean flag for surface system validity; true if the...
struct.node.surface.xdir(STRUCT_NODE_PNT,VEC)
Set the orientation of the surface system of node sn such...
struct.node.system.local(STRUCT_NODE_PNT<,INT><,INT>)
Get the local coordinate system of the structure node.
struct.node.system.surface(STRUCT_NODE_PNT<,INT><,INT>)
Get/set the surface coordinate system of the structure node.
struct.node.temp.increment(STRUCT_NODE_PNT)
Get/set the the temperature increment that will be applied to...
struct.node.typeid
struct.node.vel.global(STRUCT_NODE_PNT<,INT>)
struct.node.vel.local(STRUCT_NODE_PNT<,INT>)
Link Functions
struct.link.attach(STRUCT_LINK_PNT,INT)
Get the attached condition used by the link in degree-of-freedom...
struct.link.delete(STRUCT_LINK_PNT)
Delete the structural link.
struct.link.extra(STRUCT_LINK_PNT<,INT>)
struct.link.find(INT)
Get the link with internally assigned component-ID number i .
struct.link.group(STRUCT_LINK_PNT<,STR>)
Get/set the group name assigned to link p in slot...
struct.link.group.remove(STRUCT_LINK_PNT,STR)
Remove the group s from structural link p in all...
struct.link.head
Get the first zone in the list of all structural...
struct.link.id(STRUCT_LINK_PNT)
Get the structural link ID number.
struct.link.id.component(STRUCT_LINK_PNT)
Get the structural link component-ID number.
struct.link.isgroup(STRUCT_LINK_PNT,STR<,STR>)
struct.link.list
Get the list of all structural links in the model.
struct.link.maxid
Get the maximum component-ID number assigned to any structural link...
struct.link.model(STRUCT_LINK_PNT,INT)
Get the name of the 1-D force-displacement model used in...
struct.link.model.area(STRUCT_LINK_PNT<,INT>)
Get/set the area associated with the force-displacement model.
struct.link.model.compression(STRUCT_LINK_PNT<,INT>)
Get/set the compressive yield force associated with the force-displacement model.
struct.link.model.disp(STRUCT_LINK_PNT<,INT>)
Get the relative displacement between the node and the target...
struct.link.model.force(STRUCT_LINK_PNT<,INT>)
Get the current force in each 1-D force-displacement model.
struct.link.model.gap(STRUCT_LINK_PNT)
Get/set the flag indicating whether gap calculations are active in...
struct.link.model.gap.neg(STRUCT_LINK_PNT<,INT>)
Get the negative (compressive) gap component of each 1-D force-displacement...
struct.link.model.gap.pos(STRUCT_LINK_PNT<,INT>)
Get the positive (tensile) gap component of each 1-D force-displacement...
struct.link.model.prop(STRUCT_LINK_PNT,INT,STR)
Get/set a property of the deformable model in degree-of-freedom idof ...
struct.link.model.stiffness(STRUCT_LINK_PNT<,INT>)
Get/set the stiffness used by each 1-D force-displacement model.
struct.link.model.tension(STRUCT_LINK_PNT<,INT>)
Get/set the tensile yield force associated with the force-displacement model.
struct.link.model.yield(STRUCT_LINK_PNT,INT)
Get the yield state indicator in the 1-D force displacement...
struct.link.next(STRUCT_LINK_PNT)
Get the next link after p in the list of...
struct.link.node(STRUCT_LINK_PNT)
struct.link.num
struct.link.side(STRUCT_LINK_PNT)
Get the side number of the link.
struct.link.slide(STRUCT_LINK_PNT)
struct.link.slide.tol(STRUCT_LINK_PNT)
struct.link.target(STRUCT_LINK_PNT)
Get the ID (or component-ID) of the target.
struct.link.type(STRUCT_LINK_PNT)
Get the name of the link target type.
struct.link.typeid
struct.link.used.by(STRUCT_LINK_PNT)
Get the name of the type of structural element with...
l struct.connectivity
l struct.delete
l struct.density
l struct.extra
l struct.find
l struct.force.update
l struct.group
l struct.group.remove
l struct.head
l struct.id
l struct.id.component
l struct.isgroup
l struct.list
l struct.local.system
l struct.mark
l struct.maxid
l struct.mech.convergence
l struct.mech.ratio.avg
l struct.mech.ratio.local
l struct.mech.ratio.max
l struct.near
l struct.next
l struct.node
l struct.num
l struct.pos
l struct.therm.expansion
l struct.type
l struct.typeid
l struct.was.updated
struct.connectivity
Syntax
index = struct.connectivity(p,id)
Get the index of the node with component-ID id in the element. Will return 0 if no node in that element matches.
Returns: index - the index of the node

Arguments: p - a pointer to a structural element
struct.delete
Syntax
i = struct.delete(p)
Delete the structural element.
Also deletes any nodes that become unconnected and any links associated with those nodes. The value of p will become null. The return value is ignored.

struct.density
Syntax
f = struct.density(p)
struct.density(p) = f
Get/set the structural element density. This is used to determine gravitational forces and to determine nodal masses in dynamic mode.
Returns: f - the structural element density

Accepts: f - the structural element density
struct.extra
Syntax
a = struct.extra(p<,i>)
struct.extra(p<,i>) = a
Get/set the FISH parameter value stored at index i of the extra array associated with the structural element.
Returns: a - the value of the variable stored at the index

Accepts: a - the value of the variable stored at the index
Arguments: p - a pointer to a link
i - an optional index from 1 to 128. If not specified, 1 is assumed
struct.find
Syntax
p = struct.find(i)
Get the structural element with internally assigned component-ID number i.
Returns: p - the pointer to the link with ID number i, or null if none was found
Arguments: i - a component-ID number
struct.force.update
Syntax
i = struct.force.update()
Flags the cycling logic so that a geometry update is performed at the start of the next cycle. Normally this update is performed at the start of cycling, and in large-strain
mode at the geometry update interval. Changes to gridpoint mass and gravity caused by density and stiffness changes may not actually affect the calculation unless an
update is performed. The return value is ignored.
Note that calling this function every step will slow cycling down, and may in certain cases (most notably cases where the timestep is changing frequently, as in creep)
disable checks that prevent instability in a static analysis. Generally it is not necessary to call this more than once every 10 steps at most.
struct.group
Syntax
s = struct.group(p<,slot>)
struct.group(p<,slot>) = s
Get/set the group name assigned to structural element p in slot slot. Use of the group logic is described in Group.
struct.group.remove
Syntax
b = struct.group.remove(p,s)
Remove the group s from structural element p in all slots it is found.
Returns: b - true if the group was removed from one or more slots of the element, false if the group was not found in the element
struct.head
Syntax
p = struct.head
Get the first element in the list of all structural elements in the model. This function should be considered deprecated, it is provided mostly for backwards compatibility
with old data files. Instead, see the fish_statement_loopforeach statement and the struct.list function. See also the struct.next function.
Returns: p - a pointer to a structural element
struct.id
Syntax
i = struct.id(p)
Get the structural element ID number. This is not to be confused with the component-ID number.
Note
number. See the struct.id.component function.
Returns: i - the structural element ID number

struct.id.component
Syntax
i = struct.id.component(p)
Get the structural element component-ID number. This is a unique value assigned internally at creation, not to be confused with the ID number.
Note
number. See the struct.id function.
Returns: i - the structural element component-ID number

struct.isgroup
Syntax
b = struct.isgroup(p,s<,slot>)
Check if the group s is associated with the structural element. Will return true if a match is found in any slot. If the optional third argument slot is provided, then it will
only check that slot.
Returns: b - true if the group was found in that element

s - a group name
slot - an optional slot specification. If not provided, the check will occur on all slots that have been assigned to the element.
struct.list
Syntax
l = struct.list()
Get the list of all structural elements in the model, of any type. This is primarily used in the fish_statement_loopforeach statement.
Returns: l - a pointer to the list of all structural elements
struct.local.system
Syntax
m = struct.local.system(p<,idir><,idof>)
Get the local coordinate system for the structural element.
Returns a 3x3 matrix representing the local coordinate system. If the optional first argument idir is specified, then it will return a vector representing the direction of that
degree-of-freedom. If the optional second argument idof is also given, then it will return that component of the vector.
Returns: m - a 3x3 matrix if no additional argument is given. A vector if one optional argument is provided. A real value if two optional arguments are provided.
Arguments: p - a pointer to a structural element.
idir - an optional argument indicating the local degree-of-freedom (from 1 to 3) of which you want the direction
idof - an optional argument indicating which component of the vector (from 1 to 3) is wanted
struct.mark
Syntax
b = struct.mark(p)
struct.mark(p) = b
Get/set the mark flag on the structural element. The structural element logic may modify this flag during command processing and cycling.
Returns: b - a boolean indicating if the element is marked

Accepts: b - a boolean indicating if the element is marked
struct.maxid
Syntax
i = struct.maxid()
Get the maximum component-ID number assigned to any structural element in this model. The next element created will be assigned this value plus one.
Note
number. See the struct.id.component function.
Returns: i - maximum component-ID number of any structural element in the model.
struct.mech.convergence
Syntax
f = struct.mech.convergence()
Get the maximum convergence value (local ratio divided by target ratio) of all structural nodes in the model.
Returns: f - maximum convergence value (local ratio divided by target ratio) of all structural nodes in the model.
struct.mech.ratio.avg
Syntax
f = struct.mech.ratio.avg()
Get the average convergence ratio of all structural nodes in the model.
Returns: f - the average convergence ratio of all structural nodes in the model.
struct.mech.ratio.local
Syntax
f = struct.mech.ratio.local()
Get the maximum local convergence ratio of all structural nodes in the model.
Returns: f - the maximum local convergence ratio of all structural nodes in the model
struct.mech.ratio.max
Syntax
f = struct.mech.ratio.max()
Get the ratio of maximum unbalanced force to average applied force of all structural nodes in the model.
Returns: f - ratio of maximum unbalanced force to average applied force of all structural nodes in the model
struct.near
Syntax
p = struct.near(v)
struct.near()
Get the structural element (of any type) whose centroid is closest to the point v. Will return null if there are no structural elements in the model.
Returns: p - a pointer to a structural element, or null if none exists

Arguments: v - a position in space
struct.next
Syntax
pnext = struct.next(p)
Get the next element after p in the list of all structural elements in the model. Will return null if no more links follow. This function should be considered deprecated; it
is provided mostly for backwards compatibility with old data files. Instead, see the fish_statement_loopforeach statement and the struct.list function. See also the
struct.head function.
Returns: pnext - the next structural element in the list, or null

struct.node
Syntax
node = struct.node(p,i)
Get a pointer to the node at index i in the structural element.
i can be from 1 to 2 for 1D structural element types (beams, cables, and piles) and up to 3 for 2D types (shells, geogrids, and liners).
Returns: node - a pointer to a structural node

i - the index of the node, from 1 to 3
struct.num
Syntax
i = struct.num()
Get the total number of structural elements in the model.
Returns: i - the total number of structural elements in the model
struct.pos
Syntax
Vector Access
v = struct.pos(p<,i>)
Get the position vector of the element, defined as the element centroid. Returns a vector, unless an optional component argument i is supplied, in which case it returns
the component value.

Arguments: p - a structural element pointer
i - optional vector component from 1 to 3
Component Access
f = struct.pos.x(p)
Get the x-component position vector, defined as the element centroid.

f = struct.pos.y(p)
Get the y-component position vector, defined as the element centroid.

f = struct.pos.z(p)
Get the z-component position vector, defined as the element centroid.

struct.therm.expansion
Syntax
f = struct.therm.expansion(p)
struct.therm.expansion(p) = f
Get/set the thermal expansion coefficient for the structural element.
Returns: f - the thermal expansion coefficient

Accepts: f - the thermal expansion coefficient
struct.type
Syntax
s = struct.type(p)
Get the name of the structural element type. This will be either beam, cable, pile, shell, geogrid, or liner.
Returns: s - the name of the structural element type

struct.typeid
Syntax
i = struct.typeid()
Get an identifier that uniquely determines the type of object. This function will return 1283545601, indicating a general structural element.
For specific structural elements types, the typeid value is given in the following table:
Table 1: Structural Element

TypeID Numbers
Element Type TypeID Number
beam 1283545608
cable 1376516851
pile 1283545868
shell 1283545603
geogrid 1283545605
liner 1283545607
struct.was.updated
Syntax
b = struct.was.updated()
Returns TRUE if the last validation check actually performed a geometry update. Normally this update is performed at the start of cycling, and in large-strain mode at
the geometry update interval. This value will be true after the validation update is performed until the next validation step when a full geometry update is not performed.
Returns: b - true if the last validation step in the cycle sequence performed a full geometry update.
Trace
A trace is a particle that is used to follow the positions and velocities of certain objects during a model run. The resulting path through space followed by the trace can be
plotted. Only one object may be traced per trace command. Traces may be added at any time. The contents of all traces can be erased with the trace purge keyword, and all
traces can be deleted with trace delete. A summary of all traces can be obtained by using trace list. Traces are sampled at a rate controlled by the trace interval
command; all traces will use this sampling rate.
l Commands
Commands
Operate on particle traces.
Each trace records and stores a the position and velocity of a particle as the model progresses. The interval is controlled by the trace interval command. Traces are created
using the trace keyword applied to a specific data type (for example zone trace or ball trace).
Trace data is stored in a temporary file while the model is open, and this data is transferred to the save file when the model is saved.
Trace Commands
trace delete
Delete all traces.
trace export
Export the contents of the list of traces to the...
trace interval
Specify the step interval on which trace values will be...
trace list
List trace information.
trace name label
Specify the label for trace s .
trace purge
Clear the contents of all traces while retaining the list...
trace results
indicates whether trace information is stored in subsequent results files.
l trace delete command

l trace export command
l trace interval command
l trace list command
l trace name command
l trace purge command
l trace results command
trace delete command

Syntax
trace delete
Delete all traces.
trace export command

Syntax
trace export s ... <file sfile >
Export the contents of the list of traces to the screen. If the optional file keyword is given, then the contents are written to the file sfile.
trace interval command

Syntax
trace interval i
Specify the step interval on which trace values will be recorded. The default value is 10.
trace list command

Syntax
trace list <keyword>
Primary keywords:
labels | limits | series
List trace information. If no keywords are specified, all traces currently being taken are listed and their current locations.
labels
List the trace labels.
limits
List the extent of position and velocity values taken for each trace.
series s ...
List the specified particle trace series where more that one trace identifier can be specified.
trace name command

Syntax
trace name s label slabel
Specify the label for trace s. This is the label that will appear when plotting the trace.
trace purge command

Syntax
trace purge
Clear the contents of all traces while retaining the list of objects to trace. New values will continue to be taken upon cycling.
trace results command

Syntax
trace results active b
indicates whether trace information is stored in subsequent results files. By default this value is off.
Zone
l Commands
l FISH Functions
Orientation of Nodes and Faces within a Zone

A zone is a closed geometric domain, with nodes at the vertices and faces forming the surface of the zone. The relative orientation of the nodes and faces is shown in the
figure below for the basic zone types: brick, wedge, pyramid, degenerate brick and tetrahedron (see zone create for full list). Each face has vertices; these vertices are also
identified in the figure. Several FLAC3D and FISH commands (e.g., zone attach) refer to this orientation.
click to enlarge image in a new

window
Figure 1: Zone geometry.
Condition Measure of Zones

A zone condition number is a measure of how badly deformed a zone is. Three measures are included, and the condition number is taken as the minimum of these three to
characterize the worst case. The range of a zone condition number is between 0 and 1. The larger the zone number is, the better the zone geometry is.
The first measure is the smallest aspect ratio between the edges of each internal tetrahedron for a given zone. For all zone types, it is assumed that the ideal shape is the one
for which all edges are equal in length, and angles between the edges are 90 degrees for a brick, 60 degrees and 90 degrees for a wedge or a degenerate brick, 60 degrees for a
pyramid or a tetrahedron, so brick faces are squares, wedge faces are 3 squares and 2 equilateral triangles, pyramid faces are 1 square and 4 equilateral triangles, and
tetrahedron faces are 4 equilateral triangles. For an ideal tetrahedron, the aspect ratio is 1. However, for the internal tetrahedrons composing zones with the ideal shapes, the
1/ 1/
smallest aspect ratio is \sqr for those internal tetrahedrons in an ideal brick or dbrick and \sqr for an ideal pyramid and wedge. Thus the result is required to be
\ \
normalized to the range between 0 and 1 by multiplying a factor of for bricks and dbricks, and for pyramids and wedges.
The second measure is the volume ratio between the tetrahedron with the smallest volume and a tetrahedron with the “average” volume for a given zone. The average volume
is defined as (zone volume) / (number of internal tetrahedrons). For wedge, tetrahedron, pyramid, and dbrick zone types with ideal shape, this measure gives 1. However, for
an ideal brick, it gives 5/6. Thus the result is required to be normalized for bricks with a multiplication factor of 1.2.
The third measure is the orthogonality, which shows how “well” sides of the zones (for each face) are inclined relative to each other. If the test returns a value close to zero, it
means that zone is most likely very elongated or badly deformed. For ideal brick, this minimum value is 1, but for other zone types with ideal shape, the minimum value is
\ 1/
. Thus this measure has to be multiplied by \sqr for zones except bricks.
Zone Field Data Names
In FLAC3D, the FISH zone field data functions allow the user to make queries about the values of a model variable at arbitrary locations in space. This includes zone-based
information as well as gridpoint-based information. The FISH functions in this section are state-based. Some of them set the particular data type (and the methods and
properties used to get that data), while others retrieve the data once these values have been set.
By default, queries operate as quickly as possible for individual calls. If many (hundreds or more) points of data are to be queried, you can initialize the system to optimize
multiple calls. This makes it unnecessary to calculate data more than once in a given zone or gridpoint. As an example, here is a FISH fragment that queries for the gridpoint-
based value x-displacement at a single location in space:
zone.field.name = 'displacement-x'
local result = zone.field.get(vector(3.5,4.3,6.7))
Here is a FISH fragment that performs many queries on a line in space, on the zone-based values of horizontal stress:
array dataset(100)
zone.field.name = 'stress-xx'
zone.field.method.name = ’poly’ ; Use polynomial fit extrapolation
zone.field.init
loop ii (1,100)
local xp = 5.0 + float(ii)/10.0
dataset(ii) = zone.field.get(3.5,4.3,xp)
end_loop
zone.field.reset
The available zone field data names are described in the table below. Note that these are the same values available under zone history, for example.
Zone Field Data Names
Name Description
acceleration acceleration magnitude at the gridpoint (only available if model configure dynamic has been specified)
acceleration-x x-acceleration at the gridpoint (only available if model configure dynamic has been specified)
acceleration-y y-acceleration at the gridpoint (only available if model configure dynamic has been specified)
acceleration-z z-acceleration at the gridpoint (only available if model configure dynamic has been specified)
condition a measure of how badly deformed a zone is (see discussion above)
density the density of the zone
displacement displacement magnitude at the gridpoint
displacement-x x-displacement at the gridpoint
displacement-y y-displacement at the gridpoint
displacement-z z-displacement at the gridpoint
extra extra variable value. The extra variable index used will default to 1 and can be changed with the zone.field.extra function. By default, the value will
come from the grid point extra variables, but this can be specified using the zone.field.source function. By default, the value will be treated as a
scalar floating point type, but this can be specified using the zone.field.type function.
pore-pressure 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
zone.field.source function.
property a property of the mechanical constitutive model of the zone. The property name must be specified using the zone.field.prop function. By default, it
will be assumed the property is a floating point scalar but this can be specified using the zone.field.type function.
property-fluid a property of the fluid constitutive model of the zone. The property name must be specified using the zone.field.prop function. By default, it will be
assumed the property is a floating point scalar but this can be specified using the zone.field.type function.
property-thermal a property of the thermal constitutive model of the zone. The property name must be specified using the zone.field.prop function. By default, it will
be assumed the property is a floating point scalar but this can be specified using the zone.field.type function.
ratio-local the local unbalanced force ratio at each gridpoint. Like all results, this can be changed to the logarithm of the value by using the zone.field.log
function.
saturation the saturation at the gridpoint (only available if model configure fluid has been specified)
strain-increment the strain increment tensor of the zone determined by the current displacement field. Use the zone.field.quantity function to specify which scalar
value to retrieve from the tensor.
strain-rate the rate increment tensor of the zone determined by the current velocity field. Use the zone.field.quantity function to specify which scalar value to
retrieve from the tensor.
stress the stress tensor of the zone determined by the weighted average of the subzone stresses. Use the zone.field.quantity function to specify which
scalar value to retrieve from the tensor.
stress-effective the effective stress tensor of the zone determined by the weighted average of the subzone stresses minus the zone averaged pore pressure. Use the
zone.field.quantity function to specify which scalar value to retrieve from the tensor.
stress-strength-ratio the stress-strength ratio of the zone. 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.
temperature the temperature at the gridpoints. The zone.field.source function can be used to specify that zone-based temperature should be used instead.
timestep-dynamic the local critical dynamic timestep of that particular gridpoint (only available if model configure dynamic has been specified)
unbalanced-force the unbalanced force magnitude at the gridpoint
unbalanced-force-x x-unbalanced force at the gridpoint
unbalanced-force-y y-unbalanced force at the gridpoint
unbalanced-force-z z-unbalanced force at the gridpoint
velocity the velocity magnitude at the gridpoint
velocity-x x-velocity at the gridpoint
velocity-y y-velocity at the gridpoint
velocity-z z-velocity at the gridpoint
Zone Field Quantity Names
The field data names above may return a range of quantities. The options are listed in the following table. The definitions of the field data of a tensor (stress, strain increment,
or strain rate) can be found in Stress/Strain Invariants.
Quantity Name Description
intermediate intermediate principal stress or strain (increment/rate)

maximum maximum (most positive) value of the principal stress or strain (increment/rate)
mean mean value defined as the trace of the tensor divided by three
minimum minimum (most negative) value of the principal stress or strain (increment/rate)
norm norm of stress or strain (increment/rate)
octohedral octahedral stress or strain (increment/rate)
shear-maximum maximum shear stress or strain (increment/rate)
total-measure distance from the origin to the tensor point in the principal space
volumetric trace of the stress or strain (increment/rate)
von-mises von Mises measure of the stress or strain (increment/rate)
xx xx-component of the stress or strain (increment/rate)
xy xy-component of the stress or strain (increment/rate)
xz xz-component of the stress or strain (increment/rate)
yy yy-component of the stress or strain (increment/rate)
yz yz-component of the stress or strain (increment/rate)
zz zz-component of the stress or strain (increment/rate)
Below is a simple example:
zone.field.method.name = 'poly' ; Use polynomial fit extrapolation
global value1 = zone.field.get(10,0,-20) ; Return stress-xx
zone.field.quantity = 'von-mises' ; Reset the stress quantity to 'von-mises'
global value2 = zone.field.get(10,0,-20) ; Return stress-von-mises
or
zone.field.method.name = 'poly' ; Use polynomial fit extrapolation
global value1 = zone.field.get(10,0,-20) ; Return stress-xx
zone.field.name = 'stress-von-mises' ; Reset the filed name directly to 'stress-von-mises'
global value2 = zone.field.get(10,0,-20) ; Return stress-von-mises
Stress-Strength Ratio
The stress-strength ratio (SSR) is calculated in some constitutive models as a local indicator of the current stress state's proximity to failure. Suppose the current effective
\sig \sig \sig
minimum and maximum principal stresses are and . The current Mohr circle is plotted in Figure 2. By keeping fixed, enlarge the Mohr
\sigma^
circle so that it is tangent to the shear failure line; the new minimum effective principal stress is denoted by {\prime}_1 , and the stress-strength ratio is defined as
SSR = \begin{vmatrix} \cfrac{\sigma^{\prime}_1 - \sigma_3}{\sigma_1 - \sigma_3} \end{vmatrix}

\le 10
It is self-evident that if the stress state is in shear failure, SSR = 1. The upper limit of SSR in FLAC3D is set to 10. If the current stress state is in tension failure, the SSR is set
to 0. SSR can be plotted as a zone contour value if it is defined in the constitutive model.
../../../../../_images/stress-strength-ratio.png
Figure 2: Schematic of stress-strength ratio.
Commands
Operate on zones.
Please see the Formulation of a 3D Explicit Finite Difference Model section for a detailed description of FLAC3D zones and their implementation and structure.
Zone elements are connected through gridpoints.
Zones can interact across surfaces with the interface logic using interface nodes and elements.
Zone faces can be used to track and name zone surfaces. It is important to note that there is no actual separate zone face data structure. Zone faces are simply associations
made with the boundaries of individual zones. As such zone faces do not have a unique id number, but are instead identified by either a zone ID number and side number pair,
or by a list of gridpoint ID numbers.
Zone commands
zone apply
Create or modify zone conditions.

zone apply-remove
Remove a zone condition.
zone attach
Create attached gridpoints.
zone cmodel
Assign, load, or get information on a zone constitutive model.
zone copy
Copy zones.
zone create
The zone.
zone creep
This command sets parameters for a time-dependent creep material analysis...
zone delete
Delete zones.
zone densify
This command finds all zones in the range and subdivides...
zone dynamic
This command sets parameters for a dynamic model (only available...
zone export
Exports a grid to a file.
zone fluid
This command sets parameters for a groundwater fluid flow analysis.
zone generate
This set of commands generates zones based on an algorithm,...
zone geometry-test
Evaluate the integrity of model zones.
zone geometry-tolerance
This command defines the tolerance before an illegal geometry error...
zone geometry-update
Updates associated with geometric or property changes are performed at...
zone group
Add group name s to the zones in the range.
zone hide
This commands hides or un-hides all zones in the range.
zone history
Adds a history of a zone value.
zone import
Import a grid from a file.
zone initialize
Initialize a variable on all zones in the range.
zone initialize-stresses
Initialize zone stresses based on the density of the zones...
zone list
List zone data.
zone mechanical
Sets parameters for a static mechanical analysis, that are specific...
zone nodal-mixed-discretization
Activate or deactivate the nodal mixed discretization (nmd) feature.
zone property
Make a constitutive model(s) property assignment.
zone property-distribution
Modify a zone constitutive model property.
zone ratio
The ratio limit for mechanical, thermal and fluid-flow calculations using...
zone reflect
All zones within the given range are reflected across the...
zone relax
Creates and modifies a special apply condition on the zones...
zone results
Controls if and what values are saved from zones in...
zone select
This commands selects or de-selects all zones in the range.
zone separate
separates internal faces specified by the range .
zone split
Splits zones in the range into multiple hexahedral zones.
zone thermal
Set parameters for a thermal analysis (only available if model...
zone trace
Trace zone position and velocity.
zone validate
This command is new and experimental.
zone water
This command initializes pore pressures, changing the effective stresses.
Zone Face commands
zone face apply

This command is used to apply boundary conditions at surface...
zone face apply-remove
Remove zone face apply conditions, which are described in the...
zone face group
Adds a group name s to zone faces included in...
zone face hide
Hide or un-hide zone faces in the range.

zone face list
List information about zone faces.
zone face select
Select or deselect zone faces in the range.
zone face skin
Skin the model to automatically generate face groups.
zone face westergaard
Applies the Westergaard approximation for the dynamic response of water...
zone face westergaard-remove
Removes any applied westergaard condition on the faces in the...
Zone Gridpoint commands
zone gridpoint create

Create a single gridpoint.
zone gridpoint fix
Fix a property at all gridpoints in the range.
zone gridpoint force-reaction
For each gridpoint in the range, in each of the...
zone gridpoint free
Free properties at gridpoints in the range.
zone gridpoint group
Assign group name s to zone gridpoints in the range.
zone gridpoint initialize
Assign or initialize values to all gridpoints in the range.
zone gridpoint list
Display gridpoint information in the console.
zone gridpoint merge
Attempts to merge all gridpoints in the range.
zone gridpoint system
Set the local coordinate system for gridpoints within the range.
Zone Interface commands
zone interface create

Create nodes or elements on interface s .
zone interface effective
The effective stress will be used in the interface calculation...
zone interface element
Manage zone interface elements.
zone interface list
Show summary data on interfaces.
zone interface node
Configure interface nodes.
zone interface permeability
Interfaces are permeable by default.
zone interface tolerance-contact
Sets the maximum depth of penetration (of faces that contact...
l zone apply command

l zone apply-remove command
l zone attach command
l zone cmodel command
l zone copy command
l zone create command
l zone creep command
l zone delete command
l zone densify command
l zone dynamic command
l zone export command
l zone face apply command
l zone face apply-remove command
l zone face group command
l zone face hide command
l zone face list command
l zone face select command
l zone face skin command
l zone face westergaard command
l zone face westergaard-remove command
l zone fluid command
l zone generate command
l zone geometry-test command
l zone geometry-tolerance command
l zone geometry-update command
l zone gridpoint create command
l zone gridpoint fix command
l zone gridpoint force-reaction command
l zone gridpoint free command
l zone gridpoint group command
l zone gridpoint initialize command
l zone gridpoint list command
l zone gridpoint merge command
l zone gridpoint system command
l zone group command
l zone hide command

l zone history command
l zone import command
l zone initialize command
l zone initialize-stresses command
l zone interface tolerance-contact command
l zone interface create command
l zone interface effective command
l zone interface element command
l zone interface list command
l zone interface node command
l zone interface permeability command
l zone list command
l zone mechanical command
l zone nodal-mixed-discretization command
l zone property command
l zone property-distribution command
l zone ratio command
l zone reflect command
l zone relax command
l zone results command
l zone select command
l zone separate command
l zone split command
l zone thermal command
l zone trace command
l zone validate command
l zone water command
zone apply command

Syntax
zone apply keyword <range>
Primary keywords:
force | force-x | force-y | force-z | source | well
Create or modify zone conditions. This command is used to apply conditions to the volume represented by zones — i.e., body forces or fluid/thermal sources. For
application of boundary conditions on surfaces represented by zone faces, see the zone face apply command. The user must specify the condition type, the numerical
value, optional modifiers, and an optional range over which the condition is to be applied. If no range is specified, then the command applies to the entire model.
Removal of zone conditions is done with a separate command — see zone apply-remove.
After the supplied condition's value (f or v), an optional modifier keyword can be used to modulate the supplied value. The position of the modifier in the command is
marked [keywordblock]; the valid modifier keywords are found in the Keyword Block section at the end of this topic. The modifiers can be used to vary the value of the
applied condition in both time and space.
All values are considered to be per unit volume.
Apply conditions that conflict with currently existing ones will overwrite them.
force v [keywordblock]
All components (x, y, and z) of the body force per unit volume applied to a zone.
force-x f [keywordblock]
The x-component of the body force per unit volume applied to a zone.
force-y f [keywordblock]
The y-component of the body force per unit volume applied to a zone.
force-z f [keywordblock]
The z-component of the body force per unit volume applied to a zone.
source f [keywordblock]
A heat-generating source, f, is applied as a volume source of the specified strength (e.g., in W/m3 ) in each zone in the specified range. When a new source is
applied to a zone with an existing source, the new source strength replaces the existing source strength.
Decay of the heat source over time can be represented by applying one of the available modifiers.
Note this keyword is only available for the thermal model option.
well f [keywordblock]
A volume rate of flow, f (i.e., fluid volume per zone volume per unit time), is specified for each zone in the specified range (f > 0 for inflow).
Note: A fluid flow model must exist for this command to work.
Keyword Block
The following keywords may be used to modify the base value supplied. force, force-x, force-y, force-z, source and well.
fish s
Specify a multiplier that is a FISH function named s. The return value of this FISH function is multiplied by the base value (including gradient) over all
zones included in this apply condition. So a return value of 1.0 will apply the base value provided, and a return value of 0.0 will effectively remove it. This
function will be called every step.
If the apply condition requires a vector value, this function should also return a vector.
fish-local s
Specify a multiplier that is a FISH function named s, which is applied separately to each individual zone affected by this apply condition. This function
must take two arguments, the first of which will be a pointer to the specific zone. The second argument is not used. This allows an apply condition to vary
over time as well as space. The returned value of this FISH function is multiplied by the base value (including gradient) on the specific zone supplied. So a
return value of 1.0 will apply the base value provided, and a return value of 0.0 will effectively remove it. This function will be called every step for every
zone included in the apply condition.
If the apply condition requires a vector value, this function should also return a vector.
gradient v <origin v >
Applies a gradient in space to the scalar-value provided. The position used in this calculation is the zone centroid. Another way of assigning a linear
gradient is with the vary modifier.
servo keyword ...
Use a servo tied to the mechanical convergence ratio to control the magnitude of the applied condition. This can be used to maintain, gradually ramp up, or
gradually reduce apply conditions while maintaining a quasi-static response. By default the multiplier will start at 0.001, and will gradually increase to 1.0
as the convergence ratio falls below 2e-3, and decrease if it rises above 1e-2. The following keywords are available to control the servo response:
latency i
The minimum number of steps that must pass since the last servo adjustment before the next one occurs. This can keep the servo from
overcontrolling in the initial response to an adjustment. The default value is 1.
lower-bound f
Set the lower mechanical convergence ratio value. If the current ratio falls below this value, the current multiplier will be multiplied by the lower-
multiplier. The default value is :lflt:`2e-3'.
lower-multiplier f
If the current ratio falls below the lower-bound, the value is multiplied by this. The default value is 0.975.
maximum f
The maximum value the current multiplier is allowed to become. The default value is 1.0.
minimum f
The minimum value the current multiplier is allowed to become. The default value is 0.001.
ramp
Sets the servo into ramp mode. This means that the current multiplier is not allowed to go down, the value will only increase. This is useful to
gradually increase an applied condition to it's full value. See also the reduce keyword.
ratio keyword
Which mechanical convergence ratio is compared against lower-bound and upper-bound. By default this is the current value assigned by the zone
ratio command (which is average by default. See the zone ratio command for definitions. The available keywords are:
average
Use the average mechanical force ratio.
maximum
Use the maximum mechanical force ratio.
local
Use the local mechanical force ratio.
reduce
Sets the servo into reduce mode. In this mode the starting value of the current multiplier is 1.0, and the minimum value is set to 0.0. When the current
ratio falls below lower-bound the current multiplier is reduced by the upper-multiplier. The current multiplier is never increased. This is useful to
gradually decrease an applied condition to zero.
upper-bound f
Set the upper mechanical convergence ratio value. If the current ratio rises above this value, the current multiplier will be multiplier by the upper-
multiplier. The default value is 1e-2.
upper-multiplier f
If the current ratio rises above the upper-bound, the value is multiplied by this. The default value is 1.01.
table s <time keyword>
Specify a value multiplier that is a table (named s). By default, the x-value of the table is the step number. The returned value of this table is multiplied by
the base value (including gradient) over all zones included in this apply condition. So a return value of 1.0 will apply the base value provided, and a return
value of 0.0 will effectively remove it. The table lookup will be performed every step. The time scale for the x-axis can also be selected by giving the time
keyword followed by one of the following options:
step
creep
dynamic
fluid
mechanical
thermal
vary v
Apply a linear variation to the scalar-value provided. The position used in this calculation is the zone centroid. Another way of assigning a linear gradient is
with the gradient modifier.
zone apply-remove command

Syntax
zone apply-remove <keyword> <range>
Primary keywords:
force | force-x | force-y | force-z | source | well
Remove a zone condition. Zone conditions are applied using the zone apply command. If no keyword is supplied, all conditions are removed on each zone in the
range. If no range is supplied, the condition is removed from all zones. To remove conditions applied to zone faces, see the command zone face apply.
force
Remove a zone apply force (vector) condition applied to a zone.
force-x
Remove a zone apply force-x condition applied to a zone.
force-y
Remove a zone apply force-y condition applied to a zone.
force-z
Remove a zone apply force-z condition applied to a zone.
source
Remove the heat-generating source applied as a volume source of specific strength to a zone (i.e., remove a zone apply source condition).
well
Remove the volume rate of flow applied to each zone (i.e., remove a zone apply well condition).
zone attach command

Syntax
zone attach keyword
Primary keywords:
delete | by-face | gridpointid | group | list
Create attached gridpoints. Gridpoints on one zone may be rigidly attached (or slaved) to master gridpoints, edges, or faces of other zones. This allows grids that do not
exactly topologically match to behave as a single grid. Each gridpoint so attached results in the creation of an internal data structure (an Attach Point) that is accessible
by command and by FISH.
The attach logic is fully general in that it will successfully attach any distribution of gridpoints or faces on both sides. However, it works best if there is always a
integral increase in the number of points from one edge to another (for example, three gridpoints for every two) and if one side of the attached surface consistently has
smaller faces than the other.
See Connecting Adjoining Primitive Shapes for an example application and further discussion of limitations.
One of the following keywords is required to create, destroy, or manipulate attach conditions.
delete <range>
Removes attach conditions on all slaved gridpoints within the given range. All attach conditions are removed if no range is present.
by-face keyword ... <range>
Searches the mesh for all surface faces in the range. For this purpose a surface face is defined to be a face that is not perfectly topologically connected to a zone
on the other side. For faces that are coplanar and touching (within a tolerance), attach conditions are automatically generated between gridpoints on one side and
faces on the other. The side with the smaller faces will be selected to be attached (the slave).
The following optional keywords are available to control which faces and gridpoints are selected to attach.
snap b
If snap is set to on (the default), then turns slave gridpoint locations are moved to correspond to the locations they are slaved to on the master, both
immediately and during cycling. If snap is set to off, slave gridpoints will move along with the master relatively, but their positions might be different.
tolerance-absolute f
If specified, f is the maximum absolute distance between the slave gridpoint and the target face for an attach condition to be created. The default value is
0.0, meaning a relative tolerance scheme is used instead.
tolerance-angle f
Faces are attached only if the angle between them is less than f in degrees. By default this value is 5 degrees. It is sometimes necessary to increase this
tolerance for complex surfaces that create non-planar faces.
tolerance-relative f
Gridpoints are attached to faces only if the distance is within a distance of f times the absolute value of the position of the face centroid. The default value is
1x10-5. It may be necessary to increase this value if there was additional error in grid creation. [CS: check this out; usage here is fuzzy (past tense? when
"was" the error]
gridpointid ids keyword
Attaches a single gridpoint with ID number ids to: another gridpoint, an edge between two gridpoints, or a zone face. One of the following keywords is required
to indicate the target of the attach condition.
to-gridpointid idm <snap b >
Attaches the gridpoint to the gridpoint with ID idm. By default snap is on and will cause gridpoint ids to move to the same location as gridpoint idm, both
immediately and during cycling.
to-edgeids id1 id2 keyword ...
The gridpoint with ID number ids is attached to the edge defined as the line between gridpoints i1 and i2.
One of the following optional keywords may be applied.
weight f
The optional keyword weight can be given to define the location of gridpoint ids between gridpoints i1 and i2. If weight = 0.0, then ids is located at
i1; if weight = 1.0, then ids is located at i2. If not specified, this weighting is calculated automatically based on the position of gridpoint ids.
snap b
By default snap is on and will cause gridpoint ids to move to the location given by the weighting between i1 and i2 automatically, both immediately
and during cycling.
to-faceid idz iside keyword ...
The gridpoint with ID number ids is attached to the face identified as side iside of zone with ID idz. URGENT: CS: section referred to here appears to be
absent (Refer to :flag2:-Command Reference Section 1.1.4 Orientation of Nodes and Faces within a Zone-).]
One of the following optional keywords may be applied.
weight f1 f2 f3 f4
The optional keyword weight can be given to define the location of gridpoint ids on face idz, iside1 with respect to the face vertices. Each of the four
value given must be between 0.0 and 1.0, and the sum should add to 1.0 (assuming the slave location is on the face). For example, the location of the
first vertex would correspond to 1.0, 0.0, 0.0, 0.0, and the center of the face would correspond to 0.25, 0.25, 0.25, 0.25.
snap b
By default snap is on and will cause gridpoint ids to move to the location given by the weighting on zone face idz, iside1 automatically, both
immediately and during cycling.
group s keyword ... <range>
Group gridpoint attach data structures within the given range, if specified. One of the following optional keywords may be applied.
slot s
Assign the group to slot s.
remove
Remove the group s from all attach conditions in the range. If slot is not specified, it will be removed from all slots it is found in.
list <range>
List information on all attach conditions in the range. This information includes the slave gridpoints, the master targets, and the weighting factors if appropriate.
zone cmodel command

Syntax
zone cmodel keyword
Primary keywords:
assign | list | load
Assign, load, or get information on a zone constitutive model. This command associates a constitutive model with specified zones in the grid. It also allows querying of
properties and states of constitutive models, and dynamic loading of user-defined mechanical models as DLLs.
assign keyword <overlay i > <range>
assigns a mechanical material model to all zones in the range.
The optional keyword overlay assigns either two overlaid sets of five constant-strain tetrahedral elements to each zone ( i =2 ), or one set of five tetrahedral
elements to each zone ( i =1 ). The default is set to double-overlaid elements. Use of zones with a single overlay for mechanical calculations is not recommended.
The mechanical constitutive models are described in Constitutive Models, and the creep models are in Creep Constitutive Models.
anisotropic
transversely-anisotropic elastic model (see the Anisotropic model description).
burgers
classical viscoelastic model known as the Burgers substance which composed of a Kelvin model and a Maxwell model (only available for the creep option;
see the Burgers model description).
burgers-mohr
viscoplastic model combining the Burgers model and the Mohr-Coulomb model (only available for the creep option; see the Burgers-Mohr model
description).
cap-yield
cap-yield elasto-plasticity model, known also as CYSoil model (see the CYSoil model description).
cap-yield-simplified
simplified cap yield elasto-plasticity model, known also as CHSoil model (see the CHSoil model description).
double-yield
double-yield (cap) elasto-plasticity model (see the Double-Yield model description).
drucker-prager
Drucker-Prager elasto-plasticity model (see the Drucker-Prager model description).
elastic
isotropic elastic model (see the Elastic Model description).
finn
dynamic pore-pressure generation elasto-plasticity model (only available for the dynamic option; see the Finn model description).
hoek-brown
Hoek-Brown elasto-plasticity model (see the Hoek-Brown model description).
hoek-brown-pac
Hoek-Brown-PAC elasto-plasticity model (see the Hoek-Brow-PAC model description).
hydration-drucker-prager
modified Drucker-Prager for hydration (only available for the thermal option; see see the Hydration-Drucker-Prager model description).
maxwell
classical viscoelastic model known as the Maxwell substance, known also as Maxwell model (only available for the creep option; see the Maxwell model
description).
modified-cam-clay
modified Cam-Clay elasto-plasticity model (see the modified Cam-Clay model description).
mohr-coulomb
Mohr-Coulomb elasto-plasticity model (see the Mohr-Coulomb model description).
mohr-coulomb-tension
Mohr-Coulomb elasto-plasticity model with tensile strain crack tracking, known also as the MohrT model (see the Mohr-Coulomb-Tension model
description).
null
null model — for most purposes null models are ignored by default, and zones adjacent to them are treated as surfaces (see the Null model description).
orthotropic
orthotropic elastic model (see the Orthotropic model description).
plastic-hardening
elasto-plasticity model with shear and volumetric hardening, known also as PH model (see the Plastic-Hardening model description).
power
two-component power law model used for mining applications (only available for the creep option; see the Power model description).
power-mohr
viscoplastic model combining the two-component Power model and the Mohr-Coulomb model (only available for the creep option; see the Power-Mohr
model description).
power-ubiquitous
viscoplastic model combining the two-component Power model and the Ubiquitous-Joint model (only available for the creep option; see the Power-
Ubiqitous mdoel description).
softening-ubiquitous
strain-softening/hardening elasto-plasticity model with bilinear failure and ubiquitous joints, known also as the SUBI model (see the Softening-Ubiquitous
model description).
strain-softening
strain-softening/hardening elasto-plasticity model (see the Strain-Softening model description).
swell
Mohr-Coulomb elasto-plasticity model considering wetting-induced deformation (see the Swell model description).
ubiquitous-joint
Mohr-Coulomb elasto-plasticity model with a plane of weakness, known also as UBI model (see the Ubiquitous-Joint model description).
ubiquitous-anisotropic
model with a plane of weakness and with anisotropic elasticity (see the Ubiquitous-Anisotropic model description).
wipp
a reference creep model commonly used in thermomechanical analyses associated with studies for the underground isolation of nuclear waste in salt (only
available for the creep option; see the WIPP model description).
wipp-drucker
a viscoplastic model combining the WIPP model and the Drucker-Prager model (only available for the creep option, see the WIPP-Drucker model
description).
wipp-salt
viscoplastic model modified from the WIPP model, and includes volumetric and deviatoric compaction behavior for salt-like materials (only available for
the creep option; see the WIPP-Salt model description).
list keyword
names <s >
Outputs available mechanical model keywords, names and version numbers. Output is restricted to the model named s if supplied.
properties <s >
Outputs the property list for each mechanical model. Output is restricted to the model named s if supplied.
states <s >
Outputs the possible state flags for each mechanical model. Output is restricted to the model named s if supplied.
load <s >
attempts to dynamically load a DLL version of a constitutive model, identified by s. Once loaded, the DLL model can be assigned to zones in the grid using the
zone cmodel assign command and range keywords. See Writing New Constitutive Models for a guide to creating user-defined models as DLLs. zone cmodel
load can only be applied if model configure plugin is invoked. Also see the zone cmodel load command.
s can either be the keyword used by the model, which should expand into the model dll name as modelname006.dll (where 'name' is the name provided by s), or it
can be full name of the dll. If a relative filename is given, both the current directory and the directory FLAC3D is installed in will be searched, including
subdirectories.
zone copy command

Syntax
zone copy v <merge b > <range>
Copy zones. New zones and gridpoints are created by copying all zones within the given to a new position with position offset by v. If merge is set off, gridpoints on the
outer boundaries of the newly created zones are not merged with preexisting gridpoints. The default setting for merge is on. Zones and gridpoints created by copying
retain the group assignments of the source zones and gridpoints.
zone create command

Syntax
zone create keyword
Primary keywords:
brick | cylindrical-shell | cylinder | cylindrical-intersection | degenerate-brick | pyramid | radial-brick | radial-cylinder | radial-tunnel | tetrahedron | tunnel-intersection |
uniform-wedge | wedge
The zone.create command fills primitive shapes ( brick, cylinder, etc.) with a predefined grid pattern.
See Primitive-Based Grids for further discussion and examples of the process of creating a mesh using primitive shapes.
To create zones from a 2D cross section that is then extruded into a third dimension, see the extrude command and the Extruder Pane in the GUI, along with the
command zone generate from-extruder.
To create zones from an interactive assembly of blocks, with control over curved edges, see the building-block command and the Building Blocks Pane in the GUI
along with the command zone generate from-building-blocks.
To create individual gridpoints see zone gridpoint create.
Individual zones may be created with this command using the brick keyword and the size set to (1,1,1).
FLAC3D may also read in externally generated grids in several formats, see the zone import command.
On meshing with zone create
l see Primitive-Based Grids in Problem Solving with FLAC3D

l see Further Discussion: Meshing With Primitives in Tutorial: First FLAC3D Model
Note
Thumbnails of primitives are links (may be clicked) to enlargements that indicate the shapes' reference points.
After each shape keyword is a block of modifiers that control its position, shape, and zone distribution. These are marked [keywordblock] in the commands, with
definitions found in the "Keyword Block" section at the end of this topic.
IMPORTANT: image setup below works for CHM output ONLY; clicking a thumbnail in HTML output will result in a "Page can't be displayed" error. DO NOT TRY
TO FIX.
to do: the full size images for the primitives should be redone for html format; the numbers are too hard to read
brick [keywordblock]
Create a hexahedral brick-shaped mesh with eight vertices:
8 reference points, 3 size entries, 0 dimension entries, not fill-able.
cylindrical-shell [keywordblock]
Create a cylindrical shell mesh:
10 reference points, 4 size entries, 4 dimension entries, fill-able.
cylinder [keywordblock]
Create a cylindrical-shaped mesh:
cylindrical-intersection [keywordblock]
Create an intersection of two cylinders:
degenerate-brick [keywordblock]
Create a degenerate brick mesh, with two vertices merged:
pyramid [keywordblock]
Create a pyramid-shaped mesh:
radial-brick [keywordblock]
Create a radially graded mesh around brick:
radial-cylinder [keywordblock]
Create a radially graded mesh around cylindrical-shaped tunnel
radial-tunnel [keywordblock]
Create a radially graded mesh around parallelepiped-shaped tunnel:
tetrahedron [keywordblock]
Create a tetrahedral-shaped mesh:
tunnel-intersection [keywordblock]
Create a tunnel intersection:
uniform-wedge [keywordblock]
Create a uniform wedge-shaped mesh:
wedge [keywordblock]
Create a wedge-shaped mesh:
Keyword Block
Zone Create Modifiers
The characteristics of the created shape (e.g., global coordinate positions, number of zones) are defined by specifying the keywords given below, after the shape
keyword. The numerical entries associated with each shape are summarized in the table above and illustrated in the figures (click any thumbnail image above for
a reference enlargement). The shape keywords of zone.create shown above will accept the keywords listed in the block below, except where noted otherwise in
the descriptions. The major keywords are: brick, cylinder, cylindrical-intersection, cylindrical-shell, degenerate-brick, pyramid, radial-brick,
radial-cylinder, radial-tunnel, tetrahedron, tunnel-intersection, uniform-wedge and wedge.
dimension f ...
Specify the dimensions of interior regions for some shapes. These are used if the control point is not specifically given. Up to seven dimension entries may
be required for a shape (f1, f2, f3, ... , f7). Refer to the figures above for entries and dimensions. If dimension is not given the entries are calculated as 20%
of the lengths between reference points.
This keyword can only be used with the following keywords of the zone create command: cylindrical-intersection, cylindrical-shell, radial-brick, radial-
cylinder, radial-tunnel, and tunnel-intersection.
edge f
Specify an edge length for the sides of the mesh. If point 1, point 2, and point 3 are not specified, then the magnitude of the distance from point 0 will be
defined by edge. By default the edge length is the number of zones specified in that direction.
fill <group s1 <slot s2 >>
If specified, the interior region for some shapes (see tableofnumbersforprimitives above) will be filled with zones. If not specified, the interior region will
not contain zones. If the optional group keyword is given with a valid name, the name s1 is assigned to the filled zones.
This keyword can only be used with the following keywords of the zone create command: cylindrical-intersection, radial-brick, radial-cylinder, radial-
tunnel, and tunnel-intersection.
group s1 <slot s2 >
Assign a group name s1 to this primitive at creation. By default (when the slot keyword is not supplied), the group is assigned to slot Default. Use of the
merge b
Gridpoints on the outer faces of the mesh are merged with existing mesh faces if this keyword is set true. During execution of a zone.create command, a
check is made for each boundary gridpoint against the boundary gridpoints of zones that already exist. Internal gridpoints are not checked. If two boundary
gridpoints fall within a tolerance of 1 × 10-7 (relative to the magnitude of the gridpoints' position vector) of each other, they are assumed to be the same
point, and the first gridpoint is used instead of creating new ones for all subsequent calculations. If merge is set false, two gridpoints are not merged into
one.
point i keyword
The keywords point 0, point 1, point 2 . . . point 16 specify the reference (corner) points of shapes. By default, point 0 is located at (x = 0, y = 0, z = 0). By
default, point 1, point 2, and point 3 are set to the orthogonal distances in the x-, y- and z-directions, with a magnitude equal to the number of zones in that
direction. When specifying point 1, point 2, and point 3, the vectors point 0 - point 1, point 0 - point 2, and point 0 - point 3 must form a right-handed
coordinate system.
Up to 16 points may be required for a shape. The number required is shown in tableofnumbersforprimitives above. The locations of these points are
illustrated in the reference images (click on any thumbnail above to access).
The following options are available to define the location of any given point
v <add>
The position is given as a vector v. If the optional keyword add is used, the value of v will be added to the position of point 0.
gridpoint s
The position of the gridpoint with name s is used. See the zone gridpoint create command. This allows to user to create named reference points
in space ahead of time, and refer to them when creating primitives.
ratio f1 <f2... >
This specifies a ratio that is used to space zones with an increasing or decreasing geometric ratio. This ratio is defined as creating a zone size distribution
such that each zone along the edge is f times the previous. Up to five ratio entries (f5) may be needed for some shapes. For each shape, the entries and their
associated zone directions are shown in the reference images (click any thumbnail above). If ratio is not given, all entries default to 1.0.
size i1 <i2 ... >
This specifies the number of zones for each shape. Up to five (i5) may be needed for some shapes. The number required is listed in
tableofnumbersforprimitives above. The entries and their corresponding directions for each shape are shown in the reference images (click any thumbnail
above). If not specified, size values default to 10.
sweep-axis
When this keyword is given, edge point 0 - point 2 is used as an axis about which edges point 1 - point 4 and point 3 - point 5 are swept. Without this
keyword, the grid faces fall on the (point 0,point 1,point 3) and (point 2,point 4,point 5) planes.
zone creep command

Syntax
zone creep keyword
Primary keywords:
active | list | time-total
This command sets parameters for a time-dependent creep material analysis (only available with the creep model option – see Section 1 in Creep Material Models).
These parameters apply to zones only, other model elements may have different values.
active b
The creep process is on for zones, by default, when the model configure creep command is given. Specify active off to suppress the creep calculation for
zones. Generally this command is unnecessary and is slaved to the zone creep active setting.
list
Display creep calculation-mode information.
time-total f
Specifies the accumulated zone creep time, defined as the sum of all the timesteps over which zone creep is active. Once set, creep time will continue to
accumulate with subsequent cycles.
zone delete command

Syntax
zone delete <range>
Delete zones. All zones with centroids within the range defined by <range> are deleted. Zones can be deleted at any time in the model creation or solution. Unlike
zones removed with the zone cmodel assign null command, deleted zones cannot be restored.
zone densify command

Syntax
zone densify keyword <range>
Primary keywords:
global | gradient-limit | local | maximum-length | segments | repeat
This command finds all zones in the range and subdivides them into smaller zones filling the same volume. This will create new zones, and in general will create new
gridpoints. The new zones will copy the group assignments of the original.
Note that this can create “hanging” gridpoints that are not perfectly connected to the surrounding grid. The zone attach by-face command should be used before
cycling, to ensure continuous model behavior.
See Densifying Grids for a discussion and examples of the use of zone densification, and Geometry-Based Densification: Octree Meshing for discussion and examples
the process of creating an "octree" mesh based on geometric data.
global
This specifies that the zone edges to which the segments keyword applies are the ones that most closely correspond to the global x, y and z axes.
gradient-limit
Zones chosen for densification will be checked to attempt to ensure that adjacent zones differ by, at most, one level of densification. This may mean more zones
will be densified than actually fall into the range.
local
This is to set the zones to be densified in a local segment order. The local segment order is along the edges of e1, e2 and e3, where e1, e2 and e3 are the edges of
the first and second, first and third, and first and fourth gridpoints of this zone. This is the default setting.
maximum-length f1 <f2 <f3 >>
This specifies the maximum edge lengths to be densified, in order. If f2 and f3 are not specified, they will be set to the same number as f1.
segments i1 <i2 <i3 >>
This specifies the subdivision number of zones to be densified, in order. If i2 and i3 are not specified, they will be set to the same number as i1.
repeat 
Repeats the densification i times, causing a recursive application of the range and densification settings. This can, for example, be used to create an octree grid.
Note that if no number is given, then FLAC3D will repeat until the maximum-length is reached, applying the division specified in segments each time.
zone dynamic command

Syntax
zone dynamic keyword
Primary keywords:
active | damping | free-field | list | multi-step | time-total
This command sets parameters for a dynamic model (only available with the dynamic model option – see Dynamic Analysis. These parameters apply to zones only,
other model elements may have different values.
active b
The dynamic option is on for zones, by default, when the model configure dynamic command is given. Specifies whether zone mechanical calculations are
considered to use dynamic mode. Generally this setting is unnecessary and is slaved to the zone dynamic active setting.
damping keyword <range>
This command selects the damping type for the dynamic analysis. Damping in dynamic analysis is described in the topic Mechanical Damping and Material
Response. Damping values can vary from region to region within the model. The following keywords apply:
artificial-viscosity f1 f2
Sets the von Neumann (f2) and Landshoff (f2) constants, which in general should both be 1.0. This damping only applies to the main grid. See the topic
Artificial Viscosity.
combined f <gradient v >
combined local damping (see Combined Damping). The damping value is 0.8, by default. A gradient map be applied to vary the parameter in space.
local f <gradient v >
local damping (see Local Nonviscous Damping). The damping value is 0.8, by default. A gradient map be applied to vary the parameter in space.
hysteretic keyword
Hysteretic damping is invoked (see Hysteretic Damping). The following keywords and coefficients are the functions available to represent the variation in
G / Gmax.
default f1 f2
Default model represented by a cubic equation with two parameters.
hardin f1
Hardin/Dernevich equation with one parameter.
off
Turns hysteretic damping off.
sig3 f1 f2 f3
sigmoidal equation with three parameters.
sig4 f1 f2 f3 f4
sigmoidal equation with four parameters.
rayleigh <f1 <gradient v > f2 <gradient v > <mass> <stiffness>>
For dynamic calculations, a certain fraction of critical damping is usually required over a given frequency range. This type of damping is known as
Rayleigh damping (see Rayleigh Damping), where f1 = the fraction of critical damping operating at center frequency of f2. (NOTE: Input frequencies for
the program are in cycles/sec or Hertz – not radians/sec.) The optional modifiers stiffness and mass denote that the damping is to be restricted to stiffness-
or mass-proportional, respectively. If they are left out, normal Rayleigh damping is used.
NOTE: By specifying stiffness damping, the critical timestep for numerical stability will automatically be reduced. It is still possible for instability to result
if large mesh deformation occurs. In such a case, lower the timestep with the model dynamic timestep command.
free-field keyword
Controls the free-field boundary condition (available only for dynamic option; see Free-Field Boundaries). The following keywords are also available instead of a
boolean value:
If on, creates free field boundary zones. If off, destroys the free field boundary zones and the rest of the associated apply conditions.
plane-x
Creates free field zones only on the planes perpendicular to the X axis. So free field zones will be created on the -X and +X sides of the model, but not on
the -Y and +Y side of the mode, and corner zones will not be created. This is useful when FLAC3D is used to model 2D dynamic problems.
plane-y
Creates free field zones only on the planes perpendicular to the Y axis. So free field zones will be created on the -Y and +Y sides of the model, but not on
the -X and +X side of the mode, and corner zones will not be created. This is useful when FLAC3D is used to model 2D dynamic problems.
list
dynamic calculation-mode information
multi-step b
turns multi-stepping on or off (see Dynamic Multi-stepping). Multi-stepping speeds up calculations in dynamic models which have a large zone size or modulus
contrast. Areas of the grid with critical timesteps greater than the global critical timestep are updated less frequently, thus saving execution time. The logic is
general in the sense that all zones, gridpoints and structures are included. The user does not need to do anything beyond switching it on.
time-total f
Specifies the accumulated zone dynamic time, defined as the sum of all the timesteps over which zone dynamic mode is active. Once set, dynamic time will
continue to accumulate with subsequent cycles.
[DR: please check that all the "see ----" links on this page land where they should]
zone export command

Syntax
zone export s keyword <range>
Primary keywords:
binary
Exports a grid to a file. A path can be part of the supplied file name s. The grid file is an ASCII-format file (or binary-format file if binary is assigned) description of the
FLAC3D geometry (zones, gridpoints, zone groups, and face groups). The binary-format file size will be smaller than the ASCII-format file size, and it takes less
loading time if being imported by FLAC3D later. The ASCII-format grid file specification can be found with the zone import command description. If no file
extension is given, an extension of "f3grid" is used. The zone and face group information can be exported.
binary
exported grid file will be in binary-format instead of ASCII-format.
zone face apply command

Syntax
zone face apply keyword <range>
Primary keywords:
acceleration | acceleration-dip | acceleration-local | acceleration-normal | acceleration-strike | acceleration-x | acceleration-y | acceleration-z | convection | discharge |
flux | leakage | pore-pressure | quiet-dip | quiet-normal | quiet-strike | reaction | reaction-dip | reaction-local | reaction-normal | reaction-strike | reaction-x | reaction-y |
reaction-z | stress-dip | stress-normal | stress-strike | stress-xx | stress-xy | stress-xz | stress-yy | stress-yz | stress-zz | temperature | velocity | velocity-dip | velocity-local |
velocity-normal | velocity-strike | velocity-x | velocity-y | velocity-z | servo | vary | :class:
This command is used to apply boundary conditions at surface faces of the model. To apply conditions to zones rather than at faces, see the zone apply command. To
apply conditions at individual gridpoints, see the zone gridpoint fix command.
The user must specify the condition type, the numerical value or values associated with it, optional modifiers that may vary the value over time and space, and an
optional range over which the boundary condition is to be applied. If no range is specified, then the command applies to the entire model.
To remove a boundary created with this command, see zone face apply-remove.
After the supplied condition's value(s), an optional modifier keyword can be used to modulate the supplied value. These are marked <[keywordblock]> in the
commands, with definitions found in the "Keyword Block" section at the end of this topic.
Note that some apply conditions (like velocity) are actually applied to the gridpoints attached to all the faces in the range. This could cause a conflict between gridpoints
that are connected to multiple faces with conflicting apply conditions specified. Whenever possible, FLAC3D will attempt to satisfy all conditions — including
automatically adjusting the gridpoint local axes system to accomodate the constraints. If this is not possible, however, the velocity condition applied last will dominate.
Note
Occasionally you may want to apply a condition to a set of internal faces. To do this, we recommend temporarily nulling out one side with the zone cmodel assign
command, applying the condition, and then restoring the zones to their original constitutive model. This will allow the apply logic to select the appropriate orientation
when necessary — for applying stress boundary conditions, for example.
acceleration v <[keywordblock]>
vector of the acceleration components applied in the global coordinate axes (available only if model configure dynamic has been specified). This is a gridpoint
based condition.
acceleration-dip f <[keywordblock]>
acceleration component applied in the dip direction of the local gridpoint axes — available only if model configure dynamic has been specified (see Local
Axes System below). This is a gridpoint based condition.
acceleration-local v <[keywordblock]>
vector of the acceleration components applied in the local gridpoint axes — available only if model configure dynamic has been specified (see Local Axes
System below). This is a gridpoint based condition.
acceleration-normal f <[keywordblock]>
acceleration component applied in the normal direction of the local gridpoint axes — available only if model configure dynamic has been specified (see Local
acceleration-strike f <[keywordblock]>
acceleration component applied in the strike direction of the local gridpoint axes — available only if model configure dynamic has been specified (see Local
acceleration-x f <[keywordblock]>
x-component of acceleration applied at a gridpoint — available only if model configure dynamic has been specified. This is a gridpoint based condition.
acceleration-y f <[keywordblock]>
y-component of acceleration applied at a gridpoint — available only if model configure dynamic has been specified. This is a gridpoint based condition.
acceleration-z f <[keywordblock]>
z-component of acceleration applied at a gridpoint — available only if model configure dynamic has been specified. This is a gridpoint based condition.
convection f1 f2 <[keywordblock]>
A thermal convective boundary condition is applied over the range of faces specified (available only if model configure thermal has been specified). f1 is the
temperature Te of the medium to which convection occurs. f2 is the convective heat transfer coefficient h (e.g., in W/m2◦ C).
discharge f <[keywordblock]>
Fluid flux f is the component of the specific discharge vector (e.g., in m/s) applied normal to the boundary.
flux f <[keywordblock]>s
A flux is applied over the range of faces specified (available only if model configure thermal has been specified). f is the initial flux (e.g., in W/m2). This
command is used to specify a constant flux into (f > 0) or out of (f < 0) a thermal boundary of the grid. Decay of the flux can be represented by applying a time-
varying modifier available in <[keywordblock]>.
leakage f1 f2 <[keywordblock]>
f1 is the pore pressure in the leaky layer.
f2 is the leakage coefficient, h (e.g., in m3/N sec).
See this equation in Fluid Flow Boundary and Initial Conditions in FLAC3D for the formula for a leaky boundary condition. A leaky condition is applied over the
range of faces specified. The history keyword is not active for leakage.`
pore-pressure f <[keywordblock]>
Applies a specific pore-pressure value (available only if model configure fluid has been specified). This is a gridpoint based condition.
quiet-dip <[keywordblock]>
quiet (viscous) boundary applied in the dip direction of the local gridpoint axes — available only if model configure dynamic has been specified (see Local
Axes System below).
quiet-normal <[keywordblock]>
quiet (viscous) boundary applied in the normal direction of the local gridpoint axes — available only if model configure dynamic has been specified (see Local
Axes System below).
quiet-strike <[keywordblock]>
quiet (viscous) boundary applied in the strike direction of the local gridpoint axes — available only if model configure dynamic has been specified (see Local
Axes System below).
reaction <[keywordblock]>
vector of all components of reaction force at a gridpoint Reaction forces will only be applied in directions that are currently fixed, and those fixity conditions will
be removed. This is a gridpoint based condition.
reaction-dip <[keywordblock]>
reaction force in the dip direction of the local gridpoint axes Reaction forces will only be applied in directions that are currently fixed, and those fixity conditions
will be removed. This is a gridpoint based condition.
reaction-local <[keywordblock]>
Apply a reaction force in all components of the local coordinate system (see Local Axes System below). Reaction forces will only be applied in directions that are
currently fixed, and those fixity conditions will be removed. This is a gridpoint based condition.
reaction-normal <[keywordblock]>
reaction force in the normal direction of the local gridpoint axes (see Local Axes System below). Reaction forces will only be applied in directions that are
reaction-strike <[keywordblock]>
reaction force in the strike direction of the local gridpoint axes (see Local Axes System below). Reaction forces will only be applied in directions that are
reaction-x <[keywordblock]>
x-component of reaction force at a gridpoint Reaction forces will only be applied in directions that are currently fixed, and those fixity conditions will be
removed. This is a gridpoint based condition.
reaction-y <[keywordblock]>
y-component of reaction force at a gridpoint Reaction forces will only be applied in directions that are currently fixed, and those fixity conditions will be
reaction-z <[keywordblock]>
z-component of reaction force at a gridpoint Reaction forces will only be applied in directions that are currently fixed, and those fixity conditions will be
stress-dip f <[keywordblock]>
stress component applied in the dip direction of the local face axes (see Local Axes System below).
stress-normal f <[keywordblock]>
stress component applied in the normal direction of the local face axes (see Local Axes System below).
stress-strike f <[keywordblock]>
stress component applied in the strike direction of the local face axes (see Local Axes System below).
stress-xx f <[keywordblock]>
xx-component of the stress tensor applied at a face
stress-xy f <[keywordblock]>
xy-component of the stress tensor applied at a face
stress-xz f <[keywordblock]>
xz-component of the stress tensor applied at a face
stress-yy f <[keywordblock]>\
yy-component of the stress tensor applied at a face
stress-yz f <[keywordblock]>
xz-component of the stress tensor applied at a face
stress-zz f <[keywordblock]>
zz-component of the stress tensor applied at a face
temperature f <[keywordblock]>
Fixes and applies a specific temperature value to the gridpoint (available only if model configure thermal has been specified). This is a gridpoint based
condition.
vector of all velocity components in the global coordinate axes. This is a gridpoint based condition.
velocity-dip f <[keywordblock]>
velocity component applied in the dip direction of the local gridpoint axes (see Local Axes System below). This is a gridpoint based condition.
velocity-local v <[keywordblock]>
vector of all velocity components in the local coordinate axes (see Local Axes System below). This is a gridpoint based condition.
velocity-normal f <[keywordblock]>
velocity component applied in the normal direction of the local gridpoint axes (see Local Axes System below). This is a gridpoint based condition.
velocity-strike f <[keywordblock]>
velocity component applied in the strike direction of the local gridpoint axes (see Local Axes System below). This is a gridpoint based condition.
x-component of velocity applied at a gridpoint This is a gridpoint based condition.
y-component of velocity applied at a gridpoint This is a gridpoint based condition.
z-component of velocity applied at a gridpoint This is a gridpoint based condition.
Local Axes System
The local face axes are defined by the normal to the face. The dip, strike, and normal directions form a right-handed coordinate system. Given the normal vector, the
other local axes are defined by “d-axis,” which points downward (i.e., in the negative z-direction) along the dip-direction, and “s-axis,” which is horizontal (i.e., lies
within the xy-plane) such that d-s-n form a right-handed system as illustrated here.
Figure 1: Local face axes.
Keyword Block
Zone Face Apply Modifiers
The following keywords may be used to modify a supplied value. If the description of the modifier keyword mentions what type of value it may be applied to (e.g.
scalar value, vector value, etc.), be sure there is a match between the modifier and the main keyword value. The commands main keywords are: acceleration,
acceleration-dip, acceleration-local, acceleration-normal, acceleration-strike, acceleration-x, acceleration-y, acceleration-z, convection,
discharge, flux, leakage, pore-pressure, quiet-dip, quiet-normal, quiet-strike, reaction, reaction-dip, reaction-local, reaction-normal, reaction-
strike, reaction-x, reaction-y, reaction-z, stress-dip, stress-normal, stress-strike, stress-xx, stress-xy, stress-xz, stress-yy, stress-yz,
stress-zz, temperature, velocity, velocity-dip, velocity-local, velocity-normal, velocity-strike, velocity-x, velocity-y and velocity-z.
fish s
Specify a multiplier that is a FISH function named s. The returned value of this FISH function is multiplied by the base value (including gradient) over all zone
faces or gridpoints included in this apply condition. So a return value of 1.0 will apply the base value provided, and a return value of 0.0 will effectively remove
it. This function will be called every step. If the apply condition requires a vector value, this function should also return a vector. If the apply condition requires
two values, the function should return a vector and the z-component will be ignored.
fish-local s
Specify a multiplier that is a FISH function named s, which is applied separately to each individual zone face or gridpoint affected by this apply condition. This
function must take two arguments. For apply conditions that work directly on faces, the first argument is a pointer to the zone and the second argument is an
integer from 1 to 6 indicating the face. For apply conditions that work on gridpoints, the first argument is a pointer to the gridpoint and the second argument is not
used. This allows an apply condition to vary over time as well as space. The returned value of this FISH function is multiplied by the base value (including
gradient) on the specific zone supplied. So a return value of 1.0 will apply the base value provided, and a return value of 0.0 will effectively remove it. This
function will be called every step for every zone included in the apply condition. If the apply condition requires a vector value, this function should also return a
vector. If the apply condition requires two values, the function should return a vector and the z-component will be ignored.
gradient v
Apply a gradient to the scalar-value provided. This is not availble if the apply conditions requires two values or a vector value.
servo keyword ...
Use a servo tied to the mechanical convergence ratio to control the magnitude of the applied condition. This can be used to maintain, gradually ramp up, or
gradually reduce apply conditions while maintaining a quasi-static response. This controls a factor that is multiplied with the base value supplied. By default the
factor will start at 0.001, and will gradually increase to 1.0 as the convergence ratio falls below 2e-3, and decrease if it rises above 1e-2. The following keywords
are available to control the servo response:
latency i
The minimum number of steps that must pass since the last servo adjustment before the next one occurs. This can keep the servo from overcontrolling in
the initial response to a change in the factor. The default value is 1.
lower-bound f
Set the lower mechanical convergence ratio limit. If the current ratio falls below this limit, the factor will be multiplied by the lower-multiplier. The default
limit is :lflt:`2e-3'.
lower-multiplier f
If the current ratio falls below the lower-bound limit, the factor is multiplied by this number. The default is 1.01.
maximum f
The maximum value the factor is allowed to become. The default is 1.0.
minimum f
The minimum value the factor is allowed to become. The default is 0.001.
ramp
Sets the servo into ramp mode. This means that the factor is not allowed to go down, the value will only increase. This is useful to gradually increase an
applied condition to it's full value. See also the reduce keyword.
ratio keyword
Which mechanical convergence ratio is compared against lower-bound and upper-bound. By default this is the current value assigned by the zone ratio
command (which is average by default. See the zone ratio command for definitions. The available keywords are:
average
Use the average mechanical force ratio.
maximum
Use the maximum mechanical force ratio.
local
Use the local mechanical force ratio.
reduce
Sets the servo into reduce mode. In this mode the starting value of the factor is 1.0, and the minimum value is set to 0.0. When the current ratio falls below
lower-bound the factor is reduced by the upper-multiplier. The factor is never increased. This is useful to gradually decrease an applied condition to zero.
upper-bound f
Set the upper mechanical convergence ratio value. If the current ratio rises above this value, the factor will be multiplier by the upper-multiplier. The
default is 1e-2.
upper-multiplier f
If the current ratio rises above the upper-bound, the factor is multiplied by this. The default is 0.975.
system keyword ...
The local coordinate system used by the apply condition may be specified explicitly by the user. By default, this coordinate system is determined auomaticaly.
For faces it is determined by the normal direction of the face. For gridpoints it is determined by the average normal vectors of all faces connected to the gridpoint
that are a part of this apply condition.
The local coordinate system may be specified in one of two ways, using by either the keyword normal or using the keywords dip and dip-direction together.
normal v
v is the unit normal vector to the plane.
dip f
dip [degrees], f, of the plane measured in the negative z-direction from the global xy-plane.
dip-direction f
dip-direction [degrees], f, of the plane measured in the global xy-plane clockwise from the positive y-axis.
Specify a multiplier that is a table named s. By default the x-axis value is the current step number. The optional time keyword may be used to specify which
processes accumulated time-total should be used to provide the x-axis value. The available keywords are:
creep
dynamic
fluid
mechanical
step
thermal
vary v
:class: rblock
Apply a linear variation to the scalar-value provided. This is not availble if the apply conditions requires two values or a vector value.
[DR: is location of local axes here ok, or should it be elsewhere? And, is more material needed?
zone face apply-remove command

Syntax
zone face apply-remove <keyword> <range>
Remove zone face apply conditions, which are described in the documentation for that command. If an optional range is supplied, the condition is removed only
from those faces within the range. If no keyword is specified, then all conditions applied to the specified faces are removed.
acceleration
acceleration-dip
acceleration-local
acceleration-normal
acceleration-strike
acceleration-x
acceleration-y
acceleration-z
convection
discharge
flux
leakage
pore-pressure
quiet-dip
quiet-normal
quiet-strike
reaction
reaction-dip
reaction-local
reaction-normal
reaction-strike
reaction-x
reaction-y
reaction-z
stress-dip
stress-normal
stress-strike
stress-xx
stress-xy
stress-xz
stress-yy
stress-xz
stress-zz
velocity
velocity-dip
velocity-local
velocity-normal
velocity-strike
velocity-x
velocity-y
velocity-z
zone face group command

Syntax
zone face group s keyword ... <range>
Primary keywords:
fluid | internal | mechanical | or | remove | slot | thermal
Adds a group name s to zone faces included in the optional range. Use of the group logic is described in Group. This command may take the form zone face group
"slotname = groupname" — quotation marks required, spaces at equals sign ignored — where slotname is the slot assignment and groupname is the group name.
A zone face may belong to many groups, up to a maximum of 128. The group range element can be used to select objects by group name.
Both the group and the slot can be encoded into the single string s. To do this use the composition 'slotname=groupname', where the name to the left of the equals sign
Note that by default only surface faces are modified. To select all faces use the internal keyword described below.
The following optional keywords are available:
fluid
Zones with a non-null fluid model are scanned to determine the surface faces. Applies only if internal is not specified.
internal
If specified, then the range looks at internal faces as well as surface faces.
mechanical
Zones with a non-null mechanical model are scanned to determine the surface faces. Applies only if internal is not specified.
or
Cannot be used with internal. By default, if more than one mechanical, thermal or fluid keyword is given, then the zone needs to have all of those conditions to
determine a surface face. In other words, if both mechanical and thermal were given, then if the zone had a non-null mechanical model and a null thermal model
it would be considered outside the surface. If the or keyword is given, then it is considered inside the surface if any of those conditions has a non-null model.
remove
The group is removed from the zone face if present. If the slot keyword is used, then the group is only removed from that slot if present. Otherwise the group is
removed from any slot it is found in.
slot s
The group is assigned to the slot named s. If not supplied, the group is assigned to the default slot, which is the one named default.
thermal
Zones with a non-null thermal model are scanned to determine the surface faces. Applies only if internal is not specified.
zone face hide command

Syntax
zone face hide <keyword> ... <range>
Primary keywords:
b | group | id | internal | only-grouped | skin | undo | use-hidden-zones
Hide or un-hide zone faces in the range.
This command hides or un-hides zone faces in the range, depending on the keyword options below. By default, commands have no affect on hidden zone faces unless
the use-hidden keyword is used in the range specification.
Note that by default only surface faces are selected. To select all faces use the internal keyword described below.
If present, sets whether zone faces will be hidden (on) or un-hidden (off). The default value if not specified is on.
group s keyword
Specifies that only zone faces that are in the specified groups will be affected. Use of the group logic is described in Group. This keyword is incompatible with
the keywords id and skin. Note that by default, zones connected to faces will also be checked for a match. So a face will be considered to match group Fred either
if it has been assigned to group Fred directly, or if either of the possible zones it is connected to has been assigned that group. A range phrase cannot be given if
this keyword is used. The following additional keywords are available to determine the group designation will be used:
and s
Indicates that the zone faces selected need to be both in the original group and group s in order to be modified. This is incompatible with the or keyword
and the slot keyword. Any number of groups can be combined via multiple and keywords.
or s
Indicates that the zone faces selected can be in the original group or group s, and both will be modified. This is incompatible with the and keyword. Any
number of groups can be combined via multiple or keywords.
only
Indicates that the list of on or more groups specified must define all the groups assigned to the zone face. If there are any additional groups, they will not be
modified.
by s
Indicates whether the group check will be made by face or by zone. If specified then only group assignments for that object specifically will be considered.
By default a face will be selected either if it has that group assignment directly, or if a zone it is connected to has that group assignment.
matches i
Objects that by default participate in a hierarchy may match a given group more than once. For example, zone face may match a group if they have been
assigned that group directly, or are connected to a zone that has that group assignment. So for a given group, a zone face might find a match from 0 to 2
times. The match keyword allows you to specify how many matches are required for each group provided. The default value is 1.
slot s
By default, a group will match if the face has that group assigned in any slot. The slot keyword allows you to specify which slot to look in specifically,
ignoring all the others.
id iz side is
Specifies that a single zone face will be affected. This face is identified by the zone ID number iz and the side number is. This keyword is incompatible with the
keywords group and skin. A range phrase cannot be given if this keyword is used.
internal
Include internal faces when hiding zone faces in the specified range. If this keyword is not supplied, by default the command will only hide external zone faces in
the specified range.
only-grouped s <slot s >
Specifies that only the set of faces that have had group names assigned should be considered. Other filter options are allowed. If an option slot is specified, then
only the set of faces with group assignments in that particular slot will be considered.
skin keyword
Specifies that a set of contiguous faces are to be selected, starting at the point where a ray from a given point in a given direction intersects a surface face. The
following keywords are available to define the faces selected:
start v
Defines the starting point of the ray used. By default this value is (0,0,0).
direction v
Defines the direction taken from the starting point. By default this value is (0,0,1).
break-angle f
Defines the angle between faces necessary to break continuity. By default this angle is 45 degrees. This means that if the faces connect at an angle greater
than 45 degrees, they are not considered to be part of the same contiguous group.
undo
Undo the last zone face hide command. The undo keyword will reverse the operation of the last hide command, up to 12 times (the program keeps a maximum
stack 12 zone face hide commands). This keyword is incompatible with any other keyword (including a following range phrase), and must be given alone.
use-hidden-zones
Include faces on zones that are within the specified range but also hidden. If this keyword is not supplied, faces on zones that are hidden will not be included in
the operation of the command, even if they otherwise exist within the range specified.
zone face list command

Syntax
zone face list keyword <range>
Primary keywords:
apply | groups | information
List information about zone faces.
apply <keyword>
Values and types of applied conditions at zone faces are listed. If the optional keyword is omitted, conditions is used as the default.
conditions
List the apply conditions that have been created on faces. This does not list each condition on each face, rather it lists the separate apply conditions that
have been created. For example the command zone face apply stress-normal would create one entry no matter how many individual faces were
involved. The range phrase is not used for this keyword.
items
Display the conditions that are being applied to each face in the range.
items-gridpoints
Displays a list of conditions that are being applied to each gridpoint in the range, caused by conditions applied to connected faces. The range phrase for this
keyword applies to the list of all gridpoints.
groups
Lists the groups assigned to each face in the range, as well as the gridpoints that make up the face and the zones on each side.
information
For each face in the range, lists the gridpoint ids that it is connected to, the zones on either side, the hide and select status, and any group assignments that exist.
zone face select command

Syntax
zone face select <keyword> ... <range>
Primary keywords:
b | group | id | internal | only-grouped | skin | undo | use-hidden-zones
Select or deselect zone faces in the range.
This command selects or de-selects zone faces in the range, depending on the keyword options below. Selected objects may be identified in a range by using the
selected keyword in the range specification.
Note that by default only surface faces are selected. To select all faces use the internal keyword described below.
If present, sets whether zone faces will be select (on) or deselected (off). The default value if not specified is on.
group s keyword
Specifiy that only zone faces that are in the specified groups will be affected. Use of the group logic is described in Group. This keyword is incompatible with the
keywords id and skin. Note that by default, zones connected to faces will also be checked for a match. So a face will be considered to match group Fred either if it
has been assigned to group Fred directly, or if either of the possible zones it is connected to has been assigned that group. A range phrase cannot be given if this
keyword is used. The following additional keywords are available to determine the group designation will be used:
and s
Indicate that the zone faces selected need to be both in the original group and group s in order to be modified. This is incompatible with the or keyword and
the slot keyword. Any number of groups can be combined via multiple and keywords.
or s
Indicates that the zone faces selected can be in the original group or group s, and both will be modified. This is incompatible with the and keyword. Any
number of groups can be combined via multiple or keywords.
only
Indicates that the list of on or more groups specified must define all the groups assigned to the zone face. If there are any additional groups, they will not be
modified.
by s
Indicates whether the group check will be made by face or by zone. If specified then only group assignments for that object specifically will be considered.
By default a face will be chosen either if it has that group assignment directly, or if a zone it is connected to has that group assignment.
matches i
Objects that by default participate in a hierarchy may match a given group more than once. For example, zone face may match a group if they have been
assigned that group directly, or are connected to a zone that has that group assignment. So for a given group, a zone face might find a match from 0 to 2
times. The match keyword allows you to specify how many matches are required for each group provided. The default value is 1.
slot s
By default, a group will match if the face has that group assigned in any slot. The slot keyword allows you to specify which slot to look in specifically,
ignoring all the others.
id iz side is
Specifies that a single zone face will be affected. This face is identified by the zone ID number iz and the side number is. This keyword is incompatible with the
keywords group and skin. A range phrase cannot be given if this keyword is used.
internal
Include internal faces when selecting zone faces in the specified range. If this keyword is not supplied, by default the command will only select external zone
faces in the specified range.
only-grouped s <slot s >
Specifies that only the set of faces that have had group names assigned should be considered. Other filter options are allowed. If an option slot is specified, then
only the set of faces with group assignments in that particular slot will be considered.
skin keyword
Specifies that a set of contiguous faces are to be chosen, starting at the point where a ray from a given point in a given direction intersects a surface face. The
following keywords are available to define the faces selected:
start v
Defines the starting point of the ray used. By default this value is (0,0,0).
direction v
Defines the direction taken from the starting point. By default this value is (0,0,1).
break-angle f
Defines the angle between faces necessary to break continuity. By default this angle is 45 degrees. This means that if the faces connect at an angle greater
than 45 degrees, they are not considered to be part of the same contiguous group.
undo
Undo the last zone face select command. The undo keyword will reverse the operation of the last select command, up to 12 times (the program keeps a
maximum stack 12 zone face select commands). This keyword is incompatible with any other keyword (including a following range phrase), and must be
given alone.
use-hidden-zones
Include faces on zones that are within the specified range but also hidden. If this keyword is not supplied, faces on zones that are hidden will not be included in
the operation of the command, even if they otherwise exist within the range specified.
zone face skin command

Syntax
zone face skin <keyword ... ><range>
Primary keywords:
break-angle | internal | slot | slot-skin | use-hidden-zones
Skin the model to automatically generate face groups. "Skinning" refers to automatic face group generation, which occurs as follows: the program looks for contiguous
faces and puts them into automatically named groups within the slot named skin. Two faces are not considered contiguous if: the angle between two faces exceeds the
break angle, or if the two faces belong to different groups according to the command's slot specification. Unless internal is specified, the operation of the command is
restricted to external faces. For this command, only zone faces that have no zone on the other side, a hidden zone on the other side, or a mechanically null zone on the
other side, are considered surface faces. When use-hidden-zones is used, zone faces within the specified range will be included for consideration, even if they are a part
of zones that are currently hidden.
Group names are generated as follows:
Surface faces are assigned a name based on the face normal vector. If the normal vector x component is larger (in the absolute sense) than the y
and z then it will be assigned the name sEast if it is positive or sWest if it is negative. If the y component is larger than the z then it will be
assigne the name sNorth if it is positive or sSouth if it is negative. Otherwise it will be assigned the name sTop if the z-component is positive
or sBottom if it is negative.
Internal faces (if present) are assigned the names of the group on either side that changed in order to create them, with a colon s: character
between. So an interface surface marking the boundary between groups sFred and sGeorge will be named sFred:George.
If more than one collection of faces is assigned the same name, then a number will be appended to the name to keep them distinct. So sEast1
and sEast2 for example.
The following keywords are currently available:
break-angle f
Specify the angle that is used to determine face contiguity for inclusion in a skin group. The default break angle is 45 degrees.
internal b
Include internal faces when creating face groups. This will assign group names to faces along internal boundaries where the zone group assignments change. The
default is off.
slot s
Identify the slot that contains the groups to be used for consideration of contiguity. Use of the group logic is described in Group. If this keyword is omitted, zone
group assignments will be ignored and the internal keyword will not do anything. Use the the special any slot assignment to use all slots.
slot-skin s
Place the groups created by this command in a slot named s. If this keyword is omitted, the groups will be place in a slot named skin.
use-hidden-zones b
Include faces that are on currently hidden zones if they are within the range. By default this values is off.
zone face westergaard command

Syntax
zone face westergaard <keyword> ... <range>
Primary keywords:
direction | height | base | density-water | factor
Applies the Westergaard approximation for the dynamic response of water to the surface faces in the range. This operates by changing the inertial mass of the gridpoints
connected to the surface faces in the range. This command is only available if model configure dynamic has been specified.
As with most zone face commands, this command will only operate on surface faces in the range.
direction f
reversal direction of the hydrodynamic wave propagation. This direction must be in horizontal plane.
height f
height of the water in the reservoir
base f
elevation of the base of the reservoir
density-water f
density of the water in the reservoir
factor f
optional coefficient, the default value is 0.743
zone face westergaard-remove command

Syntax
zone face westergaard-remove <range>
Removes any applied westergaard condition on the faces in the range.
zone fluid command

Syntax
zone fluid keyword
Primary keywords:
active | biot | cmodel | fastflow | fastflow-relaxation | implicit | list | property | permeability | dip | dip-direction | permeability-1 | permeability-2 | permeability-3 |
permeability-xx | permeability-xy | permeability-xz | permeability-yy | permeability-yz | permeability-zz | rotation | property-distribution | saturation-tolerance | time-
total | track | zone-based-pp
This command sets parameters for a groundwater fluid flow analysis. These commands are only available after a model configure fluid command. These
parameters apply to zones only, other model elements may have different values.
active b
The fluid process is on for zones, by default, when the model configure fluid command is given. Specify active off to suppress the fluid calculation for zones.
Generally this command is unnecessary and is slaved to the zone fluid active setting.
biot b
The fluid-flow calculation uses the Biot coefficient, α, and the Biot modulus, M, if on. If off, then the fluid modulus, Kf , and porosity, n, are used and α = 1. The
default is off. See Biot Coefficient and Biot Modulus.
cmodel keyword
Associates a fluid constitutive model with specified zones in the grid. It also allows querying of properties and states of constitutive models.
assign keyword <range>
assigns a fluid model to all zones in the range. This keyword may only be given if the model is configured for fluid calculations (see model configure
fluid). Fluid models are described in Grid Configured for Fluid Flow.
anisotropic
Assign the anisotropic flow model.
isotropic
Assign the isotropic flow model.
null
Assign the null fluid model.
list
List the available fluid constitutive models and their properties.
fastflow b
Turns the fastflow solution scheme on and off. See Fully Saturated Fast Flow.
fastflow-relaxation f
Sets the relaxation parameters used in the fastflow solution scheme.
implicit b
The implicit solution scheme in the fluid flow model is turned on or off. The default is off.
list
information
Outputs current configuration settings and status information for the fluid model.
property s <range>
Outputs the values of the fluid property s in all zones in the range.
Assigns properties for the fluid flow constitutive models of all zones in the rnage. Any number of name value pairs may be assigned. The type of the value a must
match the type expected by the property s. Any constitutive model that has a matching property name will be assigned the value.
biot f
Biot coefficient (grain compressibility), . The default is 1.0.
porosity f
Porosity, . The default is 0.5.
undrained-thermal-coefficient f
Undrained thermal coefficient, .
Isotropic Fluid Flow:
permeability f
Isotropic permeability, . The permeability used in FLAC3D is defined as the conventional hydraulic Permeability divided by the unit weight of
water. Permeability must be non-zero if the command zone fluid active on applies.
Anisotropic Fluid Flow:
dip f
Principal permeability plane dip angle (in degrees).
dip-direction f
Principal permeability plane dip direction angle (in degrees).
permeability-1 f
Principal permeability value.
permeability-2 f
permeability-3 f
permeability-xx f
xx-component permeability.
permeability-xy f
xy-component permeability.
permeability-xz f
xz-component permeability.
permeability-yy f
yy-component permeability.
permeability-yz f
yz-component permeability.
permeability-zz f
zz-component permeability.
rotation f
Principal permeability plane rotation angle (in degrees).
property-distribution s akeyword <range>
Assigns a single property name to the fluid flow constitutive models of all zones in the range. The property value may be varied in space by using the following
optional keyword values.
add
Add a to the property value. This keyword only applies to float type property values.
deviation-gaussian f
A gaussian distribution is used to assign the value randomly, with a mean value of a and a standard deviation of f. This keyword only applies to float type
property values.
deviation-uniform f
A uniform distribution is used to assign the value randomly, with a mean value of a and a standard deviation of f. This keyword only applies to float type
property values.
Apply a gradient to the property value. This keyword only applies to float type property values.
multiply
Multiply the property value by a.
vary v
Apply a linear variation to the property value. This keyword only applies to float type property values.
saturation-tolerance f
The effect of saturation changes to gridpoints is only applied when the accumulated saturation change is greater than this value. This is done for efficiency of
calculation. The default value is 1x10:exp:-3
time-total f
Specifies the accumulated zone fluid time, defined as the sum of all the timesteps over which zone fluid is active. Once set, fluid time will continue to accumulate
with subsequent cycles.
track keyword
The TRACK command places a particle in the grid at the location specified. The particle flows with the fluid and maintains a record of its path over a finite
period of time. The grid must be configured for fluid flow (see model configure fluid), and the zone must have a non-null fluid model in order for a particle to
exist in a zone. The particle is not created (and no error message is output) if the location does not map into a zone with these specifications. The particles have no
mass and do not influence the flow or mechanical behavior in any way; they are simply carried along by the fluid and record its motion. Several TRACK
commands may be given, at different times, if desired. See the data files in One-Dimensional Filling of a Porous Region for an example of particle track usage.
Location and keywords are given as follows.
active b
Turns particle tracking on or off. track is off by default.
create keyword
Create one or more particles in zones. The location and number of the particles created are controlled by the following keywords. The <[keywordblock]>
following can be used to specify attributes on the created particles.
point v ... <[keywordblock]>
Place a particle in the grid at the specified location v. For each vector value given, another particle will be created.
line keyword ... <[keywordblock]>
Add particles to the grid along a line.
begin v
Specify the start position of the line. The default value is (0,0,0).
end v
Specify the end position of the line. The default value is (0,0,0).
segment i
Specify the line be divided equally into i + 1 segments, causing i particles to be introduced into the grid. The default value is 2.
plane keyword ... <[keywordblock]>
Add particles to the grid along a plane defined by two lines.
begin v
Specifies the shared start point of both lines that will define the plane. The default value is (0,0,0).
end-1 v
Specifies end of the first line. The default value is (0,0,0).
end-2 v
Specifies end of the second line. The default value is (0,0,0).
segment i1 i2
Divides the first line into i1 + 1 equal segments; divides the second line into i2 + 1 equal segments. i1 x i2 particles will be introduced to the
grid on an evenly spaced grid along the plane. The default value of i1 and i2 is 2.
delete <range>
Delete particles within the given range
group s keyword <range>
Assign or remove groups to particles in the range. Use of the group logic is described in Group.
remove
Remove the group s from particles within the given range. This does not remove the particles themselves.
slot s
Assign groups in the given range to the slot named s. By default groups will be assigned to slot Default
list <path>
lists summary information about tracking particles. If the path keyword is omitted, the current particle position information is output. If the path keyword is
included, then particle path information is output.
trace <name s > i
Creates a location trace (see the trace command) of the particle with ID number i.
zone-based-pp b
Indicates that pore-pressures should be retrieved directly from the zone, rather than averaged from the gridpoints. Zone pore pressures must be assigned manually
via FISH, using the zone.pp intrinsic.
Keyword Block
Zone Fluid Track Create Modifiers
At the time of particle creation the following additional configuration settings may optionally be supplied. They apply to the keywords: line, plane and point.
group s1 <slot s2 >
Assign the created particles to the group s1 and (if supplied) assign that group to slot s2. By default the slot name will be Default.
tail b
When on (the default setting), particles will automatically store a list of coordinates along their path as they move through the grid. If off
particles will only keep track of their current position.
tortuosity f
The tortuosity is specified as f, which is defined as the ratio of the straight line path to the actual fluid path through a zone. This factor
will be used to multiply track increments calculated from the flow velocity; it defaults to 1 if not given.
[DR: please check that "see ---- " links here land where they should]
zone generate command

Syntax
zone generate keyword
Primary keywords:
from-building-blocks | from-extruder | from-topography | from-geometry
This set of commands generates zones based on an algorithm, generally from some other data structure. The following keywords are available:
from-building-blocks <set s >
Generate zones from the current building-blocks set. See the building-blocks command. If the optional keyword set is used, then will generate zones from the
set with name s instead of the current set.
from-extruder <set s >
Generate zones from the current extruder set. See the extruder command. If the optional keyword set is used, then will generate zones from the set with name s
instead of the current set.
from-topography <keyword ...> <range>
Generates zones by extruding surface faces in the range until they meet polygons in a geometric set.
Discussion and examples on the use of this option to create zones can be found in Surface Topography and Layering.
geometry-set s
Specify the geometry set used to define the surface to which zones are being extruded. By default the current geometric set will be used.
segments i
Specify the number of zone layers created between the existing surface zone faces and the geometry set. By default this value is 1.
direction v
Specify the extrusion direction that will be used to create zones on surface faces. From a surface gridpoint, a ray will be cast in this direction until it
intersects a polygon in the geomtric set. This will define the shape and size of the zones created. By default this value will be (0,0,1). If a face normal is
parallel to this direction vector (with a tolerance of about 0.5 degrees) the face will be neglected even it if is in the range.
ratio f
Specify the ratio used to distribute zones from the surface face to the geometric set. A ratio of 1.1 means that each zone edge in that direction will be 1.1
times the length of the previous zone. If not specified, the default ratio is 1.0.
group s1 <slot s2 >
Assign the group s1 to the created zones, in slot s2. If not specified, the default slot is Default. Use of the group logic is described in Group.
face-group s1 <slot s2 >
Assign the group s1 in slot s2 to the new surface faces created by extruding the original faces selected. By default no group name is assigned. If not
specified, the slot used will be Default.
from-geometry <keyword> ...
Generate zones by identifying closed volumes in a geometric set, and creating tetrahedral zones that fill the volume. The following optional keywords are
available.
set s
Specify the geometry set used to define the surface to which zones are being extruded. By default the current geometric set will be used.
maximum-edge f
Specify the maximum edge length for any tetra to be generated. The actual maximum edge length will be close to this, but the result is not guaranteed to be
exact.
gradation f
Rate at which, on the surface of the tetrahedral mesh, neighboring triangle sizes vary as triangles increase or decrease in size due to local size adaptation.
offset f
Offset distance between the input surface and the surface of the resulting tetrahedral mesh measured in thousandths of the length of the bounding box
diagonal.
cut-angle f
Threshold angle for the capture of surface features. The default value is 45°. Use a larger cut angle smooth over unwanted surface features associated with
the coarseness of the triangulation. Use a smaller cut angle if if there are intersecting surfaces after surface remeshing.
verbose b
The default value is off. If set to on the tetra generation process emits information and diagnostic information to the console.
hexahedron
If specified, then an attempt will be made to fill the volume with hexahedral blocks.
bring-to-building-blocks
If specified, then the result of the volume discretization will also be sent to a building-blocks set.
grid-file s
If specified, then the result of the volume discretization will be sent to output file s (no zones generated). Grid-File keyword has no effect if Bring-To-
Building-Blocks is present.
zone geometry-test command

Syntax
zone geometry-test <range>
Evaluate the integrity of model zones. FLAC3D has three basic tests built in to check the integrity of gridded models, to make sure that the model is adequate for
simulation purposes. For example, these tests can be used to check whether there is improper mapping of gridpoints during execution of a grid-generation data file in
FLAC3D, resulting in some zones being inside out and, hence, not suitable for simulation. It can also be used to check whether a zone is degenerate. Degeneracy can
occur if a primitive is created without satisfying the requirements of geometry conditions, such as the number of vertices, edges and faces for that particular primitive.
Warning messages are given if any of the zone primitives are degenerate or cannot support two overlays.
In addition to tests for degeneracy and overlay support, the geometric aspects of zones are further evaluated using four quantities: aspect ratio, volume ratio,
orthogonality and face planarity. The quantities compare the zones to an idea one - a zone that all edges are equal, except for a degenerate brick zone whose idea one is
assumed to a degenerated cube. zone geometry-test invokes the test for all four of these geometric quantities.
Aspect Ratio — The ratio of the shortest edge length to the longest edge length. This will be assumed 1.0 for an ideal zone. It will approach zero as the zone becomes
stretched or flattened. The result is required to be normalized for degenerate brick zones with a multiplication factor of . See FISH function zone.aspect or
zone.condition.
Volume Ratio — The ratio of the smallest tetrahedron and the averaged tetrahedron in the zone. For wedge, tetrahedron, pyramid and degenerate brick zone type with
ideal shape, this measurement gives 1. However, for an ideal brick, it gives 5/6. Thus the result is required to be normalized for brick zones with a multiplication factor
of 1.2. See FISH function zone.condition.
Orthogonality — A measurement of how "well" sides of the zones are inclined to each other. For each gridpoint in each zone, the determinant of the matrix defined by
the three edge vectors is computed and divided by the product of their lengths. This gives 1.0 for a cube, and approaches zero as pairs of edges approach being coplanar
or all three approach being coplanar. Each zone is measured by the worst orthogonality value of all gridpoints. The result is required to be normalized with a
multiplication factor of and with for other non-brick zones. See FISH function zone.ortho or zone.condition.
Face Planarity — Hexahedrons are composed of 6 quadrilateral faces, just like a cube’s square faces. However, it is possible that the four vertices of a quadrilateral
polygon will not be coplanar in 3D. FLAC3D allows faces to be nonplanar, but the greater the deviation, the less accurate the solution process will be. There is no clear
singular method of measuring planarity. A method that compares the volume of a tetrahedron filling the 4 vertices and the area of the quadrilateral face, computing the
area by adding a central point, m = (A + B + C + D)/4, and computing the 4 triangle areas, ABC, ABD, ACD, BCD, is chosen. The ratio of the cube root of the volume
to the square root of the area (to get a dimensionless value) is computed. This value is zero if planar, and positive if nonplanar. This test can be “scaled” by a constant
because there is no fundamental limit on how nonplanar a face can be. (Values should be << 1.0 for a face to be good.) Each zone has its six faces tested, and the worst
value is reported.
Reporting average values for these tests are meaningless because some grids might be 90% good and 10% bad and give the same average as a grid with an 80% test
quality. Instead, distribution of values for all of the four parameters across all zones in the range specified is reported. The distribution ranges from 0 to 1.0, with a 0.1
interval. Thus, all zones fall within these 10 intervals. This distribution helps identify the number of bad zones, and how bad these zones are. Note that these tests are
useful for relative comparisons between different grids for the same geometry. For a model to perform well with FLAC3D, aspect ratio, volume ratio and orthogonality
should be near 1.0, and planarity test values near 0.0. FISH functions (see zone.condition) can be written to group all zones that failed to meet minimum standards,
and thus visualize the bad zones.
zone geometry-tolerance command

Syntax
zone geometry-tolerance f
This command defines the tolerance before an illegal geometry error happens in response to zone deformation. The user input f is the minimum ratio of the volume of a
tetrahedral subzone to the zone volume. FLAC3D signals an illegal geometry error if that ratio is less than f for any tetrahedral subzone in the model. The default value
is 0.0.
Note: Be aware that zone geometry is checked only every 10 steps in large-strain model. So, if the tolerance is set too close to zero, an error may be signalled elsewhere
in the calculation before exiting at the selected ratio. Also note that the typical minimum subzone volumes are 0.2 of the full zone volume. So the maximum value
selected for the ratio should be less than 0.2 to avoid premature termination of cycling.
zone geometry-update command

Syntax
zone geometry-update i
Updates associated with geometric or property changes are performed at the start of every model solve command (including model step and model cycle). In large
strain mode, these calculations are also updated every 10 steps by default. The number of steps between these large strain updates can be change with this command to
every i steps.
zone gridpoint create command

Syntax
zone gridpoint create v <keyword>
Primary keywords:
group | name
Create a single gridpoint. The gridpoint is created at position v. The following keywords are available to assign attributes to the created gridpoint.
group s1 <slot s2 >
The gridpoint is assigned to group s1 if the optional group keyword is used. The group is assigned to slot s2 if the optional slot keyword follows; it is assigned to
the slot named Default if not. Use of the group logic is described in Group.
name s
The created gridpoint is assigned the name s, for later reference. This name can be used with the point keyword of the zone create command so that gridpoints
can be created ahead of time to mark key points in space. Note that this name is distinct from any and all group assignments that can be made to the gridpoint.
zone gridpoint fix command

Syntax
zone gridpoint fix keyword <range>
Primary keywords:
acceleration | acceleration-x | acceleration-y | acceleration-z | force-applied | force-applied-x | force-applied-y | force-applied-z | pore-pressure | source | temperature |
velocity | velocity-x | velocity-y | velocity-z | well
Fix a property at all gridpoints in the range. If a fixed displacement is required, the appropriate velocities should be initialized to zero. (Zero velocity is the default on
start-up.) To provide a boundary condition to a surface of the model, see the zone face apply command.
acceleration <v >
Fix acceleration. If v is given, acceleration is fixed at that value. This is only available if model configure dynamic has been specified. The value is always in
terms of the gridpoint local coordinate system, if any.
acceleration-x <f >
Fix x-acceleration. If f is given, x-acceleration is fixed at that value. This is only available if model configure dynamic has been specified. The value is always
in terms of the gridpoint local coordinate system, if any.
acceleration-y <f >
Fix y-acceleration. If f is given, y-acceleration is fixed at that value. This is only available if model configure dynamic has been specified. The value is always
acceleration-z <f >
Fix z-acceleration. If f is given, z-acceleration is fixed at that value. This is only available if model configure dynamic has been specified. The value is always
force-applied <v >
Fix applied force. If v is given, applied force is fixed at that value. Note that this value is independent of either force-based apply conditions, or forces applied via
FISH. The value is always in terms of the gridpoint local coordinate system, if any.
force-applied-x <f >
Fix applied force in the x-direction. If f is given, applied force in the x-direction is fixed at that value. Note that this value is independent of either force-based
apply conditions, or forces applied via FISH. The value is always in terms of the gridpoint local coordinate system, if any.
force-applied-y <f >
Fix applied force in the y-direction. If f is given, applied force in the y-direction is fixed at that value. Note that this value is independent of either force-based
force-applied-z <f >
Fix applied force in the z-direction. If f is given, applied force in the z-direction is fixed at that value. Note that this value is independent of either force-based
pore-pressure <f >
Fix pore pressures. If f is given, the pore pressure is fixed at that value. Note that if the current pore-pressure is changed, the difference is stored in the fluid-
mechanical coupling logic and will be applied to the zones in the next mechanical step. This will adjust the total stress but keep the effective stress constant. This
is in comparison to using the zone gridpoint initialize pore-pressure, which will keep the total stress constant but change the effective stress.
source <f >
Apply a thermal source to the gridpoint. Note that this value is independent of sources applied either by apply commands or by FISH.
temperature <f >
Fixes temperatures. If f is given, the temperature is fixed at that value. This is only available if model configure thermal has been specified.
velocity <v >
Fixes velocity. If v is given, velocity is fixed at that value. The value is always in terms of the gridpoint local coordinate system, if any.
velocity-x <f >
Fixes x-velocity. If f is given, the x-velocity is fixed at that value. The value is always in terms of the gridpoint local coordinate system, if any.
velocity-y <f >
Fixes y-velocity. If f is given, the y-velocity is fixed at that value. The value is always in terms of the gridpoint local coordinate system, if any.
velocity-z <f >
Fixes z-velocity. If f is given, the z-velocity is fixed at that value. The value is always in terms of the gridpoint local coordinate system, if any.
well <f >
Applies a fluid source to the gridpoint. This is only available if model configure fluid has been specified.
zone gridpoint force-reaction command

Syntax
zone gridpoint force-reaction <keyword> <range>
Primary keywords:
all | x | y | z
For each gridpoint in the range, in each of the the specified degree-of-freedoms, checks if the gridpoint is fixed in that direction. If it is, then the fixity condition is
removed and an applied force is created (as with zone gridpoint fix force-applied) that is equal and opposite to the reaction force present. Assuming the model
was in equilibrium, the gridpoint will have removed the fixity condition and still be in equilibrium.
all
Create reaction forces in all degrees-of-freedom. This is the default value.
Create reaction forces in the local x-direction only.
Create reaction forces in the local y-direction only.
Create reaction forces in the local z-direction only.
zone gridpoint free command

Syntax
zone gridpoint free keyword <range>
Primary keywords:
acceleration | acceleration-x | acceleration-y | acceleration-z | force-applied | force-applied-x | force-applied-y | force-applied-z | pore-pressure | source | temperature |
velocity | velocity-x | velocity-y | velocity-z | well
Free properties at gridpoints in the range. The list of properties here is identical to that for zone gridpoint free, where they are also described.
acceleration
Free acceleration.
acceleration-x
Free x-acceleration.
acceleration-y
Free y-acceleration.
acceleration-z
Free z-acceleration.
force-applied
Free applied force.
force-applied-x
Free applied force in the x-direction.
force-applied-y
Free applied force in the y-direction.
force-applied-z
Free applied force in the z-direction.
pore-pressure
Free pore pressures.
source
Frees the applied thermal source.
temperature
Frees temperatures.
velocity
Frees velocity.
velocity-x
Frees x-velocity.
velocity-y
Frees y-velocity.
velocity-z
Frees z-velocity.
well
Frees an applied fluid source.
zone gridpoint group command

Syntax
zone gridpoint group s <keyword> <range>
Primary keywords:
remove | slot
Assign group name s to zone gridpoints in the range. Use of the group logic is described in Group.
Both the group and the slot can be encoded into the single string s. To do this use the composition 'slotname=groupname', where the name to the left of the equals sign
remove
Remove group s from the gridpoint. If no slot is specified the group assignment is removed from all slots it is found in.
slot s
Assign the group to the slot named s. The default slot is Default.
zone gridpoint initialize command

Syntax
zone gridpoint initialize keyword <range>
Primary keywords:
biot | displacement | displacement-x | displacement-y | displacement-z | displacement-small | displacement-small-x | displacement-small-y | displacement-small-z | extra |
fluid-modulus | fluid-tension | position | position-x | position-y | position-z | pore-pressure | ratio-target | saturation | temperature | velocity | velocity-x | velocity-y |
velocity-z
Assign or initialize values to all gridpoints in the range. One or more keywords can be chosen from the following list:
biot f <[keywordblock]>
Biot modulus for fluid-flow model (see See Biot Coefficient and Biot Modulus). Only available if the model configure fluid has been given.
displacement v <[keywordblock]>
Gridpoint displacement.
displacement-x f <[keywordblock]>
Gridpoint displacement in the x-direction.
displacement-y f <[keywordblock]>
Gridpoint displacement in the y-direction.
displacement-z f <[keywordblock]>
Gridpoint displacement in the z-direction.
displacement-small v <[keywordblock]>
Accumulated small-strain displacement at a gridpoint (used in interface calculations).
displacement-small-x f <[keywordblock]>
Accumulated small-strain x-displacement at a gridpoint (used in interface calculations).
displacement-small-y f <[keywordblock]>
Accumulated small-strain y-displacement at a gridpoint (used in interface calculations).
displacement-small-z f <[keywordblock]>
Accumulated small-strain z-displacement at a gridpoint (used in interface calculations).
extra i a<[keywordblock]>
Extra grid variable for extra array index i and a. [CS: this seems like a pretty thin description; previously was flagged for that reason]
fluid-modulus f <[keywordblock]>
Fluid bulk modulus for fluid-flow model (can only be used for biot c = 1; see the material in Fluid-Mechanical Interaction). Only available if the model
configure fluid has been given.
fluid-tension f <[keywordblock]>
Fluid tension limit for fluid-flow model (tension is negative, value is -1e-15 by default; see the material in Fluid-Mechanical Interaction). Only available if the
model configure fluid has been given.
position v <[keywordblock]>
Position of a gridpoint.
position-x f <[keywordblock]>
X-coordinate of gridpoint
position-y f <[keywordblock]>
Y-coordinate of gridpoint
position-z f <[keywordblock]>
Z-coordinate of gridpoint
pore-pressure f <[keywordblock]>
Pore Pressure at gridpoint. Note that if the pore-pressure is changed this will not affect the total stress, but will change the effective stress. The zone gridpoint
fix pore-pressure command can be used to change the total stress and leave the effective stress constant.
ratio-target f <[keywordblock]>
Specifies the target local force ratio that is considered to be converged for mechanical calculations. The default value is 1e-4. A local force ratio of this value will
result in a convergence value of 1.0 for the gridpoint. See the convergence keyword in the model solve command.
saturation f <[keywordblock]>
Saturation at the gridpoint. Only available if the model configure fluid has been given.
temperature f <[keywordblock]>
temperature at the gridpoint. Only available if the model configure thermal has been given.
Velocity of a gridpoint.
X-velocity of gridpoint
Y-velocity of gridpoint
Z-velocity of gridpoint
Keyword Block
The following keywords may be used to modify a supplied value. If the description of the modifier keyword mentions what type of value it may be applied to (e.g.
scalar value, vector value, etc.), be sure there is a match between the modifier and the main keyword value. The commands main keywords are: biot, displacement,
displacement-small, displacement-small-x, displacement-small-y, displacement-small-z, displacement-x, displacement-y, displacement-z, extra,

fluid-modulus, fluid-tension, pore-pressure, position, position-x, position-y, position-z, ratio-target, saturation, temperature, velocity,
velocity-x, velocity-y and velocity-z.
add
Add the specified value to the existing value.
Apply a gradient to the scalar-value provided.
local
Specify that the value supplied for the keyword is in the local coordinate system of the gridpoint (if any). By default values are initialize in the global system.
This keyword cannot be used with the following keywords of the zone gridpoint initialize command: extra.
multiply
Multiply the existing value by the specified value.
vary v
Apply a linear variation to the scalar-value provided.
zone gridpoint list command

Syntax
zone gridpoint list keyword
Primary keywords:
acceleration | apply | damping | displacement | dynamic | extra | fluid | force | group | information | position | system | temperature | velocity | zone
Display gridpoint information in the console. The following keywords are available to choose which information to list.
acceleration <local>
Gridpoint acceleration. The optional local keyword specifies that acceleration should be reported in local gridpoint coordinates; the default is in model/global
coordinates.
apply <local>
Gridpoint applied forces. The optional local keyword specifies that acceleration should be reported in local gridpoint coordinates; the default is in model/global
coordinates.
damping
Gridpoint damping parameters
displacement <local>
Gridpoint displacements. The optional local keyword specifies that acceleration should be reported in local gridpoint coordinates; the default is in model/global
coordinates.
dynamic
Gridpoint dynamic damping parameters
extra i
Extra gridpoint variable for extra array index i
fluid
Gridpoint information on fluid, including pore-pressure and fluid fixity, as well as saturation, Biot modulus, fluid modulus and fluid tension if model configure
fluid has been specified.
force <local>
Gridpoint unbalanced forces. The optional local keyword specifies that acceleration should be reported in local gridpoint coordinates; the default is in
model/global coordinates.
group <slot s >
Gridpoint group assignments. When the optional slot is supplied, only groups in that slot are listed; otherwise all groups are listed.
information
General gridpoint information: position, mass, fixity, and applied-velocity for each gridpoint. This is the default option if no keyword is given when
zone.gridpoint.list is used.
position
Position coordinates of gridpoint.
system
Gridpoint local coordinate system, if the local coordinate system is specified.
temperature
Gridpoint temperature; only available if model configure thermal has been specified.
velocity <local>
Gridpoint velocities. The optional local keyword specifies that acceleration should be reported in local gridpoint coordinates; the default is in model/global
coordinates.
zone
List of zones connected to gridpoint.
zone gridpoint merge command

Syntax
zone gridpoint merge <keyword> <range>
Primary keywords:
tolerance-relative | tolerance-absolute
Attempts to merge all gridpoints in the range. A gridpoint will be merged if another gridpoint falls within a distance given by the tolerances specified. The following
optional keywords are available to manually specify the tolerances used.
tolerance-relative f
Specifies a relative tolerance value. This is converted to an absolute tolerance by multiplying it to the minimum edge length of all zones connected to the
gridpoint. The default value is 0.01. If both an absolute and a relative tolerance is specified, the value used an any given gridpoint is the maximum of the two.
tolerance-absolute f
Specifies an absolute tolerance value. The default value is 0. If both an absolute and a relative tolerance is specified, the value used an any given gridpoint is the
maximum of the two.
zone gridpoint system command

Syntax
zone gridpoint system keyword
Primary keywords:
global | local
Set the local coordinate system for gridpoints within the range. By default all gridpoints use the global coordinate system. The zone face apply logic may set
gridpoint local systems when necessary to resolve velocity or acceleration conditions.
global
Set gridpoints in the range to use global coordinates.
local keyword ...
Set gridpoints in the range to use the local coordinate system. If only one direction is specified the other two will be determined automatically. If two directions
are specified the second will be adjusted to ensure orthogonality and the third will be determined automatically. If three directions are specified the second and
third will be adjusted to ensure orthogonality.
At least one direction must be specified.
direction-x v
Set the x-direction of the plane that defines the local coordinate system.
direction-y v
Set the y-direction of the plane that defines the local coordinate system.
direction-z v
Set the z-direction of the plane that defines the local coordinate system.
zone group command

Syntax
zone group s <keyword> <range>
Primary keywords:
remove | slot
Add group name s to the zones in the range. Use of the group logic is described in Group. This command may take the form zone group "slotname = groupname" —
quotation marks required, spaces at equals sign ignored — where slotname is the slot assignment and groupname is the group name.
A zone may belong to many groups, up to a maximum of 128. The group range element can be used to select objects by group name. zone list group can be used to
identify existing zone group names.
The following optional keywords are available:
remove
Remove s from the zones. If a slot is not specified, the group name is removed from all slots it is found in.
slot s
Assign the group to the slot named s. The default slot name is Default.
zone hide command

Syntax
zone hide <keyword> <range>
Primary keywords:
b | undo
This commands hides or un-hides all zones in the range. By default, commands that use a range filter will skip hidden objects. This can be overruled with the use-
hidden keyword in the range specification.
If a boolean type is specified, then if on it hides all zones in the range. If off it un-hides (or shows) all zones in the range, and the use-hidden keyword is applied
to the range implicitly. on is the default if no keyword is given.
undo
This will reverse the operation of the last zone hide command. FLAC3D keeps a maximum undo stack of size 12.
zone history command

Syntax
zone history <name s > keyword
Primary keywords:
acceleration | acceleration-x | acceleration-y | acceleration-z | condition | density | displacement | displacement-x | displacement-y | displacement-z | extra | pore-pressure
| property | property-fluid | property-thermal | ratio-local | saturation | strain-increment | strain-rate | stress | stress-strength-ratio | stress-effective | temperature | timestep-
dynamic | unbalanced-force | unbalanced-force-x | unbalanced-force-y | unbalanced-force-z | velocity | velocity-x | velocity-y | velocity-z
Adds a history of a zone value. See the history command. 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.
Zone histories can be taken of any scalar field variable, at any location encompassed by the zone. Once specified, the history location will travel with the zone in large
strain mode.
The location of the history may be specified by location in space, by selecting the centroid of a zone with a specific ID number, or by the location of the gridpoint with a
specific ID number.
If the value is gridpoint-based, then a value is calculated using a weighting function inside the zone.
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 [keywordblock]. By default a value is considered constant within a zone.
Note that to take a history of a specific gridpoint, you take a zone history using the gridpointid as the location, or specify the position of a gridpoint.
This will repeat in at least one other place
acceleration magnitude at the gridpoint(only available in if model configure dynamic has been specified)
x-acceleration at the gridpoint (only available in if model configure dynamic has been specified)
y-acceleration at the gridpoint (only available in if model configure dynamic has been specified)
z-acceleration at the gridpoint (only available in if model configure dynamic has been specified)
a measure of how badly deformed a zone is. [URGENT: CS: content required for link here appears to need adding to doc set: Link to wherever the contents of
section 1.1.5 in the Command Reference end up
The density of the zone.
displacement magnitude at the gridpoint
x-displacement at the gridpoint
y-displacement at the gridpoint
z-displacement at the gridpoint
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 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.
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
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.
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 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.
the saturation at the gridpoint (only available in if model configure fluid has been specified)
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.
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.
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.
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
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
the temperature at the gridpoints. The source modifier keyword can be used to specify that zone based temperature should be used instead.
the local critical dynamic time step of that particular gridpoint. (only available in if model configure dynamic has been specified)
the unbalanced force magnitude at the gridpoint.
x-unbalanced force at the gridpoint.
y-unbalanced force at the gridpoint
z-unbalanced force at the gridpoint
the velocity magnitude at the gridpoint
x-velocity at the gridpoint
y-velocity at the gridpoint
z-velocity at the gridpoint
Keyword Block
The following modifiers are available to specify addition information for the zone history keywords. It is required that the location of the history be specified
using one of the keywords position, zoneid, or gridpointid. The following keywords are available. acceleration, acceleration-x, acceleration-y,
acceleration-z, condition, density, displacement, displacement-x, displacement-y, displacement-z, extra, pore-pressure, property, property-
fluid, property-thermal, ratio-local, saturation, strain-increment, strain-rate, stress, stress-effective, stress-strength-ratio,
temperature, timestep-dynamic, unbalanced-force, unbalanced-force-x, unbalanced-force-y, unbalanced-force-z, velocity, velocity-x,
velocity-y and velocity-z.
component keyword
x-component of the vector
y-component of the vector
z-component of the vector
magnitude
vector magnitude
index i
gravity b
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
method
constant
average
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
power f
Specifies the power of the distance used to weight values. The default power is 3.0.
radius-ratio f
Specifies the ratio of the maximum distance from the point of the zones selected, to the ratio used to calculate weighted values. Zones farther
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
name s
Certain keywords (most notably property) require a name value to be fully specified. This will determine the specific property name retrieved.
null
Specifies the criteria used to ignore zone values. By default mechanical null zones are ignored.
fluid b
mechanical b
thermal b
position v
Specifies the location of the history at v. This location must be inside a zone.
quantity keyword
intermediate
intermediate principal stress
maximum
the maximum (most positive) value of principal stress. Note that in FLAC3D 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 FLAC3D 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
gridpoint.
gridpoint
zone
stress b
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
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.
zone import command

Syntax
zone import s <s2 >keyword
Primary keywords:
use-given-ids | format
Import a grid from a file. The file named s is imported. A path can be part of the file name. If no extension is specified, .f3grid is assumed.
Currently, three formats are support: FLAC3D native ( *.f3grid ), ANSYS ( *.lis ), and ABAQUS ( *.inp ). The format will be automatically determined by the filename
extension, but can be overridden wih the format keyword.
The command creates a new grid point for every gridpoint specified in the input file. Checking for duplicate gridpoints is not done. It is up to the user to merge
imported grids with existing geometry. Warning messages are output if zones are degenerate or cannot support two overlays.
use-given-ids
Forces FLAC3D to use the same gridpoint and zone IDs as are specified in the import file.
format keyword
Specified the expected format of the input file, overriding any default decision made by checking the file extension. The following format types are available:
flac3d
This specifies the native FLAC3D ASCII- or binary-format grid file, with an expected extension of f3grid. The binary-format grid file is usually with
smaller size and imported quicker than the ASCII-format grid file. The details of ASCII-format of FLAC3D grid file is given below.
ansys
This specifies an ANSYS compatible mesh file, with a normally expected extension of lis. Note that the ANSYS format enabled here generally
requires two different files, both with the same extension. The first file is assumed to contain the gridpoint information, and the second the zone
information. Use "nlist" command in ANSYS to output nodes (gridpoints) to a file; and use "elist" comamnd in ANSYS to output elements (zones)
into another file. Any ANSYS element with more than 8 nodes is not supported.
abaqus
This specifies an ABAQUS compatible mesh file, with an normally expected extension of inp. Acceptable ABAQUS elements are "c3d4", "c3d5",
"c3d6", and "c3d8". Other ABAQUS elements are not supported.
FLAC3D grid format specification
A FLAC3D ASCII-format grid file is with the following specifications: comment lines start with an asterisk; blank lines are ignored; and comma separators
between numeric values are optional.
A line starting with “G” indicates a gridpoint definition. A gridpoint contains an integer identifier (ID number) followed by the x, y, z coordinates of the gridpoint
(floating point numbers).
A line starting with “Z” indicates a zone definition. A zone contains a zone type identifier, an integer zone identifier and the identifiers of the gridpoints
comprising this zone.
The ID numbers for the gridpoints and zones must be positive integers. The ID numbers do not have to be sequential or consecutive (gaps are allowed in the
numbering); however, every gridpoint ID referred to by a zone must exist in the gridpoint list somewhere. If the use-given-ids keyword is given, the ID numbers
of gridpoints and zones specified in the *.f3grid file are used in the final grid. Otherwise, gridpoints and zones are generated using the next available ID numbers
(the default). Also, the use-given-ids keyword allows grids to be imported in a piecemeal fashion. For example, if you have the following grid files:
g1.f3grid – gridpoint definitions
g2.f3grid – more gridpoint definitions
g3.f3grid – more gridpoint definitions
z13.f3grid – zone definitions using gridpoint IDs from g1 and g3
z12.f3grid – zone definitions using gridpoint IDs from g1 and g2
groups.f3grid – groups into which zones fall
they can be imported as follows:
zone import 'g1.f3grid' use-given-ids
zone import 'z13.f3grid' use-given-ids
zone import 'z12.f3grid' use-given-ids
zone import 'groups.f3grid' use-given-ids
For this to work, the only requirement is that gridpoints must exist prior to creating the zones that require them. Also, zones must exist prior to placing them in
groups.
The following zone type identifiers are recognized:
B8 – brick type zone
W6 – wedge type zone
P5 – pyramid type zone
B7 – degenerate brick type zone
T4 – tetrahedral type zone
For the zone definition, the gridpoint ID numbers must be specified in the standard FLAC3D ordering (see Orientation of Nodes and Faces within a Zone). The
redundant points for wedge, pyramid, degenerate brick and tetrahedral zones are not specified in the grid file. For a B8 zone, 8 gridpoints must be specified, for a
W6 zone, 6 gridpoints must be specified, etc.
A line starting with “ZGROUP” indicates a group definition for zones. The text immediately following the word ZGROUP is the name of the group. Following
the group name, all zones belonging to this group are specified with zone ID numbers. A line starting with “F” indicates a face definition. A face line contains a
type identifier (a unique identifier for the face) and a set of gridpoint IDs that form a face in a zone. Type face identifiers are defined as “T3” for tetrahedral zone
faces and “Q4” for quadrilateral zone faces.
A line starting with “FGROUP” indicates a group of faces. Face groups are used in the range logic, allowing the user to apply properties, boundary conditions,
velocities, etc. to a set of faces. The face group line contains the face group name. Lines containing the identifiers of the previously defined faces will follow the
FGROUP line. The face identifiers are separated by spaces. This will assign the group name to all faces in the line when the grid is created.
The code block below shows a portion of a FLAC3D grid file:
*FLAC3D input deck produced by KUBRIX version 7.1.0

*mesh built: Wed Nov 19 20:54:43 2003
*GRIDPOINTS
G 1, -6.133336e+000, -6.144340e+000, -3.999275e+001
G 2, -4.732805e+000, -7.033142e+000, -3.999276e+001
G 3, -2.777756e+000, -4.116792e+000, -3.999988e+001
G 4, -3.535428e+000, -3.535424e+000, -3.999989e+001
G 457, -2.745877e+000, -4.129570e+000, -3.201193e+001
.
.
.
G 6, -3.512750e+000, -3.501916e+000, -3.200895e+001
G 17, -8.901190e+000, -8.922812e+000, -3.999268e+001
G 8, -6.845476e+000, -1.015358e+001, -3.999268e+001
*ZONES
Z B8 1, 1, 2, 4, 1443, 3, 6, 1444, 5
Z B8 2, 7, 8, 1, 1445, 2, 1443, 1446, 1444

Z B8 3, 9, 10, 7, 1447, 8, 1445, 1448, 1446
Z B8 4, 11, 12, 9, 1449, 10, 1447, 1450, 1448
.
.
.
Z B8 2785, 13, 14, 11, 1451, 12, 1449, 1452, 1450
Z B8 62, 15, 16, 13, 1453, 14, 1451, 1454, 1452
Z B8 78, 17, 18, 15, 1455, 16, 1453, 1456, 1454
*GROUPS
ZGROUP ’granite type 1’
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
ZGROUP ’ore zone’
1601 1602 1603 1604 1605 1606 1607 1608
zone initialize command

Syntax
zone initialize keyword <range>
Primary keywords:
density | extra | fluid-density | state | stress | stress-principal | stress-xx | stress-xy | stress-xz | stress-yy | stress-yz | stress-zz
Initialize a variable on all zones in the range.
Note that among the keywords, there is similarity between the stress xx construction of the command and the stress-xx construction. The difference is that the former
will allow multiple components to be specified at once (e.g., zone initialize stress xx 1 yy 2.4 zz 4.7) but cannot take a value modifier (that is, vary, multiply, etc.). Also
be aware that when this command form is used, the entire stress tensor is initialized — any components not specified explicitly are assumed to be zero. The latter
construction allows modifiers (e.g., zone.initialize.stress-yy 2.2 add 3) but each component must be separately specified.
Note that in FLAC3D, compressive stresses are negative.
density f [keywordblock]
mass density of zone
extra i a[keywordblock]
extra variable for array index i
fluid-density f [keywordblock]
fluid mass density in zone (only available if model configure fluid has been specified)
state i [keywordblock]
The plasticity indicators for tetrahedrons are set to i . Normally the value of i used is 0 in order to reset the failure indicators.
stress <keyword ...>
Full stress state, specified by component. A component that is not specified is assumed to be zero.
xx f
xx-component of stress
xy f
xy-component of stress
xz f
xz-component of stress
yy f
yy-component of stress
yz f
yz-component of stress
zz f
zz-component of stress
stress-principal <keyword ...>
Principal stress states, specified by value and by direction using the available keywords. Note that at least two directions must be specified, and magnitudes not
specified are assumed to be zero. Note that the [keywordblock] is available after each of the following keywords, allowing them to be varied in space
independently.
direction-intermediate v [keywordblock]
Direction of intermediate principal stress.
direction-maximum v [keywordblock]
Direction of maximum principal stress.
direction-minimum v [keywordblock]
Direction of minimum principal stress.
intermediate f [keywordblock]
Intermediate principal stress magnitude.
maximum f [keywordblock]
Maximum (most postitive) principal stress.
minimum f [keywordblock]
Minimum (most negative) principal stress.
stress-xx f [keywordblock]
xx-component of stress (See the description above for the difference between zone initialize stress-xx and zone initialize stress xx and for the next
five keywords).
stress-xy f [keywordblock]
xy-component of stress
stress-xz f [keywordblock]
xz-component of stress
stress-yy f [keywordblock]
yy-component of stress
stress-yz f [keywordblock]
yz-component of stress
stress-zz f [keywordblock]
zz-component of stress
Keyword Block
The following keywords may be used to modify a supplied value. If the description of the modifier keyword mentions what type of value it may be applied to
(e.g. scalar value, vector value, etc.), be sure there is a match between the modifier and the main keyword value. The commands main keywords are: density,
extra, fluid-density, state, stress-xx, stress-xy, stress-xz, stress-yy, stress-yz and stress-zz. direction-intermediate, direction-maximum,
direction-minimum, intermediate, maximum and minimum.
add
multiply
vary v
zone initialize-stresses command

Syntax
zone initialize-stresses keyword <range>
Primary keywords:
direction-x | overburden | total | ratio
Initialize zone stresses based on the density of the zones above them and gravity.
For all zones in the range, the total column of zone densities above them (opposite the direction of gravity) is accumulated into a stress. The ratio keyword is used to
determine both horizontal stresses, and defaults to 1.0. This zone stress state is then initialized to this value.
Note that this works even if gravity is not vertical - in which case the vertical and horizontal stresses are the principal components aligned with gravity and
perpendicular to gravity, respectively.
Note that in FLAC3D, compressive stresses are negative.
Note
On rare occasions zone can be distorted enough to cause its centroid to lie outside of the actual zone volume, at least using the assumptions this
algorithm makes about non-planar faces. If that zone is also on the model surface, then zone centroid can actually be outside of the model.
In this case the initial zone stress will be incorrect.
direction-x v
If two paramters are given for the ratio keyword, then this keyword can be used to specify the local -direction the system should use. The -direction is
determined automatically using the -dirction and the direction of gravity to create an orthonormal system. The -direction may be adjusted to make it normal to
the direction of gravity. By default the -direction is (1,0,0).
overburden f
Specifies an overburden stress added to the calculation, assuming the vertical boundary of the model does not represent the surface. This value defaults to 0.0.
Remember that compressive stresses are negative, so this value will typically be negative.
total
By default the vertical to horizontal stress ratio is applied to effective stress. Use this keyword to make it apply to total stress. This has no effect unless a non-zero
pore-pressure field has been created.
ratio f <:flt:'fy'>
Determines the vertical to horizontal stress ratio. Both horizontal stresses are set to the vertical stresses times this value. If the optional second parameter fy is
given, then a different ratio is used in the local x and y directions. Note that the direction-x keyword is used in this case to distinguish these local directions.
zone interface tolerance-contact command

Syntax
zone interface s tolerance-contact f keyword <range>
Primary keywords:
add | gradient | multiply | vary
Sets the maximum depth of penetration (of faces that contact an interface) for which a contact is detected. If this depth (or overlap) is greater than value, then no contact
is detected. By default, the value is determined from zone dimensions and is updated if deformation occurs during a simulation.
The parameter may be used to force contact detection if a large initial overlap exists between two bodies. Use with caution, because large geometrical overlaps maybe
physically unrealistic. The current values of contact-tolerance can be displayed with zone.interface s list information.
add
multiply
vary v
zone interface create command

Syntax
zone interface s create keyword
Primary keywords:
by-face | element | node
Create nodes or elements on interface s.
There are two techniques for creating an interface. The first is to derive an interface or interfaces from a range of zone faces using the by-face keyword. The second is to
specify a triangular interface element from three points. Lastly, this command may also be used to construct an interface node that may, in turn, be used with the
element keyword.
by-face <separate keyword> <range>
Interface elements are created on all surface zone faces that are within the specified range. An error will occur if interface elements from that interface already
exist on the selected faces.
If the optional separate keyword is used, then internal zone faces are selected by the range. The list of selected faces is then automatically separated (as with zone
separate) and interface elements placed on one side. The following keywords are available follwing the separate keyword:
new-side-origin v
Specifies which side of the separate faces the interfaces are place on. It chooses the side with face normal vectors pointing toward v.
clear-attach
If specified, causes any attach conditions on the boundary to be cleared. By default an existing attach condition causes an error.
element point i keyword ...
Create a triangular interface element by specifying three points. Three vertices point 1, point 2 ,and point 3 must be specified following the element keyword.
Each point can be created and located in space using the position keyword, or an existing interface node with ID i may be specified. The interface element that is
created is not attached to a grid face even if the location corresponds to that of the face. The element is fixed in space. The active side of the element is defined by
walking around the edge of the element, from point 1 to point 2 to point 3; the active side is up when walking in a clockwise direction.
For each point of the element, one of the following two keywords must be supplied.
node i
Identify the point with a previously created interface node with ID i.
position v
Identify the point with a new interface node created at position v.
node v
This creates an interface node at position v. If a node already exists at the selected location, an error is reported. The created node is fixed in space.
zone interface effective command

Syntax
zone interface s effective b
The effective stress will be used in the interface calculation if on. By default, effective stress is used (effective is on).
zone interface element command

Syntax
zone interface s element keyword <range>
Primary keywords:
delete | extra | list | maximum-edge
Manage zone interface elements.
delete
All interface elements associated with this interface within the selected range are deleted.
sets the extra interface element variable value for array index i. The standard [keywordblock] list is available to modify this value in space.
list keyword
extra i
Lists the values of the interface element extra variable for array index i.
information
Nodes, area and normal vector of all elements in the range are displayed.
maximum-edge f
f is the maximum edge length for interface elements in the range. The interface is subdivided until all of theseelements have an edge length smaller than the
assigned value. By default, two triangular elements are created for each quadrilateral zone face.
Keyword Block
(e.g. scalar value, vector value, etc.), be sure there is a match between the modifier and the main keyword value. The commands main keywords are: extra.
add
multiply
vary v
zone interface list command

Syntax
zone interface s list information
Show summary data on interfaces.
zone interface node command

Syntax
zone interface s node keyword <range>
Primary keywords:
displacement-shear | displacement-small | extra | history | id | position | id | position | id | position | id | position | initialize-stresses | list | stress-shear | stress-normal-
increment | property | update
Configure interface nodes.
displacement-shear v
Overwrites the shear displacement vector for all interface nodes in the range. The value will be constrained to be perpendicular to the interface normal direction.
displacement-small f
Interfaces operating in small-strain mode derive their forces from a comparison of “virtual positions” of the two interacting faces, where a “virtual position” of a
point is the original coordinate of the point plus the accumulated displacement ( displacement-small ) to date. If one contacting object is removed (e.g., backfill
within a tunnel), and another substituted (e.g., a liner is installed) using the same interface, then large initial stresses may appear because the two sides of the
interface appear to interpenetrate (because the virtual position of the old object has changed with respect to the specified position of the new object).
The stored displacements associated with a particular interface s may be multiplied by a factor f, using the keyword displacement-small. Normally, this factor will
be zero, thus restoring the virtual positions of the faces comprising the interface “host” to their original locations. In this case, a new interacting object will not
cause initial stresses to be generated when its coordinates match the original coordinates of the interface host faces. However, it is possible to give f a nonzero
value, in order to simulate an initial lack-of-fit between the two contacting objects.
The command changes the virtual positions in the interface, and in the two faces that are in contact. However, for a newly created interface, the “target” face is
not found until cycling has begun. Therefore, for all positions to be reset, at least one cycle should be executed before giving the command if the target (i.e., the
face without the interface elements) has some existing deformation.
Set the extra interface node variable value for array index i.
history <name sn >keyword
Interface variables can be sampled for interface s at the interface node specified. See the history command. Note that this command does not take a following
range. The following keywords are defined:
displacement-normal keyword
normal displacement (positive values indicate increased penetration).
id i
Indicates the history should be taken at interface node ID i in interface s.
position v
Indicates the history should be taken at the node closest to position v among the nodes of interface s.
displacement-shear keyword
shear displacement magnitude
id i
position v
stress-normal keywrd
normal stress (Compressive stresses are positive)
id i
position v
stress-shear keyword
shear stress magnitude
id i
position v
initialize-stresses
Initializes the normal and shear forces on all interface nodes in the range and in contact with a surface face. The values of the forces are determined by the
tractions on the host face of the node. This means that if zone stresses are initialized, then interface forces can be initialized to be approximately compatible, thus
reducing the amount of cycling to reach initial equilibrium.
Note that since normal stress is determined by absolute penetration, initialization of normal stresses is accomplished by setting the stress-normal-increment value
for each node affected.
list keyword
List information about interface nodes in the range.
displacement
The accumulated displacement, shear displacement, and small-strain displacement of the nodes.
extra i
The values stored in extra index i of the interface nodes.
host
The host zone face, and the weighting values used for the attachment.
information
The position, normal direction, and effective area, and contact tolerance.
property keyword
The value of interface properties at the nodes. The available property names are:
bonded-slip
flag indicating if slip is allowed.
cohesion
cohesion in units of stress
cohesion-residual
residual cohesion. If assigned a value greater than or equal to zero, this value is assigned to cohesion after frictional shear failure.
dilation
dilation in degrees
friction
friction in degrees
friction-residual
residual friction. If assigned a value greater than or equal to zero, this value is assigned to friction after frictional shear failure.
shear-bond-ratio
shear bond strength as a ratio of the tensile strength.
stiffness-normal
normal stiffness in units of stress over displacement.
stiffness-shear
shear stiffness in units of stress over displacement.
tension
tensile strength in units of stress
tension-residual
residual tensile strength. If assigned a value greater than or equal to zero, this value is assigned to tension after frictional shear failure.
state
current state of the interface node
stress
shear and normal stresses and shear stress direction
target
target face information including penetration
velocity
velocity at nodes
stress-shear v [keywordblock]
sets the incremental shear stress v for all interface nodes in the range.
stress-normal-increment f [keywordblock]
Sets the normal stress increment to f for all interface nodes in the range. Note that compressive stresses are positive. The normal stress increment is added to the
normal stress calculated from interface penetration.
property keyword ...
Assigns one or more new property values to all interface nodes in the range.
cohesion f [keywordblock]
cohesion [stress]
friction f [keywordblock]
friction angle [degrees]
stiffness-normal f [keywordblock]
normal stiffness [stress/displacement]
stiffness-shear f [keywordblock]
shear stiffness [stress/displacement]
cohesion-residual f [keywordblock]
residual cohesion [stress]. If a value greater than of equal to zero is specified, this value is assigned to cohesion after frictional shear failure. Default is -1.0.
friction-residual f [keywordblock]
residual friction angle [degrees]. If a value greater than of equal to zero is specified, this value is assigned to friction after frictional shear failure. Default is
-1.0.
tension-residual f [keywordblock]
residual tensile strength [stress]. If a value greater than of equal to zero is specified, this value is assigned to tension after frictional shear failure. Default is
-1.0.
tension f [keywordblock]
tensile strength [stress]
bonded-slip b
Slip is allowed, or not allowed, for a bonded interface segment. Default is off (i.e., slip is not allowed if bond is intact). This is only applicable if a bonded
interface is specified (tension is set).
shear-bond-ratio f [keywordblock]
The shear bond strength is set to sbr times the normal bond strength (tension). Note that giving sbratio alone does not cause a bond to be established; the
tensile bond strength must also be set. The default value for sbratio is 100 (i.e., shear bond is 100 times tensile bond). This is only applicable if a bonded
interface is specified (tension is set).
update b <range>
This command prevents the search for new contacts after movement occurs on an interface. The same contacts are preserved, whatever the magnitude of
displacement. Use with caution, because physically unrealistic behavior can result if displacements are large. The default behavior is on, which allows normal
searching for new and broken contacts.
Keyword Block
(e.g. scalar value, vector value, etc.), be sure there is a match between the modifier and the main keyword value. The commands main keywords are: extra,
stress-normal-increment and stress-shear. cohesion, cohesion-residual, friction, friction-residual, shear-bond-ratio, stiffness-normal,
stiffness-shear, tension and tension-residual.
add
multiply
vary v
zone interface permeability command

Syntax
zone interface s permeability b
Interfaces are permeable by default. An interface can be made impermeable by setting permeability off. If zone interface element maximum-edge is used, the
interface becomes impermeable and cannot be made permeable.
zone list command

Syntax
zone list <keyword> <range>
Primary keywords:
density | extra | fluid-density | gridpoint | group | hysteretic | information | join | mechanical | pore-pressure | principal | profile | property | state | strain | strain-increment |
strain-rate | stress | stress-effective | summary | tetrahedra
List zone data. If no keyword is given, the default output of the command is that associated with the information keyword.
density
Zone mass density.
extra i
Extra zone variable for extra array index i.
fluid-density
Zone fluid density (only available if model configure fluid has been specified).
gridpoint
ID number of gridpoint associated with zones.
group <slot s >
Zone group assignments. Only groups in slot s will be shown if the slot keyword is used.
hysteretic
Lists the hysteretic damping assignments, and parameter values, for each zone (only available if model configure dynamic has been specified; see Hysteretic
Damping for details).
information
general zone information: the zone type (brick, wedge, etc), the constitutive model assigned, density, volume, and centroid.
join
Zone face (join) connections
mechanical
General information about zone mechanical calculations. Large strain setting, nodal mixed discretization setting, damping settings, location of maximum local
force ratio, and others.
pore-pressure
Zone pore pressure (average from gridpoint values)
principal <keyword>
Principal stress components for zones. The default output is total.
effective
Effective principal stress.
total
Total principal stress.
profile keyword
List the values of a zone field variable on points spaced equally over a line.
The available zone field variables are summarized here:
acceleration magnitude at the gridpoint(only available in if model configure dynamic has been specified)
x-acceleration at the gridpoint (only available in if model configure dynamic has been specified)
y-acceleration at the gridpoint (only available in if model configure dynamic has been specified)
z-acceleration at the gridpoint (only available in if model configure dynamic has been specified)
a measure of how badly deformed a zone is (see Condition Measure of Zones).
The density of the zone.
displacement magnitude at the gridpoint
x-displacement at the gridpoint
y-displacement at the gridpoint
z-displacement at the gridpoint
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 in zone. By default this will be the grid point pore pressure, but the zone average pressure can be specified by using the source keyword
modifier.
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
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
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
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.
the saturation at the gridpoint (only available in if model configure fluid has been specified)
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.
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.
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.
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
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
the temperature at the gridpoints. The source modifier keyword can be used to specify that zone based temperature should be used instead.
the local critical dynamic time step of that particular gridpoint. (only available in if model configure dynamic has been specified)
the unbalanced force magnitude at the gridpoint.
x-unbalanced force at the gridpoint.
y-unbalanced force at the gridpoint
z-unbalanced force at the gridpoint
the velocity magnitude at the gridpoint
x-velocity at the gridpoint
y-velocity at the gridpoint
z-velocity at the gridpoint
property s
Material properties assigned to zones. Values are displayed for the property named s. Property names for each constitutive model are listed with the model
definitions (see the model defintions in the Constitutive Models section).
state <keyword>
Plasticity state indicators. The default keyword is any.
any
Lists the union of all plasticity state flags in any tetrahedral subzone (default).
average
Prints plasticity state if more than 50% of tetrahedral subzones are at this state.
strain
lists shear strain rate, shear strain incrmement, volumetric strain rate and volumetric strain increment. Strain rates are basec on the current velocity field, and
strain increments are based on the current displacement field.
strain-increment
the strain increment tensor, based on the current displacement field.
strain-rate
the strain rate tensor, based on the current velocity field.
stress
components of total stress for zones.
stress-effective
components of effective stress for zones.
summary
summary of zone module status.
tetrahedra
List values at each tetrahedral subzone of the zone.
gridpoint
The four gridpoints associated with each subzone.
information
The volume and centroid location of each subzone.
principal
The current principal stresses of each subzone, including directions.
principal-effective
The current principal effective stresses of each subzone, including directions.
stress
The current stress tensor in each subzone.
stress-effective
The current effective stress tensor in each subzone.
Keyword Block
The following modifiers are available to specify addition information for the zone list profile keywords. It is required that the location of the profile be
specified using the keywords begin, end, and segments. The following keywords are available. acceleration, acceleration-x, acceleration-y,
acceleration-z, condition, density, displacement, displacement-x, displacement-y, displacement-z, extra, pore-pressure, property, property-
fluid, property-thermal, ratio-local, saturation, strain-increment, strain-rate, stress, stress-effective, stress-strength-ratio,
temperature, timestep-dynamic, unbalanced-force, unbalanced-force-x, unbalanced-force-y, unbalanced-force-z, velocity, velocity-x,
velocity-y and velocity-z.
begin v
Specifies the beginning point of the profile line.
component keyword
x-component of the vector
y-component of the vector
z-component of the vector
magnitude
vector magnitude
end v
Specifies the ending point of the profile line.
index i
gravity b
gridpointid i
Specifies the location of the history by the location of the gridpoint with ID number i.
log b
method
constant
average
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
power f
Specifies the power of the distance used to weight values. The default power is 3.0.
radius-ratio f
Specifies the ratio of the maximum distance from the point of the zones selected, to the ratio used to calculate weighted values. Zones farther
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
name s
Certain kewords (most notably property) require a name value to be fully specified. This will determine the specific property name retrieved.
null
Specifies the criteria used to ignore zone values. By default mechanical null zones are ignored.
fluid b
mechanical b
thermal b
position v
Specifies the location of the history at v. This location must be inside a zone.
quantity keyword
intermediate
intermediate principal stress
maximum
the maximum (most positive) value of principal stress. Note that in FLAC3D 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 FLAC3D 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
segments i
Specifies the number of points to distribute evenly along the profile line from begin to end.
source keyword
gridpoint.
gridpoint
zone
stress b
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
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.
zone mechanical command

Syntax
zone mechanical keyword
Primary keywords:
active | damping | energy
Sets parameters for a static mechanical analysis, that are specific to zones. The following keywords apply:
active b
Sets mechanical calculation off/on (default is on). The mechanical calculation may be turned off for a thermal-only calculation or a fluid flow-only calculation.
Note that in general it is preferable to set mechanical calculations off for the entire model with the model mechanical active command.
damping keyword <range>
Select the damping type for the static, mechanical process (the default damping is local).
combined <f >
combined local damping (default is 0.8).
local <f ><alternate>
local damping (default is 0.8). If the alternate keyword is specified, an experimental alternate implementation of local damping is used that produces less
sensitivity to small changes in the model.
energy keyword
allows elastic strain energy and dissipated plastic energy to be calculated (see Energy Calculation in FLAC3D).
active b
Turns the calculations off/on in the stress-strain loop
clear <range>
will set the four zone energy values in every zone back to zero. The zone mechanical active command does not clear these values. This allows you to
stop accumulating plastic work over any interval you wish, and resume accumulating at any time from where it left off.
zone nodal-mixed-discretization command

Syntax
zone nodal-mixed-discretization b
Activate or deactivate the nodal mixed discretization (nmd) feature. When nmd is on, any tetrahedral zones will use the nmd algorithm during the stress calculations.
When nmd is off, the default mixed discretization method will be used. See Nodal Formulation of the Equations of Motion for further information.
zone property command

Syntax
zone property s a... <range>
Make a constitutive model(s) property assignment. The name of the property is s and the value being assigned to it is a. The assignment will affect any zone whose
constitutive model includes the property named (noting that some properties, such as bulk, for instance, appear in many consitutive models). Limiting a property
assignment to zones that have a particular constitutive model assignment is done using the range component of the command. For instance, in the following:
zone property bulk 3000 range cmodel mohr
the range component limits the bulk property specification to zones with a Mohr-Coulomb (mohr) constitutive model assignment.
All constitutive models have properties associated with them.
There are 19 basic mechanical constitutive models in FLAC3D (not including null, which does not appear below) and 11 option-specific mechanical models. All are
classified as follows: elastic, elastic-plastic, dynamic, creep, thermal.
Elastic Mechanical Models
anisotropic
The anisotropic (transversely-elastic) model: properties, description.
elastic
The isotropic elastic model: properties, description.
othortropic
The orthotropic elastic model: properties, description.
Elastic-Plastic Mechanical Models
cap-yield
The cap-yield (CYSoil) model: properties, description.
double-yield
The double-yield model: properties, description.
drucker-prager
The Drucker-Prager model: properties, description.
hoek-brown
The Hoek-Brown model: properties, description.
hoek-brown-pac
The Hoek-Brown-PAC model: properties, description.
modified-cam-clay
The modified Cam-Clay model: properties, description.
mohr-coulomb
The Morh-Coulomb model: properties, description.
mohr-coulomb-tension
The Mohr-Coulomb tension (MorhT) model: properties, description.
plastic-hardening
The plastic hardening model: properties, description.
cap-yield-simplified
The simplified Cap-Yield (CHSoil) model: properties, description.
softening-ubiquitous
The bilinear strain-softening/hardening ubiquitous-joint model: properties, description.
strain-softening
The strain-softening/hardening Mohr-Coulomb model: properties, description.
swell
The swell model: properties, description.
ubiquitous-joint
The ubiquitous-joint model: properties, description.
ubiquitous-anisotropic
The anisotropic-elasticity ubiquitous-joint model: properties, description.
Dynamic Option Model
finn
The Finn model: properties, description.
Creep Option Models
burgers
The Burgers model: properties, description.
burgers-mohr
The Burgers-Mohr model: properties, description.
maxwell
The Maxwell (classic viscoplastic) model: properties, description.
power
The power model: properties, description.
power-mohr
The power-Mohr model: properties, description.
power-ubiquitous
The power-ubiquitous model: properties, description.
wipp
The WIPP model: properties, description.
wipp-drucker
The WIPP-Drucker model: properties, description.
wipp-salt
The WIPP-salt model: properties, description.
Thermal Option Model
hydration-drucker-prager
The Hydration-Drucker-Prager model: properties, description.
zone property-distribution command

Syntax
zone property-distribution s fvalue keyword <range>
Primary keywords:
deviation-gaussian | deviation-uniform | gradient | add | multiply | vary
Modify a zone constitutive model property. The property name is denoted by s, the value being assigned is denoted by fvalue. The property should accept a value of
type float. While technically any valid type can be used here, none of the distribution keywords will apply and the zone property command should probably be used
instead.
The phrase that modifies the value must be given immediately following the property value. For more information on modifying values and the operation of these
keywords, see the valuemodulation topic.
A Gaussian distribution is used to assign the property values randomly, with a mean of fvalue and standard deviation of f .
deviation-uniform f
A uniform distribution is used to assign the property values randomly, with a mean value of fvalue and a standard deviation of f.
Apply a gradient to the property value.
add
Add fvalue to the property value.
multiply
Multiply the property value by fvalue.
vary v
Apply a linear variation to the property value.
zone ratio command

Syntax
zone ratio keyword
Primary keywords:
average | local | maximum
The ratio limit for mechanical, thermal and fluid-flow calculations using the model solve can be calculated in three ways, as defined by the following keywords:
average
The ratio is defined to be the average unbalanced mechanical force (or heat-flux or fluid-flow) magnitude for all the gridpoints in the model divided by the
average applied mechanical force (or heat flux or fluid flow) magnitude for all the gridpoints (default).
local
The ratio is defined to be the maximum value of the ratio of the unbalanced mechanical force (or heat-flux or fluid-flow) magnitude to the applied mechanical
force (or heat-flux or fluid-flow) magnitude for all the gridpoints in the model.
maximum
The ratio is defined to be the maximum unbalanced mechanical force (or heat-flux or fluid-flow) magnitude for all the gridpoints in the model divided by the
average applied mechanical force (or heat flux or fluid flow) magnitude for all the gridpoints.
In increasing order of stringency, the conditions are:
average
ensures a majority of zones are in equilibrium.
maximum
ensures that all unbalanced forces are below a certain value, compared to average forces for the whole model.
local
ensures that each local unbalanced force is less than some fraction of the local forces, averaged for each gridpoint. This criterion can be misleading if some zones
have very small stresses, because even a large ratio for one gridpoint may not be very important, given that the associated zone contributes almost nothing to the
overall response.
zone reflect command

Syntax
zone reflect keyword <range>
Primary keywords:
dip-direction | dip | normal | origin | merge
All zones within the given range are reflected across the plane. Note that group information is copied from the original to the new zones.
The following keywords are available to control how this reflection is accomplished.
dip-direction f
This specifies the dip direction f [degrees] of the plane measured in the global xy-plane clockwise from the positive y-axis. (The default is f = 0.)
dip f
This specifies the dip angle f [degrees] of the plane, measured in the negative z-direction from the global xy-plane. (The default is f = 0.)
normal v
This specifies a normal vector to the plane, with the components specified as v. If normal is specified, dip and dip-direction are not required.
origin v
This specifies the location of one point through which the plane crosses. The coordinates of the point are v.
merge b
If b is off, then boundary gridpoints of the newly created zones are not automatically merged with previous existing gridpoints. By default merge is on.
zone relax command

Syntax
zone relax keyword
Primary keywords:
delete | excavate | list | modify
Creates and modifies a special apply condition on the zones in the range. This condition gradually 'excavates' the material by reducing the stiffness, stresses, and
densities of the zones. This keeps spurious inertial effects in the static solution process from causing unrealistic damage to the region around the excavation.
The values of these quantities are systematically reduced by applying a multiplier (the reduction factor) that varies from 1.0 to 0.0 over time. The precise time taken and
shape of the curve is controllable by the user, but defaults to a servo controlled by the current mechanical force ratio (see zone ratio ).
When the reduction factor for a given zone is brought to zero, the mechanical constitutive model for the zone is set to null and the apply condition for that zone is
removed. When all the zones involved in a given condition are nulled, the apply condition itself is destroyed.
The constitutive model of all zones included are set to elastic, preserving the bulk and shear modulus of the original model.
Since the density and stiffness of the material is reduced over time, in small strain mode a periodic recalculation of some parameters (body force due to gravity, inertial
mass) will take place. This will happen when the reduction factor changes, but no more frequently than the current zone geometry-update setting.
Note that while the total stress is reduced to zero, any pore-pressures in the gridpoints attached to the zones will remain unaffected.
delete s
Finds a previously created zone relax apply condition with name s, and deletes it.
excavate keyword <range>
Creates and initializes an excavation condition on all zones in the range. The following keywords are available to customize how the excavation progresses.
fish s
Specify a FISH function that determines the multiplier to use as the excavation progresses. This should return a value of 1.0 at the start, and 0.0 and the
end. If this keyword is used, the default servo is not used.
fish-local s
Specify a FISH function that determines the multiplier to use as the excavation progresses. This function is called separately for each individual zone taking
part in the apply condition. If this keyword is used, the default servo is not used.
The function is assumed to take two arguments. The first argument is a pointer to the zone in question. The second argument is unused.
minimum f
Sets the minimum reduction factor that will be allowed. The default value is 0.0. This should be a number between 0.0 and 1.0. This value can be used to
solve to a specific reduction factor before installing reinforcement or other operation. Then the zone relax modify command can be used to lower the
minimum.
Note changing the minimum when using the table, fish, or fish-local options to control the reduction factor may result in unexpected behavior,
as the time index used for those options will not stop advancing after reaching the minimum value.
name s
Assigns the apply condition an identifying name s. If a name is not specified one will be created automatically based on the internally assigned ID number.
servo-bound f
If the current mechanical force ratio (see the zone ratio) is lower than this value, the reduction factor is reduced by the increment. The default value is 1e-
3
servo-increment f
If the current mechanical force ratio is less than servo-bound, then the reduction factor is reduced by subtracting f from it. This number should be less than
1.0, and greater than 0.0. The default value is 0.005.
step i
If set to a positive value, then any FISH, table, or servo parameters are ignored and the reduction factor is reduced linearly from 1.0 to 0.0 over the course
of i steps.
If specified, then the reduction factor is given by table s. A lookup is performed every step. By default the x value used to lookup a table y value will be the
accumulated mechanical time, which for a purely static analysis is the same as the number of steps. The time index used can be changed by using the
optional time keyword, with the following options.
step
Use the total cycle count.
mechanical
Use the accumulated mechanical time (the default)
fluid
Use the accumulated fluid flow time.
thermal
Use the accumulated thermal time.
creep
Use the accumulated creep time.
dynamic
Use the accumulated dynamic time.
list
List all relax conditions, including their name and settings.
modify s keyword
Finds the previously created zone relax apply condition with name s, and modify its settings. The following keywords are available:
fish s
Specify a FISH function that determines the multiplier to use as the excavation progresses. This should return a value of 1.0 at the start, and 0.0 and the
end. If this keyword is used, the default servo is not used.
fish-local s
Specify a FISH function that determines the multiplier to use as the excavation progresses. This function is called separately for each individual zone taking
part in the apply condition. If this keyword is used, the default servo is not used.
The function is assumed to take two arguments. The first argument is a pointer to the zone in question. The second argument is unused.
name s
Assigns the apply condition an identifying name s. If a name is not specified one will be created automatically based on the internally assigned ID number.
servo-bound f
If the current mechanical force ratio (see the zone ratio) is lower than this value, the reduction factor is reduced by the increment. The default value is 1e-
3
servo-increment f
If the current mechanical force ratio is less than servo-bound, then the reduction factor is reduced by subtracting f from it. This number should be less than
1.0, and greater than 0.0. The default value is 0.005.
step i
If set to a positive value, then any FISH, table, or servo parameters are ignored and the reduction factor is reduced linearly from the current value (which is
at start 0.99) to minimum (by default 0.0) over the course of i steps.
If specified, then the reduction factor is given by table s. A lookup is performed every step. By default the x value used to lookup a table y value will be the
accumulated mechanical time, which for a purely static analysis is the same as the number of steps. The time index used can be changed by using the
optional time keyword, with the following options.
step
Use the total cycle count.
mechanical
Use the accumulated mechanical time (the default)
fluid
Use the accumulated fluid flow time.
thermal
Use the accumulated thermal time.
creep
Use the accumulated creep time.
dynamic
Use the accumulated dynamic time.
zone results command

Syntax
zone results
Primary keywords:
active | attach | displacements | extra | forces | groups | interfaces | model-fluid | model-mechanical | model-thermal | pore-pressure | saturation | stresses | temperatures |
velocities | water
Controls if and what values are saved from zones in an exported results file. See the model results export command. By default zones values are active. The values
being exported by default are stresses, groups, and displacements.
active b
Controls if any zone values will be exported.
attach b
all attach condition information
displacements b
displacement vectors at gridpoints
extra b
all extra variables at zones and gridpoints
forces b
unbalanced force information at gridpoints, including the last local force ratio.
groups b
Group assignments to zones, faces, and gridpoints
interfaces b
all interface information
model-fluid b
all fluid constitutive model information
model-mechanical b
all mechanical constitutive model information
model-thermal b
all thermal constitutive model information
pore-pressure b
pore pressure values at gridpoints
range <range>
Specifies a range used to filter which zones are included in a results file export. This range is saved and restored as part of the model state. Note that this
facility is still somewhat experimental, and there may be issues if zone-dependent features like attach, apply, etc. are also included in a results export.
saturation b
saturation values at gridpoints
stresses b
average stresses in each zone. Note that the internal tetra stresses are never exported.
temperatures b
temperature values at gridpoints
velocities b
velocity vectors at gridpoints
water b
all water table information.
zone select command

Syntax
zone select <keyword> <range>
Primary keywords:
b | new | undo
This commands selects or de-selects all zones in the range. Selected objects can be specified in a range filter by using the selected keyword. Objects that are not selected
can be specified in a range filter by using the deselected keyword.
If a boolean type is specified, then if on it selects all zones in the range. If off it de-selects all zones in the range. on is the default if no keyword is given.
new
Implies on. This will select zones in the range, and automatically de-select zones not in the range.
undo
This will reverse the operation of the last zone select command. FLAC3D keeps a maximum undo stack of size 12.
zone separate command

Syntax
zone separate keyword <range>
Primary keywords:
by-face
separates internal faces specified by the range. The gridpoints of the face are duplicated, and a new surface face is created. New faces and gridpoints get copies of all
group and extra variable assignments belonging to the original face and gridpoint.
Note that faces may be restricted by giving two group range elements, therefore indicating that the face must be on the surface of the first and the second group. For
instance, if Fred and George are group names assigned to zones, then
range group 'Fred' group 'George'
will select faces that are connected to zone of both group Fred and George. Also note that faces can be selected by group directly.
One (consistent) side of the newly created faces will have a new group assignment made, to make it easier to distinguish one side from the other after creation (since
they will be in the same location in space). By default, the new side will be assigned the group NewSideX in slot Separate, where X is a number starting at 1 and
incrementing with each zone separate command. The new-side keyword can be used to specify which side is assigned and the group and slot name used.
Note that this command uses a different algorithm than in past versions of FLAC3D, and should work correctly on zone regions that are not perfectly topologically
connected, such as commonly result from a zone densify command. However this requires that only one surface with clear sides be created, if multiple intersecting
surfaces are designed, use two zone separate by-face commands.
At this time, only one option to select faces for separation is available:
by-face
Attempts to separate all internal faces in the range.
clear-attach
By default, an error occurs if any gridpoint that has an attach condition associated with it is found among those to be separated. However, if the clear-attach
keyword is supplied, then the separation of gridpoints will occur regardless. In addition, FLAC3D will remove any attach conditions connected to
gridpoints affected.
new-side keyword
origin v
Specify a location in space used to determine which side is assigned to the new group. If the vector from the origin to the face centroid is in the
opposite direction then the group name is assigned. This check is made to the first valid face encountered, and the side is kept consistent from then
on. By default, the origin is (0,0,0).
group s <slot s >
Newly created faces will be assigned the group name name in the specified slot. The default slot, which is used if slot s is not supplied, is named
Default. |flac3| determines which face will be new and which one will be old by using the origin keyword. Use of the group logic is described in
Group.
zone split command

Syntax
zone split <keyword> <range>
Primary keywords:
exclude-quadrilateral | merge
Splits zones in the range into multiple hexahedral zones.
Splits tetrahedral zones into four hexahedral zones. Wedge zones are split into six hexahedral zones. Hexahedral zones are split into eight smaller hexahedral zones.
This command is not applicable to pyramid and degenerate brick zones.
exclude-quadrilateral
Any quadrilateral faces will be excluded from splitting, causing wedge zones to be split into three hexahedral zones, and hexahedral zones to be skipped,
tetrahedral zones still to e split into four hexahedral zones.
merge b
If set to off, new gridpoints created will not be automatically merged with existing gridpoints. The default is on.
zone thermal command

Syntax
zone thermal keyword
Primary keywords:
active | cmodel | implicit | list | property | property-distribution | time-total | zone-based-temperature
Set parameters for a thermal analysis (only available if model configure thermal has been specified). The following keywords apply:
active b
Sets thermal calculations on or off. The default is on after model configure thermal has been specified.
cmodel keyword <range>
Associates a thermal constitutive model with specified zones in the grid. It also allows querying of properties and states of constitutive models.
assign keyword
assigns a thermal model to all zones in the range. This keyword may only be given if the model is configured for thermal calculations (see model
configure fluid and Mathematical Model Description).
advection-conduction
Assign advection-conduction model.
anisotropic
Assign thermal anisotropic model.
hydration
Assign thermal hydration model.
isotropic
Assign thermal isotropic model.
null
Assign thermally null model.
list
List the available thermal constitutive models and their properties.
implicit b
Turns implicit mode on or off. By default implicit mode is off. Implicit mode requires a manually specified timestep. Note that specifying a timestep that is too
large can cause the iterative matrix solver to fail to converge. (see Implicit Formulation)
list keyword
information
List general information about the zone specific thermal calculation settings.
property s <range>
List the values of all thermal properties matching s in the range.
Assigns properties for the thermal constitutive models of all zones in the range. Any number of name value pairs may be assigned. Any constitutive model that
has a matching property name will be assigned the value. The properties of the Advection-Conduction model are listed here, of the Anisotropic Heat Conduction
model are listed here, of the Isotropic Heat Conduction model are listed here, and of the Hydration model are listed here.
property-distribution s akeyword <range>
Assigns a single property name to the thermal constitutive models of all zones in the range. The property value may be varied in space by using the following
optional keyword values.
add
Add a to the property value. This keyword only applies to float type property values.
A Gaussian distribution is used to assign the value randomly, with a mean value of a and a standard deviation of f. This keyword only applies to float type
property values.
deviation-uniform f
A uniform distribution is used to assign the value randomly, with a mean value of a and a standard deviation of f. This keyword only applies to float type
property values.
Apply a gradient to the property value. This keyword only applies to float type property values.
multiply
Multiply the property value by a.
vary v
Apply a linear variation to the property value. This keyword only applies to float type property values.
time-total f
Specifies the accumulated zone thermal time, defined as the sum of all the timesteps over which zone thermal is active. Once set, thermal time will continue to
accumulate with subsequent cycles.
zone-based-temperature b
Turns zone-based temperatures on and off. By default temperatures are calculated and stored at gridpoints, and the zone temperature is the average gridpoint
value. When this is turned on, the zone temperature is stored in the zone an the gridpoint temperatures are ignored. Temperatures must be set manually using the
zone.temp FISH intrinsic.
zone trace command

Syntax
zone trace keyword
Primary keywords:
zoneid | gridpointid | position
Trace zone position and velocity. See the trace command.
The positions and velocities of locations on the zone can be sampled and stored during a model run by using this command. The resulting path through space can be
visualized with the FLAC3D interface. Only one trace position may be created per zone trace command. Traces may be added at any time.
A summary of all traces can be obtained by using the trace list command.
The following keywords are available to specify which zone location is traced.
zoneid i
Add a trace of the centroid of the zone with ID i.
gridpointid i
Add a trace of the location corresponding to the gridpoint ID i.
position v
Add a trace at position v, which must fall in or on some zone.
zone validate command

Syntax
zone validate keyword ...
Primary keywords:
group | vector | surface
Note
This command is new and experimental. Use it as a sanity check of the result of a zone attach by-face command. Note also that currently it does not take into
account interfaces, so these will probably show up as unconstrained areas.
This command attempts to validate the model, by performing checks for common errors or omissions in the model setup.
Currently, the command attemps to discover internal gridpoints that are "unconstrained", generally due to a failure to attach them properly. This most commonly
happens because of non-planar faces that require higher than default tolerances in the zone attach by-face command.
Potential unconstrained directions are determined using the normal vector to any surface faces attached to the gridpoint. Potential unconstrained directions are removed
by adding constraints due to zones they are connected to, attach conditions, or fixity conditions. In general, there is a 45 degree tolerance used to determine if a
constrained removes a possible unconstrained direction.
All surface faces attached to gridpoints that appear to have a direction that is unconstrained will be tagged with the group name Unconstrained in the slot Validate. Note
that any existing face group assignments in the given slot will be deleted. The group name and slot used can be controlled with the group keyword.
By default, both external and internal surfaces that are not internal (meaning they have open space next to them with no zones) are removed, although this can be turned
off using the surface keyword.
If the vector is set to true, then any current user defined vectors (see the command data vector create) are deleted and new ones are created to represent any
unconstrained directions detected. The base of the vector will correspond to the gridpoint, and the direction will be the direction that was determined to be
unconstrained.
The easiest way to visualize the result is to make a Zone Face plot, showing Grouped faces, with a Group range element that selects the group and slot used.
group sgroup <slot sslot >
Specify the group name assigned to surface faces attached to gridpoints that appear unconstrained. By default the group name used is Unconstrained. The slot
keyword may be used to override the slot the group name will be assigned to, which by default is Validate. Note that all group assignments on faces in that slot
will be removed before validation.
vector b
If true, will delete all user defined vector data and fill it with the location and direction of unconstrained gridpoints. The default is false.
surface b
If true, the system will attempt to determine if an unconstrained direction represents an internal excavation or an external surface, by looking to see if a zone
exists in that direction. If no zone is found, it will be assumed the unconstrained direction represents a deliberate free surface and it will be removed. The default
is true.
zone water command

Syntax
zone water keyword
Primary keywords:
density | list | set | plane
This command initializes pore pressures, changing the effective stresses. FLAC3D uses effective stresses (i.e., total stresses plus pore pressure) in constitutive models.
Pore pressures are defined at gridpoints, and zone pore pressures are then calculated as the average of the zone gridpoints. If model configure fluid is not set, pore
pressures are not affected by zone volume changes, there is no flow of water, and the dry density must be specified for zones above the water table and the saturated
material density for zones below.
density f keyword <range>
fluid density, ρw [SI units: kg/m3]. This will force a recalculation of pore pressures on all gridpoints in the range.
effective
If this keyword is specified, then the total stresses in all zones connected to gridpoints in the range will be adjusted to keep the effective stress constant.
skip-assignment
If this keyword is specified, then the values used to calculate pore-pressures is changed to pore-pressures are not actually assigned to any gridpoints. The
values specified will remain until the next zone water command is given.
list
Lists the current water table settings. This includes the assumed fluid density, the geometric set to use (if any), and the water table plane last specified.
set s keyword <range>
Specify the geometric set used to determine water surface location. By default, the name is Water Surface. Specifying a new set name causes a recalculation of
gridpoint pore pressures for all gridpoints below polygons in that set that are also in the range. See the geometry command.
effective
skip-assignment
If this keyword is specified, then the values used to calculate pore-pressures is changed to pore-pressures are not actually assigned to any gridpoints. The
values specified will remain until the next zone water command is given.
plane keyword <range>
Specify a water table plane. The water table sets pore pressure for all gridpoints (and, hence, zones) below the water table. The pore-pressure gradient is given by
the direction of the gravity vector, which can be arbitrary (see the model gravity command).
The following keywords are available to set the plane location and orientation.
effective
normal v
normal direction to the plane, defined by unit vector v and pointing in the direction of increasing pore pressure.
origin v <keyword>
one point at coordinate location (v) on the plane
skip-assignment
the plane to use for the purpose of calculate pore pressures is specified, but pore pressures are not actually assigned to gridpoints in the range.
FISH Functions
l Zone Gridpoint Functions

l Zone Functions
l Zone Face Functions
l Zone Tetra Functions
l Zone Field Data Functions
l Zone Attach Functions
l Zone Interface Functions
l Zone Interface Element Functions
l Zone Interface Node Functions
Zone Gridpoint Functions
gp.accel(GP_PNT<,INT>)
Get the acceleration vector for the gridpoint.
gp.biot.modulus(GP_PNT)
Get/set the fluid Biot modulus.
gp.convergence(GP_PNT)
gp.copy(GP_PNT,GP_PNT)
Copies the gridpoint state information from the source to the...
gp.disp(GP_PNT<,INT>)
Get/set the displacement vector for the gridpoint.
gp.disp.small(GP_PNT<,INT>)
Get the small displacement vector for the gridpoint.
gp.dynamic.mul(GP_PNT)
Get/set the dynamic stepping multiplier.
gp.extra(GP_PNT<,INT>)
Get/set the extra variable at the index associated with the...
gp.find(INT)
Get a pointer to the gridpoint with internally assigned ID...
gp.fix(GP_PNT<,INT>)
Get/set a vector indicating gridpoint fixity.
gp.flow(GP_PNT)
Get/set the unbalanced flow discharge at a gridpoint.
gp.fluid.app(GP_PNT)
Get the total applied fluid load at a grid point.
gp.fluid.load(GP_PNT)
Get/set the additional fluid load.
gp.fluid.modulus(GP_PNT)
Get/set the gridpoint fluid bulk modulus.
gp.fluid.modulus.confined(GP_PNT)
Get/set the fluid flow confined modulus times nodal volume.
gp.fluid.tension(GP_PNT)
Get/set the gridpoint fluid tension limit.
gp.fluid.unbal(GP_PNT)
Get/set the the fluid out-of-balance flow; used in the fast...
gp.fluid.vol.inv(GP_PNT)
Get the inverse of the fluid nodal volume.
gp.flux(GP_PNT)
Get the unbalanced thermal flux at a gridpoint.
gp.force.app(GP_PNT<,INT>)
Get the total applied force at a gridpoint.
gp.force.load(GP_PNT<,INT>)
Get/set the FISH applied force at a gridpoint.
gp.force.unbal(GP_PNT<,INT>)
Get the unbalanced force at a gridpoint.
gp.group(GP_PNT<,STR>)
Get/set the group name assigned to zone gridpoint gp in...
gp.group.remove(GP_PNT,STR)
Remove the group s from zone gridpoint gp in all...
gp.head
Get the first zone gridpoint in the list of all...
gp.id(GP_PNT)
Get the zone gridpoint ID number, which is a unique...
gp.isgroup(GP_PNT,STR<,STR>)
gp.link.index(GP_PNT)
Get the index location of this gridpoint in the first...
gp.link.zone(GP_PNT)
Get the first zone connected to this gridpoint.
gp.list
Get the list of all gridpoints in the model.
gp.mass.add(GP_PNT<,INT>)
Get/set the added mass vector for the gridpoint.
gp.mass.gravity(GP_PNT)
Get the gravitational mass.
gp.mass.inertial(GP_PNT)
Get the gridpoint inertial mass.
gp.maxid
Get the maximum ID number assigned to any gridpoint in...
gp.near(VEC+)
Get the gridpoint nearest v ; will return null if there...
gp.near.all(VEC+)
Get the gridpoint nearest v ; will return null if there...
gp.near.live(VEC+,BOOL,BOOL,BOOL,STR)
Get the gridpoint nearest point v .
gp.next(GP_PNT)
Get the next gridpoint after gp in the list of...
gp.num
Get the total number of gridpoints in the model.
gp.pos(GP_PNT<,INT>)
Get/set the position of the gridpoint.
gp.pp(GP_PNT<,INT>)
Get/set the gridpoint pore pressure.
gp.pp.fix(GP_PNT)
Get/set the flag indicating that the pore pressure in the...
gp.ratio(GP_PNT)
gp.ratio.target(GP_PNT)
Get/set the target local gridpoint mechanical convergence ratio.
gp.sat(GP_PNT)
Get/set the fluid saturation.
gp.state.restore(GP_PNT)
Restores all gridpoint state information from the currently open FISH ...
gp.state.save(GP_PNT)
Saves all gridpoint state information to the currently open FISH ...
gp.stiff(GP_PNT)
Get the accumulated gridpoint effective stiffness.
gp.temp(GP_PNT)
Get/set the current gridpoint temperature.
gp.temp.app(GP_PNT)
Get the total applied thermal flux at a grid point.
gp.temp.change(GP_PNT)
Get/set the temperature change of the grid point since the...
gp.temp.fix(GP_PNT)
Get/set the flag indicating that temperature in this gridpoint is...
gp.temp.source(GP_PNT)
Get/set the applied FISH temperature source at a gridpoint.
gp.typeid
gp.vel(GP_PNT<,INT>)
Get/set the velocity vector for the gridpoint.
Zone Functions
zone.aspect(ZONE_PNT)
Get the measure of a zone's aspect ratio.
zone.code(ZONE_PNT)
Get the zone code.
zone.condition(ZONE_PNT<,INT>)
Get the zone condition number.
zone.containing(VEC+<,ZONE_PNT>)
Get the zone that encompasses the point v .
zone.copy(ZONE_PNT,ZONE_PNT)
Copies the zone state information from the source zone to...
zone.create.interface.elem(ZONE_PNT,INT,STR)
create new interface elements attached to a zone face.
zone.create.ratio(FLT,INT,INT)
Get a value calculated by a geometric progression, given a...
zone.creep.time.total
Get/set the total accumulated zone module creep time.
zone.creep.timestep
Get/set the timestep used by the zone creep module when...
zone.density(ZONE_PNT)
Get/set the density of the zone.
zone.dynamic.mul(ZONE_PNT)
Get the multiple calculated for that zone when dynamic multistepping...
zone.dynamic.time.total(ZONE_PNT)
Get/set the total accumulated zone module dynamic time.
zone.dynamic.timestep
Get/set the timestep used by the zone dynamic module when...
zone.extra(ZONE_PNT<,INT>)
Get/sets the value stored in the i th extra variable array...
zone.find(INT)
Get the zone with internally assigned ID number i .
zone.flow(ZONE_PNT<,INT>)
Get the specific discharge vector for the zone.
zone.fluid.density(ZONE_PNT)
Get/set the fluid density for the zone.
zone.fluid.model(ZONE_PNT)
Get/set the fluid flow constitituve model for the zone.
zone.fluid.prop(ZONE_PNT,STR)
Get/set the value for fluid property s in zone z .
zone.fluid.ratio
Get the current fluid convergence ratio for zones.
zone.fluid.stress.normal
Get the representative stress magnitude for the fast flow solution...
zone.fluid.time.total
Get/set the total accumulated zone module fluid time.
zone.fluid.timestep
Get/set the current fluid timestep.
zone.fluid.unbal.avg
Get the average unbalanced fluid volume limit for the fast...
zone.fluid.unbal.max
Get the maximum unbalanced fluid limit for the fast flow...
zone.flux(ZONE_PNT<,INT>)
Get the zone average heat flux vector.
zone.force.update
Flags the cycling logic so that a geometry update is...
zone.geom.test(ZONE_PNT)
Test the geometric fitness of a zone.
zone.gp(ZONE_PNT,INT)
Get the gridpoint associated with the zone at index i .
zone.gp.num(ZONE_PNT)
Get the number of unique gridpoints associated with this type...
zone.group(ZONE_PNT<,STR>)
Get/set the group name assigned to zone z in slot...
zone.group.remove(ZONE_PNT,STR)
Remove the group s from zone z , in all slots...
zone.head
Get the first zone in the list of all zones...
zone.hysteretic(ZONE_PNT,STR)
Get/set the hysteretic damping parameter s in zone z .
zone.id(ZONE_PNT)
Get the zone ID number, a unique number assigned by...
zone.isgroup(ZONE_PNT,STR<,STR>)
Check if the group s is associated with the zone.
zone.islive(ZONE_PNT)
Checks if the zone is "live", meaning it has a...
zone.join(ZONE_PNT,INT)
Get the zone joined to face i of zone z .
zone.link.index(ZONE_PNT,INT)
Get the index of the next zone in the list...
zone.link.zone(ZONE_PNT,INT)
Get the next zone in the list of all zones...
zone.list
Get the list of all zones in the model.
zone.maxid
Get the maximum ID number assigned to any zone in...
zone.mech.convergence
Get the current maximum value of convergence in any gridpoint...
zone.mech.prop.name(ZONE_PNT,INT)
Get the name of the i th property in the list...
zone.mech.prop.num(ZONE_PNT)
Get the total number of properties accepted by the mechanical...
zone.mech.ratio
Get the current zone mechanical convergence ratio.
zone.mech.ratio.avg
Get the current zone mechanical average convergence ratio.
zone.mech.ratio.local
Get the current zone mechanical local convergence ratio.
zone.mech.ratio.max
Get the current zone mechanical maximum convergence ratio.
zone.model(ZONE_PNT)
Get/set the name of the current zone mechanical constitutive model.
zone.model.init(ZONE_PNT)
Initializes all constitutive models (mechanical, fluid, and thermal) assigned to...
zone.near(VEC+)
Get the zone with the centroid nearest v .
zone.near.all(VEC+)
Get the zone with the centroid nearest v .
zone.near.live(VEC+,BOOL,BOOL,BOOL,STR)
Get the zone with a centroid nearest point v .
zone.near.map(VEC+,FLT)
Finds all zones with centroids within f distance of position...
zone.next(ZONE_PNT)
Get the next zone after z in the list of...
zone.num
Get the total number of zones in the model.
zone.ortho
Get a measure of orthogonality for the zone.
zone.overlays(ZONE_PNT)
Get the number of overlays available in the zone.
zone.planarity(ZONE_PNT)
Get a measure of how planar the quadrilateral faces of...
zone.plane.traction(ZONE_PNT,VEC<,ARR_PNT>)
Get the traction on the zone in the place normal...
zone.pos(ZONE_PNT<,INT>)
Get the zone centroid position.
zone.pp(ZONE_PNT)
Get/set the average zone pore pressure.
zone.prop(ZONE_PNT,STR)
Get/set the value of property s in the zone.
zone.rotation.inc(ZONE_PNT<,INT<,INT>>)
Get the zone rotational increment tensor, or a component of...
zone.rotation.rate(ZONE_PNT<,INT<,INT>>)
Get the zone rotation rate tensor or component.
zone.state(ZONE_PNT)
Get/set the current plasticity state indicators for the zone.
zone.state.restore(ZONE_PNT)
Restores all zone state information from the currently open FISH ...
zone.state.save(ZONE_PNT)
Saves all zone state information to the currently open FISH ...
zone.strain.inc(ZONE_PNT<,INT<,INT>>)
Get the zone strain increment, based on the current displacement...
zone.strain.rate(ZONE_PNT,INT<,INT>)
Get the zone strain rate, based on the current velocity...
zone.strain.shear.inc(ZONE_PNT)
Get the zone shear strain increment based on the current...
zone.strain.shear.rate(ZONE_PNT)
Get the zone shear strain rate based on the current...
zone.strain.vol.inc(ZONE_PNT)
Get the zone volumetric strain increment based on the current...
zone.strain.vol.rate
Get the zone volumetric strain rate based on the current...
zone.stress(ZONE_PNT<,INT<,INT>>)
Get/set the zone stress.
zone.stress.effective(ZONE_PNT,INT<,INT>)
Get the zone effective stress.
zone.stress.int(ZONE_PNT)
Get the intermediate principal stress of the volume-weighted average of...
zone.stress.max(ZONE_PNT)
Get the maximum (most positive) principal value of the volume-averaged...
zone.stress.min(ZONE_PNT)
Get the minimum (most negative) principal value of the volume-averaged...
zone.stress.prin(ZONE_PNT<,INT>)
Get the zone principal stress, calculated from the volume-weighted average...
zone.stress.prin.dir(ZONE_PNT,ARR_PNT,ARR_PNT)
Get the zone principal stress directions, calculated from the volume-averaged...
zone.temp(ZONE_PNT)
Get/set the zone temperature.
zone.test.quality
Get a measure of the zone quality, or how the...
zone.thermal.model(ZONE_PNT)
Get/set the thermal flow constitutive model for the zone.
zone.thermal.prop(ZONE_PNT,STR)
Get/set the value for thermal property s in zone z .
zone.thermal.ratio
Get the current thermal convergence ratio for zones.
zone.thermal.time.total
Get/set the total accumulated zone module thermal time.
zone.thermal.timestep
Get/set the current thermal timestep.
zone.typeid
zone.unbal
Get the current maximum unbalanced force on any gridpoint in...
zone.vol(ZONE_PNT)
Get the zone volume calculated using the current position of...
zone.vol.deformed(ZONE_PNT)
Get the volume of a zone using gridpoint positions that...
zone.was.updated
Returns TRUE if the last validation check actually performed a...
zone.work.elastic.shear(ZONE_PNT)
Get the shear elastic work.
zone.work.elastic.total(ZONE_PNT)
Get the total elastic work.
zone.work.elastic.vol(ZONE_PNT)
Get the volumetric elastic work.
zone.work.plastic.shear(ZONE_PNT)
Get the shear plastic work dissipated.

zone.work.plastic.total(ZONE_PNT)
Get the total plastic work dissipated.
zone.work.plastic.vol(ZONE_PNT)
Get the volumetric plastic work dissipated.
Zone Face Functions
Note that zone faces do not have their own objects, and are therefore not referenced by pointer. They are specified most often by a zone pointer and a side index, which is
therefore not necessarily unique for internal faces.
zone.face.area(ZONE_PNT,INT)
Get the area of the face.
zone.face.extra(ZONE_PNT,INT,INT)
Get/set the value of the index in the extra variable...
zone.face.find(ZONE_PNT,INT/GP_PNT,INT/GP_PNT,INT/GP_PNT)
Get the face index of zone z that contains the...
zone.face.find.normal(ZONE_PNT,VEC)
Get the face index of zone z whose outward-facing normal...
zone.face.gp(ZONE_PNT,INT,INT)
Get a pointer to a gridpoint on face given by...
zone.face.group(ZONE_PNT,INT<,STR>)
Get/set the group name associated with the face identified by...
zone.face.group.remove(ZONE_PNT,INT,STR)
Removes the group name s from the face identified by...
zone.face.isgroup(ZONE_PNT,INT,STR<,STR>)
zone.face.normal(ZONE_PNT,INT<,INT>)
Get the normal to the face, facing outward from zone...
zone.face.pos(ZONE_PNT,INT<,INT>)
Get the position of the face, defined as the centroid...
zone.face.size(ZONE_PNT,INT)
Get the number of unique face vertices.
Zone Tetra Functions
Note that internal zone tetra are not available to fish as their own objects, and are therefore not referenced by pointer. They are specified most often by a zone pointer, an
overlay index, and a position index.
zone.tet.gp(ZONE_PNT,INT,INT,ARR_PNT)
Gets the gridpoint pointers associated with a tetrahedron number itet ...
zone.tet.num(ZONE_PNT)
Get the number of tetra in each overlay of the...
zone.tet.smallest.vol(ZONE_PNT)
Get the volume of the smallest tetrahedron in an overlay.
zone.tet.strain.inc(ZONE_PNT,INT,INT<,INT<,INT>>)
Get the zone tetra strain increment based on the current...
zone.tet.strain.rate(ZONE_PNT,INT,INT<,INT<,INT>>)
Get the zone tetra strain rate based on the current...
zone.tet.stress(ZONE_PNT,INT,INT<,INT<,INT>>)
Get/set the zone tetra stress.
Zone Field Data Functions
Zone field data functions offer a way to efficiently request a scalar value from any position in the model covered by a zone. See Zone Field Data for further information and
examples.
zone.field.component
Get/set the scalar value retrieved from a name that returns...
zone.field.extra
Get/set the index used to retrieve extra variables.
zone.field.get(VEC+<,FLT>)
Get data from the model at the location specified by...
zone.field.get.gp(GP_PNT,ZONE_PNT)
Get data directly from the gridpoint gp and zone z .
zone.field.gravity
Get/set gravitational force setting.
zone.field.hide.fluidnull
Get/set the null fluid constitutive model setting.
zone.field.hide.mechnull
Get/set the null mechanical constitutive model setting.
zone.field.hide.thermnull
Get/set the null thermal constitutive model setting.
zone.field.index
Get/set the the index number of the data type name...
zone.field.init
Initializes the zone field data system for the current method...
zone.field.log
Get/set the logarithmic setting.
zone.field.method.index
Get/set the index number of the extrapolation method used for...
zone.field.method.name
Get/set the method used for extrapolation of zone-based variables.

zone.field.name
Get/set the name of the value being retrieved from zones.
zone.field.power
Get/set the power exponent used for the inverse-distance-weighting method of...
zone.field.prop
Get/set the name of the property to retrieve when the...
zone.field.quantity
Get/set the scalar quantity to retrieve when the value being...
zone.field.radius.ratio
Get/set the the radius ratio parameter used for the inverse-distance-weighting ...
zone.field.reset
Removes the effect of zone.
zone.field.source
Get/set where values are derived from when appropriate.
zone.field.tol
Get/set the tolerance used for the polynomial method of extrapolation.
zone.field.type
Get/set the type to assume, for those values where the...
Zone Attach Functions
attach.create(GP_PNT,GP_PNT/ZONE_PNT<,GP_PNT/INT>)
If only one gridpoint pointer is given as a parameter,...
attach.delete(ATTACH_PNT)
Deletes an attachment, return value is undefined.
attach.extra(ATTACH_PNT<,INT>)
attach.find(INT)
Get the pointer to the attach condition with ID i .
attach.group(ATTACH_PNT<,STR>)
Get/set the group name assigned to attach a in slot...
attach.group.remove(ATTACH_PNT,STR)
Remove the attach condition with the group name.
attach.id(ATTACH_PNT)
Get the ID number of the given attach condition.
attach.isgroup(ATTACH_PNT,STR<,STR>)
Check if the group s is associated with the attach.
attach.list
Get the list of all attaches in the model.
attach.master(ATTACH_PNT<,INT>)
Get the master gridpoint pointer.
attach.master.face(ATTACH_PNT)
Get the face side associated with this attach condition (from...
attach.master.zone(ATTACH_PNT)
Get a pointer to the master zone for type 3...
attach.maxid
Get the maximum ID number assigned to any attach condition...
attach.num
Get the total number of attach conditions in the model.
attach.pos(ATTACH_PNT<,INT>)
Get the attach position.
attach.slave(ATTACH_PNT)
Get a pointer to the slave gridpoint.
attach.snap(ATTACH_PNT)
Get/set snap option for attach.
attach.type(ATTACH_PNT)
Get 1, 2, or 3, indicating that the attachment is...
attach.typeid
attach.weight.edge(ATTACH_PNT)
Get a value in the range 0 to 1.
attach.weight.face(ATTACH_PNT)
Get a vector with all components in the range 0...
Zone Interface Functions
interface.find(INT)
Get the interface with internally assigned ID number i .
interface.head
Get the first interface in the list of all interfaces...
interface.id(INTERFACE_PNT)
Get the interface ID number, a unique number assigned by...
interface.list
Get the list of all interfaces in the model.
interface.name(INTERFACE_PNT)
Get the interface with the assigned name s .
interface.next(INTERFACE_PNT)
Get the next interface after it in the list of...
Zone Interface Element Functions
Unlike zones and gridpoints, there is no global list of all interface elements. Instead, each interface keeps its own list of elements.
interface.elem.area(INTERFACE_ELEM_PNT)
Get the area of the interface element.
interface.elem.extra(INTERFACE_ELEM_PNT<,INT>)
interface.elem.head(INTERFACE_PNT)
Following sentence doesn't make sense.
interface.elem.host.face(INTERFACE_ELEM_PNT)
Get the face ID number (1-6) to which the interface...
interface.elem.host.zone(INTERFACE_ELEM_PNT)
Get the address of the zone to which the interface...
interface.elem.id(INTERFACE_ELEM_PNT)
Get the ID number of the given interface element.
interface.elem.join(INTERFACE_ELEM_PNT,INT)
Get the pointer to the adjacent interface element joined across...
interface.elem.list(INTERFACE_PNT)
Get the list of all interface elements in the model.
interface.elem.next(INTERFACE_ELEM_PNT)
Get the next interface element after ie in the list...
interface.elem.normal(INTERFACE_ELEM_PNT<,INT>)
Get the normal vector for the interface element.
interface.elem.vertex(INTERFACE_ELEM_PNT,INT)
Get the pointer of the vertex associated with the interface...
Zone Interface Node Functions
Unlike zones and gridpoints, there is no global list of all interface nodes. Instead, each interface keeps its own list of nodes.
interface.node.area(INTERFACE_NODE_PNT)
Get the characteristic area of the node (only valid after...
interface.node.disp(INTERFACE_NODE_PNT<,INT>)
Get the displacement vector for the interface node.
interface.node.disp.shear(INTERFACE_NODE_PNT<,INT>)
Get/set the relative shear displacement vector for the interface node.
interface.node.extra(INTERFACE_NODE_PNT<,INT>)
interface.node.find(INTERFACE_PNT,INT)
Get the interface node with the given ID number.
interface.node.head(INTERFACE_PNT)
Get the first interface node in the list of all...
interface.node.host.face(INTERFACE_NODE_PNT)
Get the face ID (1-6) of the zone face to...
interface.node.host.weight(INTERFACE_NODE_PNT,INT)
Get the weighting factor for vertex i (1-4) of the...
interface.node.host.zone(INTERFACE_NODE_PNT)
Get the zone pointer to which the node is attached.
interface.node.id(INTERFACE_NODE_PNT)
Get the ID number of the given interface node.
interface.node.list(INTERFACE_PNT)
Get the list of all interface nodes in the model.
interface.node.next(INTERFACE_NODE_PNT)
Get the next interface node after in in the list...
interface.node.normal(INTERFACE_NODE_PNT<,INT>)
Get the normal vector for the interface node, which is...
interface.node.penetration(INTERFACE_NODE_PNT)
Get interface node penetration with the contacting zone face (only...
interface.node.pos(INTERFACE_NODE_PNT<,INT>)
Get/set the position vector for the interface node.
interface.node.pp(INTERFACE_NODE_PNT)
Get the pore pressure of the node (only valid after...
interface.node.prop(INTERFACE_NODE_PNT,STR)
Get/set the property identified by s of the interface node.
interface.node.slip(INTERFACE_NODE_PNT)
Get/set the slip status (0-2) of the interface node: 0...
interface.node.stress.normal(INTERFACE_NODE_PNT)
Get the normal stress at the node.
interface.node.stress.normal.add(INTERFACE_NODE_PNT)
Get/set the additional normal stress.
interface.node.stress.shear(INTERFACE_NODE_PNT<,INT>)
Get/set the shear stress vector for the interface node.
interface.node.target.face(INTERFACE_NODE_PNT)
Get the face ID (1-6) of the zone face in...
interface.node.target.weight(INTERFACE_NODE_PNT,INT)
Get the weighting factor for vertex i (1-4) of the...
interface.node.target.zone(INTERFACE_NODE_PNT)
Get the zone pointer in contact with the node.
interface.node.tol(INTERFACE_NODE_PNT)
Get/set the interface node contact tolerance, a dimensionless measure of how...
interface.node.vel(INTERFACE_NODE_PNT<,INT>)
Get/set the velocity vector for the interface node.
l attach.create
l attach.delete
l attach.extra
l attach.find
l attach.group
l attach.group.remove
l attach.id
l attach.isgroup
l attach.list
l attach.master
l attach.master.face
l attach.master.zone
l attach.maxid
l attach.num
l attach.pos
l attach.slave
l attach.snap
l attach.type
l attach.typeid
l attach.weight.edge
l attach.weight.face
l gp.accel
l gp.biot.modulus
l gp.convergence
l gp.copy
l gp.disp
l gp.disp.small
l gp.dynamic.mul
l gp.extra
l gp.find
l gp.fix
l gp.flow
l gp.fluid.app
l gp.fluid.load
l gp.fluid.modulus
l gp.fluid.modulus.confined
l gp.fluid.tension
l gp.fluid.unbal
l gp.fluid.vol.inv
l gp.flux
l gp.force.app
l gp.force.load
l gp.force.unbal
l gp.group
l gp.group.remove
l gp.head
l gp.id
l gp.isgroup
l gp.link.index
l gp.link.zone
l gp.list
l gp.mass.add
l gp.mass.gravity
l gp.mass.inertial
l gp.maxid
l gp.near
l gp.near.all
l gp.near.live
l gp.next
l gp.num
l gp.pos
l gp.pp
l gp.pp.fix
l gp.ratio
l gp.ratio.target
l gp.sat
l gp.state.restore
l gp.state.save
l gp.stiff
l gp.temp
l gp.temp.app
l gp.temp.change
l gp.temp.fix
l gp.temp.source
l gp.typeid
l gp.vel
l interface.elem.area
l interface.elem.extra
l interface.elem.head
l interface.elem.host.face
l interface.elem.host.zone
l interface.elem.id
l interface.elem.join
l interface.elem.list
l interface.elem.next
l interface.elem.normal
l interface.elem.vertex
l interface.find
l interface.head
l interface.id
l interface.list
l interface.name
l interface.next
l interface.node.area
l interface.node.disp
l interface.node.disp.shear
l interface.node.extra
l interface.node.find
l interface.node.head
l zone.face.area
l interface.node.host.face
l interface.node.host.weight
l interface.node.host.zone
l interface.node.id
l interface.node.list
l zone.face.group.remove
l interface.node.next
l interface.node.normal
l interface.node.penetration
l interface.node.position
l interface.node.pp
l interface.node.prop
l interface.node.slip
l interface.node.stress.normal
l interface.node.stress.normal.add
l interface.node.stress.shear
l interface.node.target.face
l interface.node.target.weight
l interface.node.target.zone
l interface.node.tol
l interface.node.vel
l zone.aspect
l zone.code
l zone.condition
l zone.containing
l zone.copy
l zone.create.interface.elem
l zone.create.ratio
l zone.creep.time.total
l zone.creep.timestep
l zone.density
l zone.dynamic.mul
l zone.dynamic.time.total
l zone.dynamic.timestep
l zone.extra
l zone.face.area
l zone.face.extra
l zone.face.find
l zone.face.find.normal
l zone.face.gp
l zone.face.group
l zone.face.group.remove
l zone.face.isgroup
l zone.face.normal
l zone.face.pos
l zone.face.size
l zone.field.component
l zone.field.extra
l zone.field.get
l zone.field.get.gp
l zone.field.gravity
l zone.field.hide.fluidnull
l zone.field.hide.mechnull
l zone.field.hide.thermnull
l zone.field.index
l zone.field.init
l zone.field.log
l zone.field.method.index
l zone.field.method.name
l zone.field.name
l zone.field.power
l zone.field.prop
l zone.field.quantity
l zone.field.radius.ratio
l zone.field.reset
l zone.field.source
l zone.field.tol
l zone.field.type
l zone.find
l zone.flow
l zone.fluid.density
l zone.fluid.model
l zone.fluid.prop
l zone.fluid.ratio
l zone.fluid.stress.normal
l zone.fluid.time.total
l zone.fluid.timestep
l zone.fluid.unbal.avg
l zone.fluid.unbal.max
l zone.flux
l zone.force.update
l zone.geom.test
l zone.gp
l zone.gp.num
l zone.group
l zone.group.remove
l zone.head
l zone.hysteretic
l zone.id
l zone.isgroup
l zone.islive
l zone.join
l zone.link.index
l zone.link.zone
l zone.list
l zone.maxid
l zone.mech.convergence
l zone.mech.prop.name
l zone.mech.prop.num
l zone.mech.ratio
l zone.mech.ratio
l zone.mech.ratio.local
l zone.mech.ratio
l zone.model
l zone.model.init
l zone.near
l zone.near.all
l zone.near.live
l zone.near.map
l zone.next
l zone.num
l zone.ortho
l zone.overlays
l zone.planarity
l zone.plane.traction
l zone.pos
l zone.pp
l zone.prop
l zone.rotation.inc
l zone.rotation.rate
l zone.state
l zone.state.restore
l zone.state.save
l zone.strain.inc
l zone.strain.rate
l zone.strain.shear.inc
l zone.strain.shear.rate
l zone.strain.vol.inc
l zone.strain.vol.rate
l zone.stress
l zone.stress.effective
l zone.stress.int
l zone.stress.max
l zone.stress.min
l zone.stress.prin
l zone.stress.prin.dir
l zone.temp
l zone.test.quality
l zone.tetra.gp
l zone.tetra.num
l zone.tetra.smallest.vol
l zone.tetra.strain.increment
l zone.tetra.strain.rate
l zone.tetra.stress
l zone.thermal.model
l zone.thermal.prop
l zone.thermal.ratio
l zone.thermal.time.total
l zone.thermal.timestep
l zone.typeid
l zone.unbal
l zone.vol
l zone.vol.deformed
l zone.was.updated
l zone.work.elastic.shear
l zone.work.elastic.total
l zone.work.elastic.vol
l zone.work.plastic.shear
l zone.work.plastic.total
l zone.work.plastic.vol
attach.create
Syntax
a = attach.create(g,a1<,a2>)
If only one gridpoint pointer is given as a parameter, creates an attachment to a gridpoint. If two gridpoint pointers are given, creates an attachment to an edge. If a zone
pointer and a face index (1 to 6) are given, creates an attachment to a zone face. Function returns null if failure occurs. The first parameter is the slave gridpoint.
Attachment weights are determined automatically based on current geometry, but may be overridden by using the attach.weight.edge or attach.weight.face
intrinsic functions.
Returns: a - attach pointer

Arguments: g - slave gridpoint pointer
a1 - gridpoint pointer, or zone pointer
a2 - gridpoint pointer if the second argument is a gridpoint pointer,
or index of the matching face, from 1 to 6, if the second argument is a zone pointer
attach.delete
Syntax
i = attach.delete(a)
Deletes an attachment, return value is undefined.
Returns: i - return value is undefined

Arguments: a - attach pointer
attach.extra
Syntax
any = attach.extra(a<,i>)
attach.extra(a<,i>) = any
Get/set the value stored in the ith extra variable array of attach a.
Returns: any - value stored in extra variable slot i for attach a

Accepts: any - value to store in extra variable slot i for attach a
i - integer; if not given, it is assumed to be 1
attach.find
Syntax
a = attach.find(i)
Get the pointer to the attach condition with ID i. Returns a null pointer if one is not found.
Returns: a - attach pointer

Arguments: i - integer
attach.group
Syntax
s = attach.group(a<,slot>)
attach.group(a<,slot>) = s
Get/set the group name assigned to attach a in slot slot. Use of the group logic is described in Group.
attach.group.remove
Syntax
b = attach.group.remove(a,s)
Remove the attach condition with the group name.
Returns: b - true if the group was removed from one or more slots of the attach condition, false if the group was not found in the attach condition
s - name of the group to be removed
attach.id
Syntax
i = attach.id(a)
Get the ID number of the given attach condition.
Returns: i - ID number
attach.isgroup
Syntax
b = attach.isgroup(a,s<,slot>)
Check if the group s is associated with the attach. Will return true if a match is found in any slot. If the optional third argument slot is provided, then it will only check
that slot.
Returns: b - true if the group was found in that attach

Arguments: z - a pointer to an attach
s - a group name
slot - an optional slot specification. If not provided, the check will occur on all slots that have been assigned to the attach.
attach.list
Syntax
l = attach.list
Get the list of all attaches in the model. This is primarily used in the fish_statement_loopforeach statement.
Returns: l - a pointer to the list of all attaches
attach.master
Syntax
g = attach.master(a<,i>)
Get the master gridpoint pointer. For type 1 attachments (gridpoint to gridpoint), returns a pointer to the master gridpoint. Parameter i is not required. For type 2
attachments (edge to gridpoint), returns a pointer to the master gridpoint. The function will return the pointer to the master gridpoint 1 or master gridpoint 2, depending
on whether i is 1 or 2. For type 3 attachments (face to gridpoint), returns the pointer to the master gridpoint 1, 2, 3, or 4.
Returns: g - gridpoint pointer

i - integer, if not given it is assumed to be 1
attach.master.face
Syntax
i = attach.master.face(a)
Get the face side associated with this attach condition (from 1 to 6), or 0 if this is not a face attach type.
Returns: i - face side associated with this attach condition (from 1 to 6), or 0 if this is not a face attach type
attach.master.zone
Syntax
z = attach.master.zone(a)
Get a pointer to the master zone for type 3 attachments (face). If the attachment type is a type other than 3, the function returns a null pointer.
Returns: z - zone pointer

attach.maxid
Syntax
i = attach.maxid
Get the maximum ID number assigned to any attach condition in this model. The next attach condition created will be assigned this value plus one.
Returns: i - maximum ID number of any attach condition in the model
attach.num
Syntax
i = attach.num
Get the total number of attach conditions in the model.
Returns: i - the total number of attach conditions in the model
attach.pos
Syntax
Vector Access
v = attach.pos(p<,i>)
Get the attach position.
Returns: v - attach position vector or component

Arguments: p - attach pointer
Component Access
f = attach.pos.x(p)
Get the x-component of the attach position.
Returns: f - x-component of the attach position vector

f = attach.pos.y(p)
Get the y-component of the attach position.
Returns: f - y-component of the attach position vector

f = attach.pos.z(p)
Get the z-component of the attach position.
Returns: f - z-component of the attach position vector

attach.slave
Syntax
g = attach.slave(a)
Get a pointer to the slave gridpoint.
Returns: g - gridpoint pointer

attach.snap
Syntax
i = attach.snap(a)
attach.snap(a) = i
Get/set snap option for attach. Gridpoints on opposite attached faces will maintain their position if i is set to 1. Snap is set to true by default.
Returns: i - if equal to 1, the snap is true

Accepts: i - if equal to 1, the snap is set to be true
attach.type
Syntax
i = attach.type(a)
Get 1, 2, or 3, indicating that the attachment is attached to a gridpoint, edge, or face.
Returns: i - 1, 2, or 3, indicating that the attachment is attached to a gridpoint, edge, or face

attach.typeid
Syntax
i = attach.typeid
Get an identifier that uniquely determines the type of object. For attaches, this will always return 1283545628.
This can be used with the type.pointer.id intrinsic to identify the object type referred to by a pointer.
attach.weight.edge
Syntax
f = attach.weight.edge(a)
attach.weight.edge(a) = f
Get a value in the range 0 to 1.0. For type 2 attachments (edge), returns the location of the gridpoint in the edge. If the attachment type is a type other than 2, the
function returns 0.0.
Returns: f - value in the range 0 to 1.0

Accepts: f - value in the range 0 to 1.0
attach.weight.face
Syntax
v = attach.weight.face(a)
attach.weight.face(a) = v
Get a vector with all components in the range 0 to 1.0. For type 3 attachments (face), returns the location of the gridpoints in the face with respect to the face vertices.
The fourth quad weight can be computed by subtracting all three weights on the vector from 1.0. If the attachment type is a type other than 3, the function returns a
vector with all values set to 0.0.
Returns: v - vector
Accepts: v - vector
gp.accel
Syntax
Vector Access
v = gp.accel(gp<,i>)
Get the acceleration vector for the gridpoint. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value. This
is only available if model configure dynamic has been specified.
Returns: v - acceleration vector or component

Arguments: z - zone pointer
Component Access
f = gp.accel.x(gp)
Get the x-component acceleration vector. This is only available if model configure dynamic has been specified.
Returns: f - x-component acceleration vector

f = gp.accel.y(gp)
Get the y-component acceleration vector. This is only available if model configure dynamic has been specified.
Returns: f - y-component acceleration vector
f = gp.accel.z(gp)
Get the z-component acceleration vector. This is only available if model configure dynamic has been specified.
Returns: f - z-component acceleration vector

gp.biot.modulus
Syntax
f = gp.biot.modulus(gp)
gp.biot.modulus(gp) = f
Get/set the fluid Biot modulus. Only available if both model configure fluid has been set and zone fluid biot has been set to true. See Biot Coefficient and Biot
Modulus for further discussion.
Returns: f - the Biot modulus

Accepts: f - the Biot modulus
Arguments: gp - a zone gridpoint pointer
gp.convergence
Syntax
f = gp.convergence(gp)
Returns the gridpoint convergence value, defined as the ratio of the currenct local force ratio (gp.ratio) to the target force ratio (gp.ratio.target). A value of 1 or
less is therefore considered "converged".
Returns: f - local gridpoint mechanical convergence

gp.copy
Syntax
i = gp.copy(source,dest)
Copies the gridpoint state information from the source to the destination gridpoints. The return value is ignored.

gp.disp
Syntax
Vector Access
v = gp.disp(gp<,i>)
gp.disp(gp<,i>) = v
Get/set the displacement vector for the gridpoint. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.
Note that in FLAC3D, displacement vectors are accumulated from velocities and timesteps every cycle. They have no direct effect on the model state. Displacements
can be changed at any time without changing the forces or stresses in the model.

Accepts: v - displacement vector or component
Component Access
f = gp.disp.x(gp)
gp.disp.x(gp) = f
Get/set the x-component displacement vector.

Accepts: f - x-component displacement vector
f = gp.disp.y(gp)
gp.disp.y(gp) = f
Get/set the y-component displacement vector.

Accepts: f - y-component displacement vector
f = gp.disp.z(gp)
gp.disp.z(gp) = f
Get/set the z-component displacement vector.

Accepts: f - z-component displacement vector
gp.disp.small
Syntax
Vector Access
v = gp.disp.small(gp<,i>)
gp.disp.small(gp<,i>) = v
Get the small displacement vector for the gridpoint. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component
value.
Small displacements are incremented from velocity and timestep only in the small-strain model. See the command model largestrain. The small-strain vector field is
used in the interface logic to calculate overlaps.
Returns: v - small displacement vector or component

Accepts: v - small displacement vector or component
Component Access
f = gp.disp.small.x(gp)
gp.disp.small.x(gp) = f
Get the x-component small displacement vector.
Returns: f - x-component small displacement vector

Accepts: f - x-component small displacement vector
f = gp.disp.small.y(gp)
gp.disp.small.y(gp) = f
Get the y-component small displacement vector.
Returns: f - y-component small displacement vector

Accepts: f - y-component small displacement vector
f = gp.disp.small.z(gp)
gp.disp.small.z(gp) = f
Get the z-component small displacement vector.
Returns: f - z-component small displacement vector

Accepts: f - z-component small displacement vector
gp.dynamic.mul
Syntax
f = gp.dynamic.mul(gp)
Get/set the dynamic stepping multiplier. This is only available if model configure dynamic has been set and zone dynamic multi-step has been set to on.
Returns: f - the dynamic multiplier factor for this gridpoint

gp.extra
Syntax
a = gp.extra(gp<,index>)
gp.extra(gp<,int>) = a
Get/set the extra variable at the index associated with the gridpoint. An extra variable can be of any valid FISH parameter type.
Returns: a - the FISH parameter stored at the index of the gridpoint extra array
Accepts: a - the FISH parameter to store at the index of the gridpoint extra array
index - the optional index of the extra variable to set or retrieve. Can be from 1 to 128. If not specified, 1 is assumed.
gp.find
Syntax
gp = gp.find(i)
Get a pointer to the gridpoint with internally assigned ID number i. If no gridpoint exists with that ID number, then null is returned.
Returns: gp - a pointer to the gridpoint with ID number i

Arguments: i - a gridpoint ID number
gp.fix
Syntax
Vector Access
v = gp.fix(gp<,i>)
gp.fix(gp<,i>) = v
Get/set a vector indicating gridpoint fixity. A non-zero component value indicates that the degree-of-freedom is fixed in the local gridpoint system.
Returns: v - fixity condition vector or component value; non-zero indicates a fixed degree of freedom
Accepts: v - fixity condition vector or component value; non-zero indicates a fixed degree of freedom
Component Access
b = gp.fix.x(gp)
gp.fix.x(gp) = b
Get the fixity component in the x-direction in the gridpoint local coordinate system.
Returns: b - x-component fixity condition

Accepts: b - x-component fixity condition
b = gp.fix.y(gp)
gp.fix.y(gp) = b
Get the fixity component in the y-direction in the gridpoint local coordinate system.
Returns: b - y-component fixity condition

Accepts: b - y-component fixity condition
b = gp.fix.z(gp)
gp.fix.z(gp) = b
Get the fixity component in the z-direction in the gridpoint local coordinate system.
Returns: b - z-component fixity condition

Accepts: b - z-component fixity condition
gp.flow
Syntax
f = gp.flow(gp)
gp.flow(gp) = f
Get/set the unbalanced flow discharge at a gridpoint.
Returns: f - the unbalanced flow discharge

Accepts: f - the unbalanced flow discharge
gp.fluid.app
Syntax
f = gp.fluid.app(gp)
Get the total applied fluid load at a grid point.
This includes fluid load from both static and dynamic apply conditions, the zone gridpoint fix command, and the gp.fluid.load FISH intrinsic.
Returns: f - the total applied fluid load at a grid point.

Accepts: f - the total applied fluid load at a grid point.
gp.fluid.load
Syntax
f = gp.fluid.load(gp)
gp.fluid.load(gp) = f
Get/set the additional fluid load.
Flow may be applied to gridpoints with the FISH intrinsic gp.fluid.load. These loads are in addition to loads derived from the zone face apply command and other
sources of fluid load. The variables may be both changed and inspected by a FISH function. If not set by a user FISH function, these additional loads default to zero.
They are not changed by FLAC3D in any way, and indefinitely retain whatever values are set by the user.
Returns: f - the additional fluid load applied to that gridpoint

Accepts: f - the additional fluid load applied to that gridpoint
gp.fluid.modulus
Syntax
f = gp.fluid.modulus(gp)
gp.fluid.modulus(gp) = f
Get/set the gridpoint fluid bulk modulus.
Returns: f - the gridpoint fluid bulk modulus

Accepts: f - the gridpoint fluid bulk modulus
gp.fluid.modulus.confined
Syntax
f = gp.fluid.modulus.confined(gp)
gp.fluid.modulus.confined(gp) = f
Get/set the fluid flow confined modulus times nodal volume. This is used in the fast flow solution scheme.
Returns: f - fluid flow confined modulus times nodal volume

Accepts: f - fluid flow confined modulus times nodal volume
gp.fluid.tension
Syntax
f = gp.fluid.tension(gp)
gp.fluid.tension(gp) = f
Get/set the gridpoint fluid tension limit.
Returns: f - gridpoint fluid tension limit

Accepts: f - gridpoint fluid tension limit
gp.fluid.unbal
Syntax
a = gp.fluid.unbal(gp)
gp.fluid.unbal(gp) = a
Get/set the the fluid out-of-balance flow; used in the fast flow solution scheme.
Returns: f - fluid out-of-balance flow

Accepts: f - fluid out-of-balance flow
gp.fluid.vol.inv
Syntax
f = gp.fluid.vol.inv(gp)
Get the inverse of the fluid nodal volume.
Returns: f - the inverse of the fluid nodal volume

Accepts: f - the inverse of the fluid nodal volume
gp.flux
Syntax
f = gp.flux(gp)
Get the unbalanced thermal flux at a gridpoint.
Returns: f - the unbalanced thermal flux

Accepts: f - the unbalanced thermal flux
gp.force.app
Syntax
Vector Access
v = gp.force.app(gp<,i>)
Get the total applied force at a gridpoint. This includes all sources, including forces due to gravity. Returns a vector, unless an optional component argument i is
Returns: v - total applied force vector or component

Component Access
f = gp.force.app.x(gp)
Get the x-component total applied force vector.
Returns: f - x-component total applied force vector

f = gp.force.app.y(gp)
Get the y-component total applied force vector.
Returns: f - y-component total applied force vector

f = gp.force.app.z(gp)
Get the z-component total applied force vector.
Returns: f - z-component total applied force vector

gp.force.load
Syntax
Vector Access
v = gp.force.load(gp<,i>)
gp.force.load(gp<,i>) = v
Get/set the FISH applied force at a gridpoint. This force is kept separate from forces applied due to zone face apply (for example). The default value is (0,0,0).
Returns: v - FISH applied force vector or component

Accepts: v - FISH applied force vector or component
Component Access
f = gp.force.load.x(gp)
gp.force.load.x(gp) = f
Get the x-component FISH applied force vector.
Returns: f - x-component FISH applied force vector

Accepts: f - x-component FISH applied force vector
f = gp.force.load.y(gp)
gp.force.load.y(gp) = f
Get the y-component FISH applied force vector.
Returns: f - y-component FISH applied force vector

Accepts: f - y-component FISH applied force vector
f = gp.force.load.z(gp)
gp.force.load.z(gp) = f
Get the z-component FISH applied force vector.
Returns: f - z-component FISH applied force vector

Accepts: f - z-component FISH applied force vector
gp.force.unbal
Syntax
Vector Access
v = gp.force.unbal(gp<,i>)
Get the unbalanced force at a gridpoint. This includes all sources, including forces due to gravity. Returns a vector, unless an optional component argument i is
Returns: v - unbalanced force vector or component

Component Access
f = gp.force.unbal.x(gp)
Get the x-component unbalanced force vector.
Returns: f - x-component unbalanced force vector

f = gp.force.unbal.y(gp)
Get the y-component unbalanced force vector.
Returns: f - y-component unbalanced force vector

f = gp.force.unbal.z(gp)
Get the z-component unbalanced force vector.
Returns: f - z-component unbalanced force vector

gp.group
Syntax
s = gp.group(gp<,slot>)
gp.group(gp<,slot>) = s
Get/set the group name assigned to zone gridpoint gp in slot slot. Use of the group logic is described in Group.
Arguments: gp - a pointer to a zone gridpoint
gp.group.remove
Syntax
b = gp.group.remove(gp,s)
Remove the group s from zone gridpoint gp in all slots in which it is found.
Returns: b - true if the group was removed from one or more slots of the gridpoint, false if the group was not found in the gridpoint
s - the name of the group to remove
gp.head
Syntax
gp = gp.head()
Get the first zone gridpoint in the list of all gridpointsin the model. This function should be considered deprecated; it is provided mostly for backwards compatibility
with old data files. Instead, see the fish_statement_loopforeach statement and the gp.list function. See also the gp.next function.
Returns: gp - a pointer to the first zone gridpoint in the list of all gridpoints in the model
gp.id
Syntax
i = gp.id(gp)
Get the zone gridpoint ID number, which is a unique number assigned by the code when it is created.
Returns: i - the zone gridpoint ID number

gp.isgroup
Syntax
b = gp.isgroup(gp,s<,slot>)
Check if the group name s is associated with the zone gridpoint gp. By default, this checks if there is a match in any slot, but if the slot argument is specified, it will
return a match only in that slot.
Note that this function will return a match if any zone or zone face connected to the gridpoint contains that group name, as well as the gridpoint itself. Use of the group
logic is described in Group.
Returns: b - true if a match was found, false otherwise

Arguments: gp - a gridpoint pointer
s - the group name to check against
gp.link.index
Syntax
i = gp.link.index(gp)
Get the index location of this gridpoint in the first zone connected to this gridpoint. Use the four intrinsics gp.link.zone, gp.link.index, zone.link.zone, and
zone.link.index to iterate through every zone connected to a gridpoint.
Returns: i - the index of this gridpoint in the first zone connected to this gridpoint
Usage Example
The following code fragment shows how to traverse all the zones connected to a single gridpoint.
local zone = gp.link.zone(gp)

local index = gp.link.index(gp)
loop while zone # null
(Do something with that zone)
local index_copy = zone.link.index(zone,index)
zone = zone.link.zone(zone,index)
index = index_copy
end_loop
gp.link.zone
Syntax
z = gp.link.zone(gp)
Get the first zone connected to this gridpoint. Use the four intrinsics gp.link.zone, gp.link.index, zone.link.zone, and zone.link.index to iterate through every
zone connected to a gridpoint.
Returns: z - a pointer to the first zone connected to the gridpoint

Usage Example

index = index_copy
end_loop
gp.list
Syntax
l = gp.list()
Get the list of all gridpoints in the model. This is primarily used in the fish_statement_loopforeach statement.
Returns: l - a pointer to the list of all gridpoints
gp.mass.add
Syntax
Vector Access
v = gp.mass.add(gp<,i>)
gp.mass.add(gp<,i>) = v
Get/set the added mass vector for the gridpoint. This mass is added to the inertial mass of the gridpoint during equations of motion. Returns a vector, unless an optional
component argument i is supplied, in which case it returns the component value.
Returns: v - added mass vector or component

Accepts: v - added mass vector or component
Component Access
f = gp.mass.add.x(gp)
gp.mass.add.x(gp) = f
Get/set the x-component added mass vector.
Returns: f - x-component added mass vector

Accepts: f - x-component added mass vector
f = gp.mass.add.y(gp)
gp.mass.add.y(gp) = f
Get/set the y-component added mass vector.
Returns: f - y-component added mass vector

Accepts: f - y-component added mass vector
f = gp.mass.add.z(gp)
gp.mass.add.z(gp) = f
Get/set the z-component added mass vector.
Returns: f - z-component added mass vector

Accepts: f - z-component added mass vector
gp.mass.gravity
Syntax
f = gp.mass.gravity(gp)
Get the gravitational mass. This is determined by the density and volume of the zones to which the gridpoint is connected. The gravitational mass is used to determine
forces due to gravity. In dynamic mode, it is used in the equations of motion calculation. See also gp.mass.inertial.
Returns: f - the gridpoint gravitational mass

Accepts: f - the gridpoint gravitational mass
gp.mass.inertial
Syntax
f = gp.mass.inertial(gp)
Get the gridpoint inertial mass.
The inertial mass is calculated during the equations-of-motion calculation for a gridpoint. In static (default) mode, it is calculated from the accumulated gridpoint
stiffness, as described in Mechanical Timestep Determination for Numerical Stability. In dynamic mode, it is assigned the value of the gravitational mass. To adjust the
inertial mass, see the gp.mass.add intrinsic.
Returns: f - the inertial mass of the gridpoint

[DR: please confirm link to mechtimestepdetermination above is going where wanted]
gp.maxid
Syntax
i = gp.maxid
Get the maximum ID number assigned to any gridpoint in this model. The next gridpoint created will be assigned this value plus one.
Returns: i - maximum ID number of any gridpoint in the model
gp.near
Syntax
gp = gp.near(v)
Get the gridpoint nearest v; will return null if there are no gridpoints in the model. Excludes gridpoints only connected to mechanically null zones.
Returns: gp - the pointer to the gridpoint closest to v

gp.near.all
Syntax
gp = gp.near.all(v)
Get the gridpoint nearest v; will return null if there are no gridpoints in the model. Will include all gridpoints, including those only connected to mechanically null
zones.
Returns: gp - the pointer to the gridpoint closest to v

gp.near.live
Syntax
gp = gp.near.live(v,bmech,bfluid,btherm,s)
Get the gridpoint nearest point v. Which gridpoints are to be considered is controlled by the four arguments following. If mech, fluid, or therm is true, then gridpoints
connected to zones containing non-null constitutive models in those processes are considered. The third string argument s must be either and or or, indicating whether
the models are all required or if any one of them is sufficient.
Returns: gp - the pointer to the gridpoint matching the criteria nearest v

bmech - indicates if mechanically non-null zones are to be considered
bfluid - indicates if fluid non-null zones are to be considered
btherm - indicates if thermal non-null zones are to be considered
s - must be either and or or, indicates whether one or all of the non-null models must be present
gp.next
Syntax
gpnext = gp.next(gp)
Get the next gridpoint after gp in the list of all gridpoints in the model. Will return null if no more gridpoints follow.
This function should be considered deprecated; it is provided mostly for backwards compatibility with old data files. Instead, see the fish_statement_loopforeach
statement and the gp.list function. See also the gp.head function.
Returns: gpnext - the next gridpoint in the list or null

Arguments: gp - a pointer to a gridpoint
gp.num
Syntax
i = gp.num
Get the total number of gridpoints in the model.
Returns: i - the total number of gridpoints in the model
gp.pos
Syntax
Vector Access
v = gp.pos(gp<,i>)
gp.pos(gp<,i>) = v
Get/set the position of the gridpoint. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.
Note that changing position vectors during cycling will not update geometry-derived values calculated during an update. See the intrinsic zone.do.update.

Component Access
f = gp.pos.x(gp)
gp.pos.x(gp) = f
Get/set the x-component position vector.

Accepts: f - x-component position vector
f = gp.pos.y(gp)
gp.pos.y(gp) = f
Get/set the y-component position vector.

Accepts: f - y-component position vector
f = gp.pos.z(gp)
gp.pos.z(gp) = f
Get/set the z-component position vector.

Accepts: f - z-component position vector
gp.pp
Syntax
f = gp.pp(gp)
gp.pp(gp<,i>) = f
Get/set the gridpoint pore pressure.
When the function is used to set the fluid pore pressure and the optional argument i is set to a nonzero value, in addition to modifying the gridpoint pore pressure, the
function will update the accumulated pore pressure increment since the last mechanical step. The fluid flow calculation must be active for this option to be performed.
To achieve the same result as the command zone gridpoint fix pore-pressure f, the FISH intrinsics gp.pp.fix and gp.pp must be used together.
Returns: f - the current gridpoint pore pressure

Accepts: f - the new gridpoint pore pressure
i - if nonzero during assignment, indicates that coupling will be activated based on the change in pore pressure
gp.pp.fix
Syntax
b = gp.pp.fix(gp)
gp.pp.fix(gp) = b
Get/set the flag indicating that the pore pressure in the gridpoint is fixed.
Returns: b - true if the gridpoint pore-pressure is fixed

Accepts: b - true if the gridpoint pore-pressure will be fixed
gp.ratio
Syntax
f = gp.ratio(gp)
Get the local gridpoint mechanical convergence ratio. This is the ratio of unbalanced force to force applied to the gridpoint.
Returns: f - local gridpoint mechanical convergence ratio

gp.ratio.target
Syntax
f = gp.ratio.target(gp)
gp.ratio.target(gp) = f
Get/set the target local gridpoint mechanical convergence ratio. The default value is 1e-4. A local force ratio (gp.ratio) below this value is considered converged. See
gp.convergence.
Returns: f - gridpoint target mechanical convergence ratio

Accepts: f - gridpoint target mechanical convergence ratio
gp.sat
Syntax
f = gp.sat(gp)
gp.sat(gp) = f
Get/set the fluid saturation. This should be a value between 0.0 and 1.0. At 1.0, the gridpoint will be considered fully saturated and will begin to create pore pressure.
Returns: f - the current gridpoint saturation

Accepts: f - the new gridpoint saturation
gp.state.restore
Syntax
i = gp.state.restore(gp)
Restores all gridpoint state information from the currently open FISH file. See the file.open and file.read intrinsics.
Returns: i - returns 0 upon success; otherwise, returns a FISH file error code
gp.state.save
Syntax
i = gp.state.save(gp)
Saves all gridpoint state information to the currently open FISH file. See the file.open and file.write intrinsics.
gp.stiff
Syntax
f = gp.stiff(gp)
Get the accumulated gridpoint effective stiffness.
This value is calculated during an update, based on the stiffness of all zones it is connected to, as well as other model elements such as interfaces or attach conditions.
The effective stiffness value is used during static (default) mode to determine the gridpoint inertial mass, as described in Mechanical Timestep Determination for
Numerical Stability.
In dynamic mode, the effective stiffness is used to determine the critical timestep.
Returns: f - the effective gridpoint stiffness

[DR: please confirm link to mechtimestepdetermination above is going where wanted]
gp.temp
Syntax
f = gp.temp(gp)
gp.temp(gp) = f
Get/set the current gridpoint temperature.
Returns: f - the current gridpoint temperature

Accepts: f - the current gridpoint temperature
gp.temp.app
Syntax
f = gp.temp.app(gp)
Get the total applied thermal flux at a grid point.
This includes thermal flux from both static and dynamic apply conditions, the zone gridpoint fix command, and the gp.temp.source FISH intrinsic.
Returns: f - the total applied thermal flux at a grid point.

Accepts: f - the total applied thermal flux at a grid point.
gp.temp.change
Syntax
f = gp.temp.change(gp)
gp.temp.change(gp) = f
Get/set the temperature change of the grid point since the last mechanical cycle. If changed, the temperature of the grid point will be adjusted to match the difference.
For example, if the temperature is 10 and the temp change is 0.1 (which implies that previous temperature is 9.9), then if the value was set to 1.0 the temp change would
be 1.0 and the grid point temperature would be 10.9.
The effect of the accumulated temperature change will be seen in the model after the next mechanical step.
Returns: f - the amount of temperature change since the last thermal/mechanical coupling
Accepts: f - the amount of temperature change since the last thermal/mechanical coupling
gp.temp.fix
Syntax
b = gp.temp.fix(gp)
gp.temp.fix(gp) = b
Get/set the flag indicating that temperature in this gridpoint is fixed.
Returns: b - true if the temperature in this gridpoint is fixed

Accepts: b - true if the temperature in this gridpoint is fixed
gp.temp.source
Syntax
f = gp.temp.source(gp)
gp.temp.source(gp) = f
Get/set the applied FISH temperature source at a gridpoint.
This source is in addition to loads derived from the zone face apply command and other sources of thermal energy. Both variables may be changed and inspected by
a FISH function. If not set by a user FISH function, this source defaults to zero. It is not changed by FLAC3D in any way and will indefinitely retain whatever value is
set by the user.
Returns: f - the FISH thermal source at a gridpoint

Accepts: f - the FISH thermal source at a gridpoint
gp.typeid
Syntax
i = gp.typeid()
Get an identifier that uniquely determines the type of object. For gridpoints, this will always return 1283546092.
This can be used with the type.pointer.id intrinsic to identify the object type referred to by a pointer.
gp.vel
Syntax
Vector Access
v = gp.vel(gp<,i>)
gp.vel(gp<,i>) = v
Get/set the velocity vector for the gridpoint. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.
Returns: v - velocity vector or component

Accepts: v - velocity vector or component
Component Access
f = gp.vel.x(gp)
gp.vel.x(gp) = f
Get/set the x-component velocity vector.
Returns: f - x-component velocity vector

Accepts: f - x-component velocity vector
f = gp.vel.y(gp)
gp.vel.y(gp) = f
Get/set the y-component velocity vector.
Returns: f - y-component velocity vector

Accepts: f - y-component velocity vector
f = gp.vel.z(gp)
gp.vel.z(gp) = f
Get/set the z-component velocity vector.
Returns: f - z-component velocity vector

Accepts: f - z-component velocity vector
interface.elem.area
Syntax
f = interface.elem.area(ie)
Get the area of the interface element.
Returns: f - interface element area

Arguments: ie - interface element pointer
interface.elem.extra
Syntax
a = interface.elem.extra(ie<,i>)
interface.elem.extra(ie<,i>) = a
Get/set the value stored in the ith extra variable array of interface element ie.
Returns: a - value stored in extra variable slot i for interface element ie

Accepts: a - value to store in extra variable slot for interface ie
Arguments: ie - a pointer to the interface element
interface.elem.head
Syntax
ie = interface.elem.head(it)
Following sentence doesn't make sense. Get the first interface element all interface elements in the specific interface element. This function should be considered
deprecated; it is provided mostly for backwards compatibility with old data files. Instead, see the fish_statement_loopforeach statement and the interface.elem.list
function. See also the interface.elem.next function.
Returns: ie - interface element pointer

Arguments: it - interface pointer
interface.elem.host.face
Syntax
i = interface.elem.host.face(ie)
Get the face ID number (1-6) to which the interface element is attached.
Returns: i - face ID number (1-6)

interface.elem.host.zone
Syntax
z = interface.elem.host.zone(ie)
Get the address of the zone to which the interface element is attached.

interface.elem.id
Syntax
i = interface.elem.id(ie)
Get the ID number of the given interface element.
interface.elem.join
Syntax
ie1 = interface.elem.join(ie,i)
Get the pointer to the adjacent interface element joined across edge i, where i = 1, 2, or 3.
Returns: ie1 - interface element pointer

i - edge number (1-3)
interface.elem.list
Syntax
l = interface.elem.list(it)
Get the list of all interface elements in the model. This is primarily used in the fish_statement_loopforeach statement.
Returns: l - a pointer to the list of all interface elements

interface.elem.next
Syntax
ienext = interface.elem.next(ie)
Get the next interface element after ie in the list of all interface elements in the model. Will return null if no more interface elements follow. This function should be
considered deprecated; it is provided mostly for backwards compatibility with old data files. Instead, see the fish_statement_loopforeach statement and the
interface.elem.list function. See also the interface.elem.head function.
Returns: ienext - interface element pointer

interface.elem.normal
Syntax
Vector Access
v = interface.elem.normal(ie<,i>)
Get the normal vector for the interface element. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.
Returns: v - normal vector or component

Component Access
f = interface.elem.normal.x(ie)
Get the x-component for the interface element.
Returns: f - x-component normal vector

Accepts: f - x-component normal vector
f = interface.elem.normal.y(ie)
Get the y-component for the interface element.
Returns: f - y-component normal vector

Accepts: f - y-component normal vector
f = interface.elem.normal.z(ie)
Get the z-component for the interface element.
Returns: f - z-component normal vector

Accepts: f - z-component normal vector
interface.elem.vertex
Syntax
in = interface.elem.vertex(ie,i)
Get the pointer of the vertex associated with the interface element where i = 1, 2, or 3.
Returns: in - interface node pointer

i - vertex number (1-3)
interface.find
Syntax
it = interface.find(i)
Get the interface with internally assigned ID number i.
Returns: it - interface pointer

Arguments: i - interface ID number
interface.head
Syntax
it = interface.head
Get the first interface in the list of all interfaces in the model. This function should be considered deprecated; it is provided mostly for backwards compatibility with old
data files. Instead, see the fish_statement_loopforeach statement and the interface.list function. See also the interface.next function.
Returns: it - interface pointer
interface.id
Syntax
i = interface.id(it)
Get the interface ID number, a unique number assigned by the code when it is created.
Returns: i - interface ID number

interface.list
Syntax
l = interface.list
Get the list of all interfaces in the model. This is primarily used in the fish_statement_loopforeach statement.
Returns: l - a pointer to the list of all interfaces
interface.name
Syntax
s = interface.name(it)
Get the interface with the assigned name s.
Returns: s - interface name

interface.next
Syntax
itnext = interface.next(it)
Get the next interface after it in the list of all interfaces in the model. Will return null if no more interfaces follow. This function should be considered deprecated; it is
provided mostly for backwards compatibility with old data files. Instead, see the fish_statement_loopforeach statement and the interface.list function. See also the
interface.head function.
Returns: itnext - the next interface in the list, or null

Arguments: it - a pointer to an interface
interface.node.area
Syntax
f = interface.node.area(in)
Get the characteristic area of the node (only valid after cycling).
Returns: f - characteristic area of the node

Arguments: in - interface node pointer
interface.node.disp
Syntax
Vector Access
v = interface.node.disp(in<,i>)
Get the displacement vector for the interface node. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.

Component Access
f = interface.node.disp.x(in)
Get the x-component displacement vector of the element node.

f = interface.node.disp.y(in)
interface.node.disp.y(in) = f
Get the y-component displacement vector of the element node.

f = interface.node.disp.z(in)
interface.node.disp.z(in) = f
Get the z-component displacement vector of the element node.

interface.node.disp.shear
Syntax
v = interface.node.disp.shear(in<,i>)
interface.node.disp.shear(in<,i>) = v
Get/set the relative shear displacement vector for the interface node. Returns a vector, unless an optional component argument i is supplied, in which case it returns the
component value.
Returns: v - relative shear displacement vector or component

Accepts: v - relative shear displacement vector or component
Component Access
f = interface.node.disp.shear.x(in)
interface.node.disp.shear.x(in) = f
Get/set the x-component relative shear displacement vector of the element node.
Returns: f - x-component relative shear displacement vector
Accepts: f - x-component relative shear displacement vector

f = interface.node.disp.shear.y(in)
interface.node.disp.shear.y(in) = f
Get/set the y-component relative shear displacement vector of the element node.
Returns: f - y-component relative shear displacement vector

Accepts: f - y-component relative shear displacement vector
f = interface.node.disp.shear.z(in)
interface.node.disp.shear.z(in) = f
Get/set the z-component relative shear displacement vector of the element node.
Returns: f - z-component relative shear displacement vector

Accepts: f - z-component relative shear displacement vector
interface.node.extra
Syntax
a = interface.node.extra(in<,i>)
interface.node.extra(in<,i>) = a
Get/set the value stored in the ith extra variable array of interface node in.
Returns: a - value stored in extra variable slot i for interface node in

Accepts: a - value to store in extra variable slot for interface in
Arguments: in - a pointer to the interface node
interface.node.find
Syntax
in = interface.node.find(it,i)
Get the interface node with the given ID number.
Returns: it - pointer to an interface.
i - ID number of node to find.

interface.node.head
Syntax
ie = interface.node.head(it)
Get the first interface node in the list of all interface nodes in the specified interface element. This function should be considered deprecated; it is provided mostly for
backwards compatibility with old data files. Instead, see the fish_statement_loopforeach statement and the interface.node.list function. See also the
interface.node.next function.
Returns: in - interface node pointer

zone.face.area
Syntax
Vector Access
f = zone.face.area(z,iside)
Get the area of the face.
Returns: f - area of the face

iside - side of the zone indicating the face, from 1 to 6
interface.node.host.face
Syntax
i = interface.node.host.face(in)
Get the face ID (1-6) of the zone face to which the node is attached.
Returns: i - face ID (1-6)

interface.node.host.weight
Syntax
f = interface.node.host.weight(in,i)
Get the weighting factor for vertex i (1-4) of the zone face to which the interface node is attached.
Returns: f - weighting factor

interface.node.host.zone
Syntax
z = interface.node.host.zone(in)
Get the zone pointer to which the node is attached.

interface.node.id
Syntax
i = interface.node.id(in)
Get the ID number of the given interface node.
interface.node.list
Syntax
l = interface.node.list(it)
Get the list of all interface nodes in the model. This is primarily used in the fish_statement_loopforeach statement.
Returns: l - a pointer to the list of all interface node

zone.face.group.remove
Syntax
i = zone.face.group.remove(z,iside,s)
Removes the group name s from the face identified by z and iside. The return value will be 0 if that group had not been assigned to that face. It will remove the group
name from any slot it is found in.
Returns: i - 0 if the group is not found, nonzero otherwise

Arguments: z - a zone pointer
str - the name of the group to remove
interface.node.next
Syntax
innext = interface.node.next(in)
Get the next interface node after in in the list of all interface nodes in the model. Will return null if no more interface nodes follow. This function should be considered
deprecated; it is provided mostly for backwards compatibility with old data files. Instead, see the fish_statement_loopforeach statement and the interface.node.list
function. See also the interface.node.head function.
Returns: innext - interface node pointer

interface.node.normal
Syntax
Vector Access
v = interface.node.normal(in<,i>)
Get the normal vector for the interface node, which is an area weighted average of the interface elements it is connected to. Returns a vector, unless an optional
component argument i is supplied, in which case it returns the component value.
Returns: v - normal vector or component

Arguments: in - interface element pointer
Component Access
f = interface.node.normal.x(in)
Get the x-component for the interface normal.
Returns: f - x-component normal vector

Accepts: f - x-component normal vector
Arguments: in - interface element pointer
f = interface.node.normal.y(in)
Get the y-component for the interface node.
Returns: f - y-component normal vector

Accepts: f - y-component normal vector
f = interface.node.normal.z(in)
Get the z-component for the interface node.
Returns: f - z-component normal vector

Accepts: f - z-component normal vector
interface.node.penetration
Syntax
f = interface.node.penetration(in)
Get interface node penetration with the contacting zone face (only valid after cycling). A value ≤ 0 is returned if there is no contact.
Returns: f - value of penetration

interface.node.position
Syntax
Vector Access
v = interface.node.pos(in<,i>)
interface.node.pos(in<,i>) = v
Get/set the position vector for the interface node. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.

Component Access
f = interface.node.pos.x(in)
interface.node.pos.x(in) = f
Get/set the x-component position vector of the interface node.

Accepts: f - x-component position vector
f = interface.node.pos.y(in)
interface.node.pos.y(in) = f
Get/set the y-component position vector of the interface node.

Accepts: f - y-component position vector
f = interface.node.pos.z(in)
interface.node.pos.z(in) = f
Get/set the z-component position vector of the interface node.

Accepts: f - z-component position vector
interface.node.pp
Syntax
f = interface.node.pp(in)
Get the pore pressure of the node (only valid after cycling).
Returns: f - pore pressure

interface.node.prop
Syntax
a = interface.node.prop(in,s)
interface.node.prop(in,s) = a
Get/set the property identified by s of the interface node.
Returns: a - the value of property s in the zone

Accepts: a - the value assigned to property s in the zone. Must match the type expected by that property.
s - the name of a property
interface.node.slip
Syntax
i = interface.node.slip(in)
interface.node.slip(in) = i
Get/set the slip status (0-2) of the interface node: 0 is for shear-now; 1 is for shear-past; and 2 is for no shear failure now or in the past.
Returns: i - slip status number

Accepts: in - interface node pointer
interface.node.stress.normal
Syntax
f = interface.node.stress.normal(in)
Get the normal stress at the node.
Returns: f - normal stress

interface.node.stress.normal.add
Syntax
f = interface.node.stress.normal.add(in)
interface.node.stress.normal.add(in) = f
Get/set the additional normal stress. The normal stress used in the calculation is equal to the penetration × stiffness + additional normal stress. This function can be used
to initialize (or pre-stress) the interface normal stress or to counteract the stresses induced by interpenetration.
Returns: f - additional normal stress

Accepts: f - additional normal stress
interface.node.stress.shear
Syntax
Vector Access
v = interface.node.stress.shear(in<,i>)
interface.node.stress.shear(in<,i>) = v
Get/set the shear stress vector for the interface node. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component
value.
Returns: v - shear stress vector or component

Accepts: v - shear stress vector or component
Component Access
f = interface.node.stress.shear.x(in)
interface.node.stress.shear.x(in) = f
Get/set the x-component shear stress vector of the element node.
Returns: f - x-component shear stress vector

Accepts: f - x-component shear stress vector
f = interface.node.stress.shear.y(in)
interface.node.stress.shear.y(in) = f
Get/set the y-component shear stress vector of the element node.
Returns: f - y-component shear stress vector

Accepts: f - y-component shear stress vector
f = interface.node.stress.shear.z(in)
interface.node.stress.shear.z(in) = f
Get/set the z-component shear stress vector of the element node.
Returns: f - z-component shear stress vector

Accepts: f - z-component shear stress vector
interface.node.target.face
Syntax
i = interface.node.target.face(in)
Get the face ID (1-6) of the zone face in contact with the node.
Returns: i - face ID (1-6)

interface.node.target.weight
Syntax
f = interface.node.target.weight(in,i)
Get the weighting factor for vertex i (1-4) of the zone face in contact with the interface node.
Returns: f - weighting factor

interface.node.target.zone
Syntax
z = interface.node.target.zone(in)
Get the zone pointer in contact with the node.

interface.node.tol
Syntax
f = interface.node.tol(in)
interface.node.tol(in) = f
Get/set the interface node contact tolerance, a dimensionless measure of how close a face has to be to register a contact
Returns: f - value of tolerance

Accepts: f - value of tolerance
interface.node.vel
Syntax
Vector Access
v = interface.node.vel(in<,i>)
interface.node.vel(in<,i>) = v
Get/set the velocity vector for the interface node. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.
Returns: v - velocity vector or component

Accepts: v - velocity vector or component
Component Access
f = interface.node.vel.x(in)
interface.node.vel.x(in) = f
Get/set the x-component velocity vector of the element node.
Returns: f - x-component velocity vector

Accepts: f - x-component velocity vector
f = interface.node.vel.y(in)
interface.node.vel.y(in) = f
Get/set the y-component velocity vector of the element node.
Returns: f - y-component velocity vector

Accepts: f - y-component velocity vector
f = interface.node.vel.z(in)
interface.node.vel.z(in) = f
Get/set the z-component velocity vector of the element node.
Returns: f - z-component velocity vector

Accepts: f - z-component velocity vector
zone.aspect
Syntax
f = zone.aspect(z)
Get the measure of a zone's aspect ratio. Values near zero indicate a zone with a large aspect ratio. This is defined as the minimum ratio of smallest to largest edge
length among adjacent edges of a zone.
Returns: f - the zone aspect ratio

zone.code
Syntax
i = zone.code(z)
Get the zone code. This is an integer that indicates which of the five currently available zone types z is.
Returns: i - zone code (0 = brick, 1 = wedge, 2 = pyramid, 3 = dbrick, 4 = tetra)

zone.condition
Syntax
f = zone.condition(z<,i>)
Get the zone condition number. This is a general value indicating how geometrically well formed the zone is. A value of 1.0 indicates a perfect cubical zone. A value of
0.0 indicates an unusable zone.
Returns: f - zone condition value

i - which condition type.
if i = 0 (default), the minimum measurement of aspect ratio, volume ratio and orthogonality;
if i = 1, the measurement of aspect ratio, zone.condition (z, 1) = zone.aspect (z);
if i = 2, the measurement of volume ratio;
if i = 3, the measurement of orthogonality, zone.condition (z, 3) = zone.ortho (z).
See zone geometry-test for more explanations.
zone.containing
Syntax
z = zone.containing(v<,start>)
Get the zone that encompasses the point v. The optional value start can be given to seed the search with the last zone found at that point. This zone is checked first and,
if valid, will be the only zone check, speeding up the check.
Returns: z - the pointer to the zone containing that point, or null if no zone is found
Arguments: v - the point in space being checked
start - optional starting zone to check first
zone.copy
Syntax
i = zone.copy(source,dest)
Copies the zone state information from the source zone to the destination zone. The return value is always 0.
Returns: i = 0
Arguments: source = pointer to the source zone, the zone from which state information will be copied
dest = pointer to the destination zone, the zone to which state information will be copied
zone.create.interface.elem
Syntax
i = zone.create.interface.elem(z,iside,sname)
create new interface elements attached to a zone face.
Returns: i - the number of elements created. Two triangular elements are created on a quadrilateral face. Will return 0 if an element already exists on that face.
Arguments: z - the zone on which the interface will be created
iside - the side of the zone on which the interface will be created
sname - the name of the interface to which the element will be added. If that interface does not exist, one will be created.
zone.create.ratio
Syntax
f = zone.create.ratio(fr,index,isize)
Get a value calculated by a geometric progression, given a ratio, an index, and a size. This is the same ratio as is used in the zone create logic, the extrude, and
building-blocks. This divides the interval from 0.0 to 1.0 into size sections, each of which is ratio times the size of the previous one.
Returns: f - the fraction from 0.0 to 1.0 of the geometric progression from 0 to size at index of the given ratio
Arguments: fr - the geometric ratio to use for the progression. Each interval will be ratio times larger than the previous.
index - the index (from 0 to size) of the location in the progression to calculate
isize - the total number of intervals involved
zone.creep.time.total
Syntax
f = zone.creep.time.total()
zone.creep.time.total() = f
Get/set the total accumulated zone module creep time. This accumulates the timesteps of every cycle the zone creep module is active.
Returns: f - the total accumulated zone module creep time

Accepts: f - the total accumulated zone module creep time
zone.creep.timestep
Syntax
f = zone.creep.timestep()
zone.creep.timestep() = f
Get/set the timestep used by the zone creep module when it is active. This may not be the timestep used, as other active modules may require a smaller timestep.
Returns: f - the current zone creep module timestep

Accepts: f - sets the current zone creep module timestep. This does not change any active automatic timestep calculations that may be active.
zone.density
Syntax
f = zone.density(z)
zone.density(z) = f
Get/set the density of the zone. Note that updates to the gravitational and inertial mass of connected gridpoints may not occur until an update occurs. This normally
happens at the start of cycling and at the geometry update interval in large-strain mode. The zone.do.update intrinsic can be used to force an udpate at the start of the
next cycle.
Returns: f - the current zone density

Accepts: f - the current zone density
zone.dynamic.mul
Syntax
f = zone.dynamic.mul(z)
Get the multiple calculated for that zone when dynamic multistepping is active. See Dynamic Multi-stepping for further discussion.
Returns: f - the dynamic multistepping interval

Arguments: z - a pointer to a zone
zone.dynamic.time.total
Syntax
f = zone.dynamic.time.total(z)
Get/set the total accumulated zone module dynamic time. This accumulates the timesteps of every cycle the zone dynamic module is active.
Returns: f - the total accumulated zone module dynamic time

Accepts: f - the total accumulated zone module dynamic time
zone.dynamic.timestep
Syntax
f = zone.dynamic.timestep()
zone.dynamic.timestep() = f
Get/set the timestep used by the zone dynamic module when it is active. This may not be the timestep used, as other active modules may require a smaller timestep.
Returns: f - the current zone dynamic module timestep

Accepts: f - sets the current zone dynamic module timestep. This does not change any active automatic timestep calculations that may be active.
zone.extra
Syntax
a = zone.extra(z<,i>)
zone.extra(z<,i>) = a
Get/sets the value stored in the ith extra variable array of zone z.
Returns: a - value stored in extra variable slot i for zone z

Accepts: a - value to store in extra variable slot for zone z
Arguments: z - a pointer to the zone
zone.face.extra
Syntax
a = zone.face.extra(z,iside,index)
zone.face.extra(z,iside,index) = a
Get/set the value of the index in the extra variable array associated with the zone face z and iside.
Returns: a - the FISH value stored at that index

Accepts: a - the FISH value to store at that index
iside - the side index of the zone, from 1 to 6
index - the extra variable array index, from 1 to 128
zone.face.find
Syntax
i = zone.face.find(z,gp1,gp2,gp3)
Get the face index of zone z that contains the three gridpoints gp1, gp2, and gp3. Each gridpoint may be specified by pointer or by ID number. If no face is found, −1 is
returned.
Returns: i - the index of the matching face, from 1 to 6, or -1 if no match is found

gp1 - either a pointer to a gridpoint or a gridpoint ID number
zone.face.find.normal
Syntax
i = zone.face.find.normal(z,v)
Get the face index of zone z whose outward-facing normal is closest to the direction of v. Will return a value from 1 to 6.
Returns: i - the index of the face whose outward normal is closest to the direction of v, from 1 to 6
v - a vector indicating a direction. This need not be of unit length.
zone.face.gp
Syntax
gp = zone.face.gp(z,iside,ivertex)
Get a pointer to a gridpoint on face given by zone z and iside, and the face ivertex, as described in Orientation of Nodes and Faces within a Zone.
Returns: gp - a pointer to a gridpoint

iside - the zone side index, from 1 to 6
ivertex - the face vertex index, from 1 to 4
zone.face.group
Syntax
s = zone.face.group(z,iside<,slot>)
zone.face.group(z,iside<,slot>) = s
Get/set the group name associated with the face identified by z and iside in slot slot. On set, the slot Default is assumed if not provided. On get, the return string encodes
all group/slot assignments present on the face, in the format "SlotName=GroupName,SlotName=GroupName". Use of the group logic is described in Group.
Returns: s - the group name in the slot, or "None" if no group was assigned
Accepts: s - the group name to assign to the slot; if "None" is used, the group name will be cleared
slot - an optional slot specification; if not given, the slot Default is assumed on set, on get all group/slot assignments are returned
zone.face.isgroup
Syntax
b = zone.face.isgroup(z,iside,s<,slot>)
Check if the group name s is associated with the zone face indicated by z and iside. By default, will check if there is a match in any slot. If the slot argument is
specified, it will return a match only in that slot.
Note that this function will return a match if any zone attached to the face contains that group name, as well as the face itself. Use of the group logic is described in
Group.
Returns: b - true if a match was found, false otherwise

s - the group name to check against
zone.face.normal
Syntax
Vector Access
v = zone.face.normal(z,iside<,i>)
Get the normal to the face, facing outward from zone z.
Returns: v - zone face normal vector or component

Component Access
f = zone.face.normal.x(z,iside)
Get the x-component of the normal to the face, facing outward from zone z.
Returns: f - x-component of the zone face normal vector

f = zone.face.normal.y(z,iside)
Get the y-component of the normal to the face, facing outward from zone z.
Returns: f - y-component of the zone face normal vector

f = zone.face.normal.z(z,iside)
Get the z-component of the normal to the face, facing outward from zone z.
Returns: f - z-component of the zone face normal vector

zone.face.pos
Syntax
Vector Access
v = zone.face.pos(z,iside<,i>)
Get the position of the face, defined as the centroid of its grid points.
Returns: v - the face position or its component

Component Access
f = zone.face.pos.x(z,iside)
Get the x-component of the position of the face centroid.
Returns: f - x-component of the face position

f = zone.face.pos.y(z,iside)
Get the y-component of the face of the face centroid.
Returns: f - y-component of the face position

f = zone.face.pos.z(z,iside)
Get the z-component of the face of the face centroid.
Returns: f - z-component of the face position

zone.face.size
Syntax
i = zone.face.size(z,iside)
Get the number of unique face vertices. A quadrilateral face will return 4; a triangular face will return 3. A number less than three indicates that this is a degenerate face
that is not valid.
Returns: i - the number of unique vertices on the face

zone.field.component
Syntax
s = zone.field.component
zone.field.component = s
Get/set the scalar value retrieved from a name that returns a vector. If the type is not a vector, this value is ignored. Valid strings are x, y, z, and magnitude.
Returns: s - the current component setting

Accepts: s - the new component setting. Keyword matching rules apply. If no match is found an error will occur.
zone.field.extra
Syntax
i = zone.field.extra
zone.field.extra = i
Get/set the index used to retrieve extra variables. By default, this is 1.
Returns: i - the current extra variable index

Accepts: i - the new extra variable index to use, from 1 to 128
zone.field.get
Syntax
f = zone.field.get(v<,fdef>)
Get data from the model at the location specified by v3+. The optional argument fdef specifies which value to return if v is not inside any zone in the model. By default,
fdef = 0.0.
Returns: f - the scalar data value at location v

Arguments: v - the location in space to query
fdef - the return value to use if no zone is found at that location
zone.field.get.gp
Syntax
f = zone.field.get.gp(gp,z)
Get data directly from the gridpoint gp and zone z. Note that one of the two values may not be required, depending on the type of data queried and the extrapolation
method specified.
Returns: f - the scalar value specified at gridpoint gp and/or zone z

Arguments: gp - a pointer to a gridpoint
z - a pointer to a zone
zone.field.gravity
Syntax
b = zone.field.gravity
zone.field.gravity = b
Get/set gravitational force setting. If true, then gravitational forces are included in applied forces. If false, (the default) they are not.
Returns: b - the current gravitational force setting

Accepts: b - the new gravitational force setting
zone.field.hide.fluidnull
Syntax
b = zone.field.hide.fluidnull
zone.field.hide.fluidnull = b
Get/set the null fluid constitutive model setting. If true, then zones with a null fluid constitutive model are ignored in computing gridpoint values from zone data. The
default setting is false.
Returns: b - the null fluid constitutive model setting

Accepts: b - the null fluid constitutive model setting
zone.field.hide.mechnull
Syntax
b = zone.field.hide.mechnull
zone.field.hide.mechnull = b
Get/set the null mechanical constitutive model setting. If true, then zones with a null mechanical constitutive model are ignored in computing gridpoint values from
zone data. The default setting is true.
Returns: b - the null mechanical constitutive model setting

Accepts: b - the null mechanical constitutive model setting
zone.field.hide.thermnull
Syntax
b = zone.field.hide.thermnull
zone.field.hide.thermnull = b
Get/set the null thermal constitutive model setting. If true, then zones with a null thermal constitutive model are ignored in computing gridpoint values from zone data.
The default setting is false.
Returns: b - the null thermal constitutive model setting

Accepts: b - the null thermal constitutive model setting
zone.field.index
Syntax
i = zone.field.index
zone.field.index = i
Get/set the the index number of the data type name that should be queried. This index may be useful for efficient internal processing, but the values may change
between releases of FLAC3D. It is recommended that you determine the index value by using the zone.field.name intrinsic.
Returns: i - the data type index number

Accepts: i - the data type index number
zone.field.init
Syntax
i = zone.field.init
Initializes the zone field data system for the current method and the current data type. Results of calculations are stored internally where possible to minimize the
calculations caused by multiple calls to zone.field.get.
Note that any change to the model during this period will cause invalid results to be obtained.
Returns: i - always returns integer 0
zone.field.log
Syntax
b = zone.field.log
zone.field.log = b
Get/set the logarithmic setting. If true, then the base-ten log of the absolute value of all scalar values are returned. The default is false.
Returns: b - the logarithmic setting

Accepts: b - the logarithmic setting
zone.field.method.index
Syntax
i = zone.field.method.index
zone.field.method.index = i
Get/set the index number of the extrapolation method used for zone-based variables.
This has no effect on gridpoint-based variables. The indices corresponding to names are 0 = constant, 1 = volume-weighted averaging, 2 = inverse-distance-weighted
averaging, and 3 = polynomial fit. See zone.field.method.name. The default value is 0.
Returns: i - the extrapolation method index

Accepts: i - the extrapolation method index
zone.field.method.name
Syntax
s = zone.field.method.name
zone.field.method.name = s
Get/set the method used for extrapolation of zone-based variables.
This has no effect on gridpoint-based variables.
The available names are constant, average, inverse-distance-weighting, and polynomial. The default value is constant.
The extrapolation methods are used to determine values at the gridpoints of the zone. Then a weighting function is used to determine how values vary inside the zone.
Returns: s - the zone field extrapolation method name

Accepts: s - the zone field extrapolation method name. Keyword matching rules are used on assignment. If no match is found, an error will occur.
zone.field.name
Syntax
s = zone.field.name
zone.field.name = s
Get/set the name of the value being retrieved from zones. A list of all available names can be seen in the Zone Field Data Names table.
Returns: s - the name of the value being retrieved

Accepts: s - the name of the value to be retrieved. Keyword matching rules apply. If no match is found, an error will occur.
zone.field.power
Syntax
f = zone.field.power
zone.field.power = f
Get/set the power exponent used for the inverse-distance-weighting method of extrapolation. The default is 3.0.
Returns: f - the power exponent used with inverse distance weighting

Accepts: f - the power exponent to use with inverse distance weighting
zone.field.prop
Syntax
s = zone.field.prop
zone.field.prop = s
Get/set the name of the property to retrieve when the zone.field.name has been set to property, property-fluid, or property-thermal.
Returns: s - the name of the property to use

Accepts: s - the name of the property to use
zone.field.quantity
Syntax
s = zone.field.quantity
zone.field.quantity = s
Get/set the scalar quantity to retrieve when the value being obtained is a tensor. This value is ignored if the type is not a tensor. The available quantity names are listed
in the following table.
Quantity Name Description

intermediate intermediate principal stress
maximum the maximum (most positive) value of principal stress (note that compressive stresses are negative in FLAC3D)
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 compressive stresses are negative in FLAC3D)
norm The norm of the strain rate; see the equations below
octohedral octahedral stress; see the equations below
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 equations below
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
Returns: s - the name of the scalar quantity to retrieve from the tensor
Accepts: s - the name of the scalar quantity to retrieve from the tensor. Keyword matching rules are used. If no match is found, an error occurs.
Table 2: Equations for Zone Field Quantities

Quantity Name Stress Strain Increment Strain Rate
norm
octohedral
von-mises
[ZC: please review equations above]
zone.field.radius.ratio
Syntax
f = zone.field.radius.ratio
zone.field.radius.ratio = f
Get/set the the radius ratio parameter used for the inverse-distance-weighting method of extrapolation. The default is 0.75.
Returns: f - the radius ratio used for inverse-distance-weighting

Accepts: f - the radius ratio used for inverse-distance-weighting
zone.field.reset
Syntax
i = zone.field.reset
Removes the effect of zone.field.init. The return value is ignored.
zone.field.source
Syntax
s = zone.field.source
zone.field.source = s
Get/set where values are derived from when appropriate.
Certain values (like extra and pore-pressure) can be retrieved either from the zone structure or from the gridpoint structure. The values currently available are gridpoint
and zone. The default value is gridpoint.
Returns: s - the structure from which values are derived

Accepts: s - the structure from which values are derived. Keyword matching rules apply. If no match is found, an error occurrs.
zone.field.tol
Syntax
f = zone.field.tol
zone.field.tol = f
Get/set the tolerance used for the polynomial method of extrapolation. The default is 1e-7.
This value is used to detect a degeneracy in the matrix used to solve for polynomial extrapolation coefficients. If a degeneracy is detected, the matrix is revised to
assume there is no change in that degree-of-freedom.
Returns: f - the tolerance used for polynomial method of extrapolation

Accepts: f - the tolerance used for polynomial method of extrapolation
zone.field.type
Syntax
s = zone.field.type
zone.field.type = s
Get/set the type to assume, for those values where the type can change. This includes extra and property. The valid types are scalar, vector, or tensor. The default is
scalar.
Returns: s - the name of the type that is assumed for multiple type value
Accepts: s - the name of the type that is assumed for multiple type value
zone.find
Syntax
z = zone.find(i)
Get the zone with internally assigned ID number i.
Returns: z - pointer to the zone with ID number i. Will return null if no zone has that ID number.
Arguments: i - the ID number to look for, which must be positive
zone.flow
Syntax
Vector Access
v = zone.flow(z<,i>)
Get the specific discharge vector for the zone. Returns a vector, unless an optional component argument i is supplied, in which case it returns the component value.
Returns: v - specific discharge vector or component

Component Access
f = zone.flow.x(z)
Get the x-component of the specific discharge vector.
Returns: f - x-component of the specific discharge vector

f = zone.flow.y(z)
Get the y-component of the specific discharge vector.
Returns: f - y-component of the specific discharge vector

f = zone.flow.z(z)
Get the z-component of the specific discharge vector.
Returns: f - z-component of the specific discharge vector

zone.fluid.density
Syntax
f = zone.fluid.density(z)
zone.fluid.density(z) = fs
Get/set the fluid density for the zone.
Note that the some effects of this change will not occur until the next global update. Among them will be the gravitational force on connected grid points and the change
in inertial mass in dynamic mode. Please see the zone.force.update intrinsic.
Returns: f - the fluid density to use for the zone

Accepts: f - the fluid density to use for the zone
zone.fluid.model
Syntax
s = zone.fluid.model(z)
zone.fluid.model(z) = s
Get/set the fluid flow constitituve model for the zone. The constitutive models currently available are anisotropic, isotropic, and null.
Returns: s - the name of the current fluid constitutive model

Accepts: s - the name of the new fluid constitutive model
zone.fluid.prop
Syntax
a = zone.fluid.prop(z,s)
zone.fluid.prop(z,s) = a
Get/set the value for fluid property s in zone z. Note that the string s must match a property name in the current fluid constitutive model. Keyword matching rules are
used. If the string does not match any property in the model, an error occurs. See the list of property names listed in the zone fluid cmodel assign command.
Returns: a - the value of the fluid constitutive model property that matches to s
Accepts: a - the new value of the fluid constitutive model property that matches to s
s - the name of the fluid constitutive model property
zone.fluid.ratio
Syntax
f = zone.fluid.ratio()
Get the current fluid convergence ratio for zones. This is defined as the ratio of total unbalanced flow to the total flow through the zones.
Returns: f - the current fluid convergence ratio
zone.fluid.stress.normal
Syntax
f = zone.fluid.stress.normal()
Get the representative stress magnitude for the fast flow solution scheme.
Returns: f - the representative stress magnitude
zone.fluid.time.total
Syntax
f = zone.fluid.time.total()
zone.fluid.time.total() = f
Get/set the total accumulated zone module fluid time. This accumulates the timesteps of every cycle the zone fluid module is active.
Returns: f - the total accumulated zone module fluid time

Accepts: f - the total accumulated zone module fluid time
zone.fluid.timestep
Syntax
f = zone.fluid.timestep()
zone.fluid.timestep() = f
Get/set the current fluid timestep. Note that this may not be the timestep used in a cycle if other modules require a smaller one. This may be overriden by automatic
timestep calculations, if active. Fixing a timestep greater than the calculated critical value will produce an error.
Returns: f - the current fluid timestep

Accepts: f - the current fluid timestep
zone.fluid.unbal.avg
Syntax
f = zone.fluid.unbal.avg()
Get the average unbalanced fluid volume limit for the fast flow solution scheme.
Returns: f - the average unbalanced fluid volume limit
zone.fluid.unbal.max
Syntax
= zone.fluid.unbal.max()
Get the maximum unbalanced fluid limit for the fast flow solution scheme.
Returns: f - the maximum unbalanced fluid limit.
zone.flux
Syntax
Vector Access
v = zone.flux(z<,i>)
Get the zone average heat flux vector.
Returns: v - zone average heat flux vector or component

Accepts: v - zone average heat flux vector or component
Component Access
f = zone.flux.x(z)
Get the x-component of the zone flux.
Returns: f - x-component of the zone flux vector

Accepts: f - x-component of the zone flux vector
f = zone.flux.y(z)
Get the y-component of the zone flux.
Returns: f - y-component of the zone flux vector

Accepts: f - y-component of the zone flux vector
f = zone.flux.z(z)
Get the z-component of the zone flux.
Returns: f - z-component of the zone flux vector

Accepts: f - z-component of the zone flux vector
zone.force.update
Syntax
i = zone.force.update()
Flags the cycling logic so that a geometry update is performed at the start of the next cycle. Normally this update is performed at the start of cycling, and in large-strain
mode at the geometry update interval. Changes to gridpoint mass and gravity caused by density and stiffness changes may not actually affect the calculation unless an
update is performed. The return value is ignored.
zone.geom.test
Syntax
b = zone.geom.test(z)
Test the geometric fitness of a zone. Returns true if the zone is good and false if the zone is bad. A zone is considered to have bad geometry if the zone contains
negative or zero volume tetrahedra in its overlays. In addition to excessive large-strain deformation, the following are also causes of bad geometry: not following the
gridpoint numbering conventions; or importing an externally generated grid from a grid generator that allows severely distorted zones. This function is useful for
tagging and plotting these bad zones.
Returns: b - geometric fitness result true if good, false if bad

Arguments: z - pointer to a zone
zone.gp
Syntax
gp = zone.gp(z,i)
Get the gridpoint associated with the zone at index i. See Orientation of Nodes and Faces within a Zone and zone create for information on how gridpoints are
associated with zones. Note that zone.gp.num will return the total number of unique gridpoints available for a zone.
Returns: gp - a pointer to the gridpoint at index i for the zone

i - the index of the gridpoint to find. This should be at least 1 and will never be greater than 8.
zone.gp.num
Syntax
i = zone.gp.num(z)
Get the number of unique gridpoints associated with this type of zone. This can be as few as 4 for tetrahedral zones or as many as 8 for hexahedral zones. See
Orientation of Nodes and Faces within a Zone and zone create for information on how gridpoints are associated with zones.
Returns: i - the total number of unique gridpoints associated with the zone
zone.group
Syntax
s = zone.group(z<,slot>)
zone.group(z<,slot>) = s
Get/set the group name assigned to zone z in slot slot. Use of the group logic is described in Group.
zone.group.remove
Syntax
b = zone.group.remove(z,s)
Remove the group s from zone z, in all slots it is found.
Returns: b - true if the group was removed from one or more slots of the zone, false if the group was not found in the zone.
zone.head
Syntax
z = zone.head
Get the first zone in the list of all zones in the model. This function should be considered deprecated; it is provided mostly for backward compatibility with old data
files. Instead, see the fish_statement_loopforeach statement and the zone.list and zone.next functions.
Returns: z - a pointer to the first zone in the list of all zones in the model
zone.hysteretic
Syntax
f = zone.hysteretic(z,s)
zone.hysteretic(z,s) = f
Get/set the hysteretic damping parameter s in zone z. s can have the following possible values: c0, c1, c2, c3, modfac, model, e1, e2, e3, e4, e5, and e6.
c0, c1, c2, and c3 return/set the first through fourth parameters of the hysteretic model.
model returns/sets the hysteretic model identification number, where 1 = Default model, 2 = off, 3 = Sig3 model, 4 = Sig4 model, and 5 = Hardin model.
modfac returns/sets the current reduction factor.
e1 through e6 return/set strain components γ1 ... γ6. See Hysteretic damping for more details.
Returns: f - the value of the hysteretic damping value

s - the name of the value to retrieve from the zone
zone.id
Syntax
i = zone.id(z)
Get the zone ID number, a unique number assigned by the code when it is created.
Returns: i - the zone ID number

zone.isgroup
Syntax
b = zone.isgroup(z,s<,slot>)
Check if the group s is associated with the zone. Will return true if a match is found in any slot. If the optional third argument slot is provided, then it will only check
that slot.
Returns: b - true if the group was found in that zone

s - a group name
slot - an optional slot specification. If not provided, the check will occur on all slots that have been assigned to the zone.
zone.islive
Syntax
b = zone.islive(z)
Checks if the zone is "live", meaning it has a non-null mechanical, thermal, or fluid constitutive model.
Returns: b - true if the zone has a non-null mechanical, fluid, or thermal constitutive model
zone.join
Syntax
j = zone.join(z,i)
Get the zone joined to face i of zone z. This will return null if there is no zone connected to that face. Note that the connection must be topologically perfect.
Returns: j - the zone across the face, or null if non exists

i - the face number of the zone being checked. This is a number from 1 to 6 for hexahedral zones. If the face does not exist for other zone types, null will
always be returned.
zone.link.index
Syntax
indexnext = zone.link.index(z,index)
Get the index of the next zone in the list of all zones connected to a gridpoint. This returns the next zone in the list of zones connected to the gripoint at index of this
zone. Use the four intrinsics gp.link.zone, gp.link.index, zone.link.zone, and zone.link.index to iterate through every zone connected to a gridpoint.
Returns: indexnext - the index that the gridpoint has in the next zone in the list of all zones connected to that gridpoint
index - the index of the gridpoint in zone z
Usage Example

index = index_copy
end_loop
zone.link.zone
Syntax
zonenext = zone.link.zone(z,index)
Get the next zone in the list of all zones connected to the gridpoint attached to zone z at index index. Use the four intrinsics gp.link.zone, gp.link.index,
zone.link.zone, and zone.link.index to iterate through every zone connected to a gridpoint.
Returns: zonenext - the next zone in the list of all zones connected to the gridpoint
Arguments: z - a pointer to the zone
index - the index of the gridpoint in zone z
Usage Example

index = index_copy
end_loop
zone.list
Syntax
l = zone.list()
Get the list of all zones in the model. This is primarily used in the fish_statement_loopforeach statement.
Returns: l - a pointer to the list of all zones
zone.maxid
Syntax
i = zone.maxid()
Get the maximum ID number assigned to any zone in this model. The next zone created will be assigned this value plus one.
Returns: i - maximum ID number of any zone in the model
zone.mech.convergence
Syntax
f = zone.mech.convergence()
Get the current maximum value of convergence in any gridpoint in the model. See the model solve convergence keyword.
Returns: f - current maximum gridpoint convergence ratio
zone.mech.prop.name
Syntax
s = zone.mech.prop.name(z,i)
Get the name of the ith property in the list of properties associated with the mechanical constitutive model for that zone. If there are less than i properties available, an
error occurs. See zone.mech.prop.num.
Returns: s - the name of the ith property accepted by the zone mechanical constitutive model
i - the index of the property name, starting at 1
zone.mech.prop.num
Syntax
i = zone.mech.prop.num(z)
Get the total number of properties accepted by the mechanical constitutive model assigned to zone z. See zone.mech.prop.name.
Returns: i - the number of constitutive model properties accepted by the model assigned to zone z
zone.mech.ratio
Syntax
f = zone.mech.ratio()
Get the current zone mechanical convergence ratio. See the zone ratio command.
Returns: f - current zone mechanical convergence ratio
zone.mech.ratio
Syntax
f = zone.mech.ratio.avg()
Get the current zone mechanical average convergence ratio. See the zone ratio command.
Returns: f - current zone mechanical average convergence ratio
zone.mech.ratio.local
Syntax
f = zone.mech.ratio.local()
Get the current zone mechanical local convergence ratio. See the zone ratio command.
Returns: f - current zone mechanical local convergence ratio
zone.mech.ratio
Syntax
f = zone.mech.ratio.max()
Get the current zone mechanical maximum convergence ratio. See the zone ratio command.
Returns: f - current zone mechanical maximum convergence ratio
zone.model
Syntax
s = zone.model(z)
zone.model(z) = s
Get/set the name of the current zone mechanical constitutive model. See the list of available models with the zone cmodel assign command.
If used as an assignment, the properties will have their default values and must be initialized.
Returns: s - the name of the current mechanical constitutive model

Accepts: s - the name of the new mechanical constitutive model to assign. Keyword matching applies. If no model name that is currently available matches, an
error will occur.
zone.model.init
Syntax
i = zone.model.init(z)
Initializes all constitutive models (mechanical, fluid, and thermal) assigned to the zone. This recalculates intermediate values based on the current properties. This may
be necessary if property values are changed during cycling.
Note that mechanical constitutive models should recalculate intermediate stored values automatically when properties change.
This does not perform an update of values depending on stiffness or density; see the zone.do.update intrinsic.
Returns: 0 - always returns the integer 0

zone.near
Syntax
z = zone.near(v)
Get the zone with the centroid nearest v. Will return null if there are no zones in the model. Excludes mechanically null zones.
Returns: z - the pointer to the zone with a centroid closest to v

zone.near.all
Syntax
z = zone.near.all(v)
Get the zone with the centroid nearest v. Will return null if there are no zones in the model. Will include mechanically null zones.
Returns: z - the pointer to the zone with a centroid closest to v

zone.near.live
Syntax
z = zone.near.live(v,bmech,bfluid,btherm,s)
Get the zone with a centroid nearest point v. The four following arguments control which zones are to be considered. If bmech, bfluid, or btherm is true, then zones
containing non-null constitutive models in those processes are considered. The third string argument s must be either and or or, indicating whether the indicated models
are all required or if any one of them is sufficient.
Returns: z - the pointer to the zone matching the criteria with a centroid nearest v
bmech - indicates if mechanically non-null zones are to be considered
bfluid - indicates if fluid non-null zones are to be considered
btherm - indicates if thermal non-null zones are to be considered
s - must be either and or or; indicates whether one or all of the indicated non-null models must be present
zone.near.map
Syntax
m = zone.near.map(v,f)
Finds all zones with centroids within f distance of position :vec:`v1, and returns all of them in a map.
The may key is the zone ID nubmer, and the map value is a pointer to the zone.
No check is made for "live" status or against the constitutive model (even Null).
Returns: :map:`m` - A map of all zones within the sphere specified. Key is zone id number, value is zone pointer.
f - a distance representing a radius around point v.
zone.next
Syntax
znext = zone.next(z)
Get the next zone after z in the list of all zones in the model. Will return null if no more zones follow. This function should be considered deprecated; it is provided
mostly for backward compatibility with old data files. Instead, see the fish_statement_loopforeach statement and the zone.list and zone.head functions.
Returns: znext - the next zone in the list, or null

zone.num
Syntax
i = zone.num()
Get the total number of zones in the model.
Returns: i - the total number of zones in the model
zone.ortho
Syntax
f = zone.ortho(z)
zone.ortho()
Get a measure of orthogonality for the zone. A value near zero indicates that the zone is very non-orthogonal.
Returns: f - an orthogonality measure; zero means very non-orthogonal

zone.overlays
Syntax
i = zone.overlays(z)
Get the number of overlays available in the zone. This number will normally be 2.
A value of 1 can occur if the zone is deformed sufficiently to cause one overlay to contain a tetra with zero or negative volume, or if the zone was deliberately created
with one overlay during the zone cmodel assign command.
A value of 0 means the zone has never had a constitutive model assigned, and therefore internal tetra have never been created.
Returns: i - the number of overlays: 2, 1, or 0

zone.planarity
Syntax
f = zone.planarity(z)
Get a measure of how planar the quadrilateral faces of a zone are. A value of 0 means that all faces are perfectly planar. The greater this number, the more non-planar
the faces are.
Returns: f - a measure of zone face planarity

zone.plane.traction
Syntax
v = zone.plane.traction(z,vdir<,arr>)
Get the traction on the zone in the place normal to vdir.
If arr is given, it is filled with the normal and shear stress on the plane normal to vdir. arr(1) is the normal stress, arr(2) is the maximum shear stress, and arr(3) through
arr(5) are the (x, y, z) components of the maximum shear stress direction.
Returns: v - the traction on the zone in the plane

vdir - the direction normal to the plane
arr - an optional pointer to an array, which is filled with the normal, shear, and shear directions
zone.pos
Syntax
Vector Access
v = zone.pos(p<,i>)
Get the zone centroid position.
Returns: v - zone position vector or component

Component Access
f = zone.pos.x(p)
Get the x-component of the zone centroid position.
Returns: f - x-component of the zone position vector

f = zone.pos.y(p)
Get the y-component of the zone centroid position.
Returns: f - y-component of the zone position vector

f = zone.pos.z(p)
Get the z-component of the zone centroid position.
Returns: f - z-component of the zone position vector

zone.pp
Syntax
f = zone.pp(z)
zone.pp(z) = f
Get/set the average zone pore pressure. The assignment version is only valid if the zone-based pore pressures have been activated using the zone fluid zone-based-
pp command.
Returns: f - the zone average pore pressure

Accepts: f - the zone average pore pressure
zone.prop
Syntax
a = zone.prop(z,s)
zone.prop(z,s) = a
Get/set the value of property s in the zone. The name s must match a property type available in the current constitutive model using keyword matching rules. If no
property matches, an error occurs.
Returns: a - the value of property s in the zone

Accepts: a - the value assigned to property s in the zone. Must match the type expected by that property.
s - the name of a property
zone.rotation.inc
Syntax
Tensor Access
t = zone.rotation.inc(p<,i1<,i2>>)
Get the zone rotational increment tensor, or a component of it. This is calculated using the current displacement field.
Returns: t - zone rotational increment tensor or value

i1 - optional tensor index that, if given without i2, ranges from 1 to 7, accessing the xx, yy, zz, xy, xz, and yz tensor values.
i2 - optional tensor notation that must be given with i1. In this case, i1 corresponds to the first index of the tensor position and i2 to the second in the
Value Access
f = zone.rotation.inc.xx(p)
Get the xx-value of the zone rotational increment tensor. This is calculated using the current displacement field.
Returns: f - xx-value of the zone rotational increment tensor

f = zone.rotation.inc.xy(p)
Get the xy-value of the zone rotational increment. This is calculated using the current displacement field.
Returns: f - xy-value of the zone rotational increment tensor

f = zone.rotation.inc.xz(p)
Get the xz-value of the zone rotational increment. This is calculated using the current displacement field.
Returns: f - xz-value of the zone rotational increment tensor

f = zone.rotation.inc.yy(p)
Get the yy-value of the zone rotational increment. This is calculated using the current displacement field.
Returns: f - yy-value of the zone rotational increment tensor

f = zone.rotation.inc.yz(p)
Get the yz-value of the zone rotational increment. This is calculated using the current displacement field.
Returns: f - yz-value of the zone rotational increment tensor

f = zone.rotation.inc.zz(p)
Get the zz-value of the zone rotational increment. This is calculated using the current displacement field.
Returns: f - zz-value of the zone rotational increment tensor

zone.rotation.rate
Syntax
Tensor Access
t = zone.rotation.rate(p<,i1<,i2>>)
Get the zone rotation rate tensor or component. This is calculated using the current velocity field.
Returns: t - zone rotation rate tensor or value

Value Access
f = zone.rotation.rate.xx(p)
Get the xx-value of the zone rotation rate. This is calculated using the current velocity field.
Returns: f - xx-value of the zone rotation rate tensor

f = zone.rotation.rate.xy(p)
Get the xy-value of the zone rotation rate. This is calculated using the current velocity field.
Returns: f - xy-value of the zone rotation rate tensor

f = zone.rotation.rate.xz(p)
Get the xz-value of the zone rotation rate. This is calculated using the current velocity field.
Returns: f - xz-value of the zone rotation rate tensor

f = zone.rotation.rate.yy(p)
Get the yy-value of the zone rotation rate. This is calculated using the current velocity field.
Returns: f - yy-value of the zone rotation rate tensor

f = zone.rotation.rate.yz(p)
Get the yz-value of the zone rotation rate. This is calculated using the current velocity field.
Returns: f - yz-value of the zone rotation rate tensor

f = zone.rotation.rate.zz(p)
Get the zz-value of the zone rotation rate. This is calculated using the current velocity field.
Returns: f - zz-value of the zone rotation rate tensor

zone.state
Syntax
i = zone.state(z,bavg)
zone.state(z) = i
Get/set the current plasticity state indicators for the zone.
Tetrahedral subzones comprise a zone in FLAC3D, and each of them has a member variable that maintains its failure state. The member variable has 64 bits that can be
used to represent 64 different states. Each constitutive model defines its own list of states, and its own assignment of state names to bits in the state variable. For
convenience, however, a convention has been adopted for the most common states. The following table lists failure states and the convention adopted by many of the
constitutive models.
Failure States Value Label

Failure in shear now 1 shear-n
Failure in tension now 2 tension-n
Failure in shear in the past 4 shear-p
Failure in tension in the past 8 tension-p
Failure in joint shear now 16 j-shear-n
Failure in joint tension now 32 j-tension-n
Failure in joint shear in the past 64 j-shear-p
Failure in joint tension in the past 128 j-tension-p
Failure in volume now 256 volume-n
Failure in volume in the past 512 volume-p
The states supported by a constitutive model can be listed with the zone cmodel list state command.
The math.and and math.or intrinsics may be used to check against a specific bit or bit pattern.
Returns: i - the plasticity state indicators, encoded as bits

Accepts: i - the plasticity state indicator, encoded as bits. All tetra in the zone will be assigned this state indicator.
bavg - if true, the bit will be set if 50% or more of the volume averaged tetra have that bit set. If false, the bit will be set if any tetra in the zone have
that bit set. This value is ignored on assignment.
zone.state.restore
Syntax
i = zone.state.restore(z)
Restores all zone state information from the currently open FISH file. See the file.open and file.read intrinsics.
zone.state.save
Syntax
i = zone.state.save(z)
Saves all zone state information to the currently open FISH file. See the file.open and file.write intrinsics.
zone.strain.inc
Syntax
Tensor Access
t = zone.strain.inc(p<,i1<,i2>>)
Get the zone strain increment, based on the current displacement field.
Returns: t - zone strain increment tensor or value

Value Access
f = zone.strain.inc.xx(p)
Get the xx-value of the zone strain increment based on the current displacement field.
Returns: f - xx-value of the zone strain increment tensor

f = zone.strain.inc.xy(p)
Get the xy-value of the zone strain increment based on the current displacement field.
Returns: f - xy-value of the zone strain increment tensor

f = zone.strain.inc.xz(p)
Get the xz-value of the zone strain increment based on the current displacement field.
Returns: f - xz-value of the zone strain increment tensor

f = zone.strain.inc.yy
Get the yy-value of the zone strain increment based on the current displacement field.
Returns: f - yy-value of the zone strain increment tensor

f = zone.strain.inc.yz(p)
Get the yz-value of the zone strain increment based on the current displacement field.
Returns: f - yz-value of the zone strain increment tensor

f = zone.strain.inc.zz(p)
Get the zz-value of the zone strain increment based on the current displacement field.
Returns: f - zz-value of the zone strain increment tensor

zone.strain.rate
Syntax
Tensor Access
f = zone.strain.rate(p,i1<,i2>)
Get the zone strain rate, based on the current velocity field.
Returns: f - tensor or value

i1 - tensor index that, if given without i2, ranges from 1 to 7, accessing the xx, yy, zz, xy, xz, and yz tensor values.
Value Access
f = zone.strain.rate.xx(p)
Get the xx-value of the zone strain rate based on the current velocity field.
Returns: f - xx-value of the zone strain rate tensor

f = zone.strain.rate.xy(p)
Get the xy-value of the zone strain rate based on the current velocity field.
Returns: f - xy-value of the zone strain rate tensor

f = zone.strain.rate.xz(p)
Get the xz-value of the zone strain rate based on the current velocity field.
Returns: f - xz-value of the zone strain rate tensor

f = zone.strain.rate.yy(p)
Get the yy-value of the zone strain rate based on the current velocity field.
Returns: f - yy-value of the zone strain rate tensor

f = zone.strain.rate.yz(p)
Get the yz-value of the zone strain rate based on the current velocity field.
Returns: f - yz-value of the zone strain rate tensor
f = zone.strain.rate.zz(p)
Get the zz-value of the zone strain rate based on the current velocity field.
Returns: f - zz-value of the zone strain rate tensor

zone.strain.shear.inc
Syntax
f = zone.strain.shear.inc(z)
Get the zone shear strain increment based on the current displacement field. This is the square root of the second invariant of the strain increment deviator.
Returns: f - zone shear strain increment

zone.strain.shear.rate
Syntax
f = zone.strain.shear.rate(z)
Get the zone shear strain rate based on the current velocity field. This is the square root of the second invariant of the strain rate deviator.
Returns: f - zone shear strain rate

zone.strain.vol.inc
Syntax
f = zone.strain.vol.inc(z)
Get the zone volumetric strain increment based on the current displacement field. This is the trace of the strain increment tensor.
Returns: f - the zone volumetric strain increment

zone.strain.vol.rate
Syntax
= zone.strain.vol.rate()
Get the zone volumetric strain rate based on the current velocity field. This is the trace of the strain rate tensor.
Returns: f - the zone volumetric strain rate

zone.stress
Syntax
Tensor Access
t = zone.stress(p<,i1<,i2>>)
zone.stress(p<,i1<,i2>>) = t
Get/set the zone stress. Get: The zone-averaged value of all the internal tetra is returned, weighted by volume. Set: All of the zone's internal tetra are assigned the same
stress value. Note that compressive stresses are negative in FLAC3D.
Returns: t - zone stress tensor or value

Accepts: t - zone stress tensor or value
Value Access
f = zone.stress.xx(p)
zone.stress.xx(p) = f
Get/set the xx-value of the zone stress. Get: The zone averaged value of all the internal tetra is returned, weighted by volume. Set: All of the zone's internal tetra are
assigned the same stress value. Note that compressive stresses are negative in FLAC3D.
Returns: f - xx-value of the zone stress tensor

Accepts: f - xx-value of the zone stress tensor
f = zone.stress.xy(p)
zone.stress.xy(p) = f
Get/set the xy-value of the zone stress. Get: The zone averaged value of all the internal tetra is returned, weighted by volume. Set: All of the zone's internal tetra are
Returns: f - xy-value of the zone stress tensor

Accepts: f - xy-value of the zone stress tensor
f = zone.stress.xz(p)
zone.stress.xz(p) = f
Get/set the xz-value of the zone stress. Get: The zone averaged value of all the internal tetra is returned, weighted by volume. Set: All of the zone's internal tetra are
Returns: f - xz-value of the zone stress tensor

Accepts: f - xz-value of the zone stress tensor
f = zone.stress.yy(p)
zone.stress.yy(p) = f
Get/set the yy-value of the zone stress. Get: The zone averaged value of all the internal tetra is returned, weighted by volume. Set: All of the zone's internal tetra are
Returns: f - yy-value of the zone stress tensor

Accepts: f - yy-value of the zone stress tensor
f = zone.stress.yz(p)
zone.stress.yz(p) = f
Get/set the yz-value of the zone stress. Get: The zone averaged value of all the internal tetra is returned, weighted by volume. Set: All of the zone's internal tetra are
Returns: f - yz-value of the zone stress tensor

Accepts: f - yz-value of the zone stress tensor
f = zone.stress.zz(p)
zone.stress.zz(p) = f
Get/set the zz-value of the zone stress. Get: The zone averaged value of all the internal tetra is returned, weighted by volume. Set: All of the zone's internal tetra are
Returns: f - zz-value of the zone stress tensor

Accepts: f - zz-value of the zone stress tensor
zone.stress.effective
Syntax
Tensor Access
f = zone.stress.effective(p,i1<,i2>)
Get the zone effective stress. This is the volume-weighted average of the tetra stresses, plus the zone-averaged pore pressure.
Returns: t - zone effective stress value

i1 - tensor index that, if given without i2, ranges from 1 to 7, accessing the xx, yy, zz, xy, xz, and yz tensor values.
Value Access
f = zone.stress.effective.xx(p)
Get the xx-value of the zone effective stress.
Returns: f - xx-value of the zone effective stress tensor

f = zone.stress.effective.xy(p)
Get the xy-value of the zone effective stress.
Returns: f - xy-value of the zone effective stress tensor

f = zone.stress.effective.xz(p)
Get the xz-value of the zone effective stress.
Returns: f - xz-value of the zone effective stress tensor

f = zone.stress.effective.yy(p)
Get the yy-value of the zone effective stress.
Returns: f - yy-value of the zone effective stress tensor

f = zone.stress.effective.yz(p)
Get the yz-value of the zone effective stress.
Returns: f - yz-value of the zone effective stress tensor

f = zone.stress.effective.zz(p)
Get the zz-value of the zone effective stress.
Returns: f - zz-value of the zone effective stress tensor

zone.stress.int
Syntax
f = zone.stress.int(z)
Get the intermediate principal stress of the volume-weighted average of the zone tetra stresses.
Returns: f - the intermediate zone principal stress

zone.stress.max
Syntax
f = zone.stress.max(z)
Get the maximum (most positive) principal value of the volume-averaged tetra stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - the maximum (most positive) principal stress of the zone

zone.stress.min
Syntax
f = zone.stress.min(z)
Get the minimum (most negative) principal value of the volume-averaged tetra stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - the minimum (most negative) principal stress of the zone

zone.stress.prin
Syntax
Vector Access
v = zone.stress.prin(p<,i>)
Get the zone principal stress, calculated from the volume-weighted average of the tetra stresses. Note that compressive stresses are negative in FLAC3D.
Returns: v - zone principal stress vector or component

Component Access
f = zone.stress.prin.x(p)
Get the x-component of the zone principal stress, calculated from the volume-weighted average of the tetra stresses. Note that compressive stresses are negative in
FLAC3D.
Returns: f - x-component of the zone principal stress vector

f = zone.stress.prin.y(p)
Get the y-component of the zone principal stress, calculated from the volume-weighted average of the tetra stresses. Note that compressive stresses are negative in
FLAC3D.
Returns: f - y-component of the zone principal stress vector

f = zone.stress.prin.z(p)
Get the z-component of the zone principal stress, calculated from the volume-weighted average of the tetra stresses. Note that compressive stresses are negative in
FLAC3D.
Returns: f - z-component of the zone principal stress vector

zone.stress.prin.dir
Syntax
v = zone.stress.prin.dir(z,prin,dir)
Get the zone principal stress directions, calculated from the volume-averaged tetra stresses.
Fills the array prin with the principal stress magnitudes and the array dir with the directions of the principal stresses. It also returns the principal stresses encoded as a
vector (as does zone.stress.prin). prin indices 1, 2, and 3 are filled with the minimum, intermediate, and maximum principal stresses, respectively. dir indices 1-3
are the x-, y-, z-components of the minimum principal stress directions; 4-6 indicate the intermediate principal stress directions; and 7-9 indicate the maximum principal
stress directions.
Returns: v - the zone principal stresses as a vector in minimum, intermediate, maximum order
prin - a pointer to an array of at least size 3, filled with the principal stress values
dir - a pointer to an array of at least size 9, filled with the principal stress directions
zone.temp
Syntax
f = zone.temp(z)
zone.temp(z) = f
Get/set the zone temperature. Normally this is the average temperature of the gridpoints. If the zone thermal zone-based-temperature command was used, then
temperatures are stored and retrieved directly from the zone.
Returns: f - the average zone temperature

Accepts: f - the temperature to store in the zone; only valid if zone thermal zone-based-temperature has been set to true
zone.test.quality
Syntax
f = zone.test.quality(z,itype)
zone.test.quality()
Get a measure of the zone quality, or how the zone shape may affect solution accuracy. itype must be either 1 or 2; any other value causes a return value of 0.0. itype =
1 indicates a test of volume over edge length. itype = 2 indicates a test of skew. Both return the minimum value obtained over all internal tetrahedrons. A return value of
1.0 indicates an equilateral tetra.
Returns: f - a measure of the zone quality

itype - 1 for a test of volume over edge length, 2 for a test of skew
zone.tetra.gp
Syntax
f = zone.tet.gp(z,ioverlay,itetra,arr)
Gets the gridpoint pointers associated with a tetrahedron number itet in overlay ioverlay. Returns the tetra volume.
The gridpoint pointers are placed into array arr. The gridpoints follow the convention that if you are an observer at the 4th gridpoint looking at gridpoints 1, 2, and 3,
then the direction from gridpoint 1 to gridpoint 2 to gridpoint 3 is counterclockwise. Note that tetrahedral volumes are only calculated when cycling begins (or a model
step 0 command is issued), and during large-strain updates. A zero volume will be returned if cycling has not yet occurred.
See the functions zone.overlays and zone.tet.num.
Returns: f - the volume of the tetra, or 0.0 if this has not been calculated yet
Arguments: z - a zone pointers
ioverlay - the overlay index, from 1 to 2
itetra - the tetra index, from 1 to a maximum of 5
arr - an array of at least size 4
zone.tetra.num
Syntax
i = zone.tet.num(z)
Get the number of tetra in each overlay of the zone.
See also the function zone.overlays.
Returns: i - the number of tetra in each overlay of the zone

zone.tetra.smallest.vol
Syntax
f = zone.tet.smallest.vol(z)
Get the volume of the smallest tetrahedron in an overlay.
This volume is normalized to the zone volume. This function is useful for isolating zones that have become badly distorted during large-strain simulation. See also the
zone geometry-tolerance command.
Returns: f - the volume of the smallest tetrahedron in the zone normalized to the total zone volume
zone.tetra.strain.increment
Syntax
Tensor Access
t = zone.tet.strain.inc(z,ioverlay,itetra<,i1<,i2>>)
Get the zone tetra strain increment based on the current displacement field.
See also the functions zone.overlays and zone.tet.num.
Returns: t - zone tetra strain increment tensor or value

ioverlay - the overlay index of the tetra, from 1 to 2
itetra - the index of the tetra in the overlay
Value Access
f = zone.tet.strain.inc.xx(z,ioverlay,itetra)
Get the xx-value of the zone tetra strain increment based on the current displacement field.
Returns: f - xx-value of the zone tetra strain increment tensor

f = zone.tet.strain.inc.xy(z,ioverlay,itetra)
Get the xy-value of the zone tetra strain increment based on the current displacement field.
Returns: f - xy-value of the zone tetra strain increment tensor

f = zone.tet.strain.inc.xz(z,ioverlay,itetra)
Get the xz-value of the zone tetra strain increment based on the current displacement field.
Returns: f - xz-value of the zone tetra strain increment tensor

f = zone.tet.strain.inc.yy
Get the yy-value of the zone tetra strain increment based on the current displacement field.
Returns: f - yy-value of the zone tetra strain increment tensor

f = zone.tet.strain.inc.yz(z,ioverlay,itetra)
Get the yz-value of the zone tetra strain increment based on the current displacement field.
Returns: f - yz-value of the zone tetra strain increment tensor

f = zone.tet.strain.inc.zz(z,ioverlay,itetra)
Get the zz-value of the zone tetra strain increment based on the current displacement field.
Returns: f - zz-value of the zone tetra strain increment tensor

zone.tetra.strain.rate
Syntax
Tensor Access
t = zone.tet.strain.rate(z,ioverlay,itetra<,i1<,i2>>)
Get the zone tetra strain rate based on the current velocity field.
Returns: t - zone tetra strain rate tensor or value

Value Access
f = zone.tet.strain.rate.xx(z,ioverlay,itetra)
Get the xx-value of the zone tetra strain rate based on the current velocity field.
Returns: f - xx-value of the zone tetra strain rate tensor

f = zone.tet.strain.rate.xy(z,ioverlay,itetra)
Get the xy-value of the zone tetra strain rate based on the current velocity field.
Returns: f - xy-value of the zone tetra strain rate tensor

f = zone.tet.strain.rate.xz(z,ioverlay,itetra)
Get the xz-value of the zone tetra strain rate based on the current velocity field.
Returns: f - xz-value of the zone tetra strain rate tensor

f = zone.tet.strain.rate.yy
Get the yy-value of the zone tetra strain rate based on the current velocity field.
Returns: f - yy-value of the zone tetra strain rate tensor

f = zone.tet.strain.rate.yz(z,ioverlay,itetra)
Get the yz-value of the zone tetra strain rate based on the current velocity field.
Returns: f - yz-value of the zone tetra strain rate tensor

f = zone.tet.strain.rate.zz(z,ioverlay,itetra)
Get the zz-value of the zone tetra strain rate based on the current velocity field.
Returns: f - zz-value of the zone tetra strain rate tensor

zone.tetra.stress
Syntax
Tensor Access
t = zone.tet.stress(z,ioverlay,itetra<,i1<,i2>>)
zone.tet.stress(z,ioverlay,itetra<,i1<,i2>>) = t
Get/set the zone tetra stress. Note that compressive stresses are negative in FLAC3D.
Returns: t - zone tetra stress tensor or value

Value Access
f = zone.tet.stress.xx(z,ioverlay,itetra)
zone.tet.stress.xx(z,ioverlay,itetra) = f
Get/set the xx-value of the zone tetra stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - xx-value of the zone tetra stress tensor

Accepts: f - xx-value of the zone tetra stress tensor
f = zone.tet.stress.xy(z,ioverlay,itetra)
zone.tet.stress.xy(z,ioverlay,itetra) = f
Get/set the xy-value of the zone tetra stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - xy-value of the zone tetra stress tensor

Accepts: f - xy-value of the zone tetra stress tensor
f = zone.tet.stress.xz(z,ioverlay,itetra)
zone.tet.stress.xz(z,ioverlay,itetra) = f
Get/set the xz-value of the zone tetra stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - xz-value of the zone tetra stress tensor

Accepts: f - xz-value of the zone tetra stress tensor
f = zone.tet.stress.yy(z,ioverlay,itetra)
zone.tet.stress.yy(z,ioverlay,itetra) = f
Get/set the yy-value of the zone tetra stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - yy-value of the zone tetra stress tensor

Accepts: f - yy-value of the zone tetra stress tensor
f = zone.tet.stress.yz(z,ioverlay,itetra)
zone.tet.stress.yz(z,ioverlay,itetra) = f
Get/set the yz-value of the zone tetra stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - yz-value of the zone tetra stress tensor

Accepts: f - yz-value of the zone tetra stress tensor
f = zone.tet.stress.zz(z,ioverlay,itetra)
zone.tet.stress.zz(z,ioverlay,itetra) = f
Get/set the zz-value of the zone tetra stress. Note that compressive stresses are negative in FLAC3D.
Returns: f - zz-value of the zone tetra stress tensor

Accepts: f - zz-value of the zone tetra stress tensor
zone.thermal.model
Syntax
s = zone.thermal.model(z)
zone.thermal.model(z) = s
Get/set the thermal flow constitutive model for the zone. The currently available constitutive models are advection-conduction, anisotropic, hydration, isotropic, and
null.
Returns: s - the name of the current thermal constitutive model

Accepts: s - the name of the new thermal constitutive model
zone.thermal.prop
Syntax
a = zone.thermal.prop(z,s)
zone.thermal.prop(z,s) = a
Get/set the value for thermal property s in zone z. Note that the string s must match a property name in the current thermal constitutive model. Keyword matching rules
are used. If the string does not match any property in the model, an error occurs. See the list of property names listed in the zone thermal cmodel assign command.
Returns: a - the value of the thermal constitutive model property that matches to s
Accepts: a - the new value of the thermal constitutive model property that matches to s
s - the name of the thermal constitutive model property
zone.thermal.ratio
Syntax
f = zone.thermal.ratio()
Get the current thermal convergence ratio for zones. This is defined as the ratio of total unbalanced heat flow to the total heat flow through the zones.
Returns: f - the current thermal convergence ratio
zone.thermal.time.total
Syntax
f = zone.thermal.time.total()
zone.thermal.time.total() = f
Get/set the total accumulated zone module thermal time. This accumulates the timesteps of every cycle the zone thermal module is active.
Returns: f - the total accumulated zone module thermal time

Accepts: f - the total accumulated zone module thermal time
zone.thermal.timestep
Syntax
f = zone.thermal.timestep()
zone.thermal.timestep() = f
Get/set the current thermal timestep. Note that this may not be the timestep used in a cycle, if other modules require a smaller one. This may be overriden by automatic
timestep calculations, if active. Fixing a timestep greater than the calculated critical value will produce an error.
Returns: f - the current thermal timestep

Accepts: f - the current thermal timestep
zone.typeid
Syntax
i = zone.typeid()
Get an identifier that uniquely determines the type of object. For zones, this will always return 1283546101.
zone.unbal
Syntax
f = zone.unbal()
Get the current maximum unbalanced force on any gridpoint in the model.
Returns: f - the maximum unbalanced force on zone gridpoints
zone.vol
Syntax
f = zone.vol(z)
Get the zone volume calculated using the current position of the zone’s gridpoints.
Recall that in a large-strain analysis, gridpoint positions are updated. In a small-strain analysis, gridpoint positions are not updated. This FISH intrinsic will return the
zone volume of an undeformed zone when used in a small-strain analysis. In small-strain, to obtain zone volume that takes into account accumulated gridpoint
displacements, use FISH intrinsic zone.vol.deformed.
Returns: f - the current zone volume

zone.vol.deformed
Syntax
f = zone.vol.deformed(z)
Get the volume of a zone using gridpoint positions that take into account accumulated gridpoint displacements.
This FISH intrinsic is meant to be used in a small-strain analysis when deformed zone volumes are required. This FISH intrinsic should not be used in a large-strain
analysis (an incorrect volume will be returned). Use the intrinsic zone.vol in large-strain mode.
Returns: f - the zone volume adjusted for the current displacement field
zone.was.updated
Syntax
b = zone.was.updated()
Returns TRUE if the last validation check actually performed a geometry update. Normally this update is performed at the start of cycling, and in large-strain mode at
the geometry update interval. This value will be true after the validation update is performed until the next validation step when a full geometry update is not performed.
Returns: b - true if the last validation step in the cycle sequence performed a full geometry update.
zone.work.elastic.shear
Syntax
f = zone.work.elastic.shear(z)
Get the shear elastic work. See Energy Calculation in FLAC3D.
Returns: f - shear elastic work

zone.work.elastic.total
Syntax
f = zone.work.elastic.total(z)
Get the total elastic work. See Energy Calculation in FLAC3D.
Returns: f - total elastic work

zone.work.elastic.vol
Syntax
f = zone.work.elastic.vol(z)
Get the volumetric elastic work. See Energy Calculation in FLAC3D.
Returns: f - volumetric elastic work

zone.work.plastic.shear
Syntax
f = zone.work.plastic.shear(z)
Get the shear plastic work dissipated. See Energy Calculation in FLAC3D.
Returns: f - shear plastic work

zone.work.plastic.total
Syntax
f = zone.work.plastic.total(z)
Get the total plastic work dissipated. See Energy Calculation in FLAC3D.
Returns: f - total plastic work

zone.work.plastic.vol
Syntax
f = zone.work.plastic.vol(z)
Get the volumetric plastic work dissipated. See Energy Calculation in FLAC3D.
Returns: f - volumetric plastic work

Itasca - Flac3d 6.0 PDF

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Itasca - Flac3d 6.0 PDF

Hochgeladen von

Copyright:

Verfügbare Formate

FLAC3D Elements Page 1 of 772

Figure 1: Sign convention for positive stress components.

Figure 2: Mechanical pressure: (a) positive; (b) negative

Stress Sign Conventions

Table 1: Principal Stress Conventions

According to equations in Table 1, we have

Table 1: Stress/Strain Invariants

3rd stress invariant 3rd strain invariant

minimum principal stress minimum principal strain

equivalent deviatoric stress equivalent (engineering) shear strain

maximum shear stress maximum shear strain

Table 1: Systems of units — mechanical parameters

Gravity m/sec2 m/sec2 m/sec2 cm/s2 ft/sec2 in/sec2

where 1 bar = 106 dynes/cm2 = 105 N/m2 = 105 Pa;

1 slug = 1 lbf -s2/ft = 14.59 kg;

Table 3: Systems of units — groundwater flow parameters

Water density kg/m3 106 g/cm3 slugs/ft3 snails/in3

NOTE: FLAC3D permeability ≡ intrinsic permeability (in cm2) × 9.9 × 10-2

Contents of This Section

zone apply keyword ... <range>

l The Range Phrase

The Range Phrase

l all its parameters are specified, or

Logical Operations in a Range Phrase

Logical Operations & Named Ranges

This is equivalent to:

geometry group edge 'mainedges' range position-x 5 500 ...

Named Ranges vs. Groups

Range Phrase Keyword Reference

annulus keyword ...

component-id i1 <i2 >

cylinder keyword ...

radius fr1 <fr2 >

dfn s keyword ...

Specify additional DFNs to include during distance testing.

keywords are available.

Add an additional geometry set named s to the list of those checked.

Selects objects inside topologically closed volumes.

Selects objects outside topologically closed volumes.

adds an additional geometry set named s to the list of those checked.

Specify the orientation as a vector.

half-space above the plane

half-space below the plane

region within distance f of the plane

unit normal vector of the plane

a point on the plane

seed vsource vdir keyword

group <slot s >

Selects all objects.

sphere <keyword> ...

Specifies the center of the sphere. By default this value is (0,0,0).

Specifies the radius of the sphere. By default this value is 0.0.

The fluid model is used to determine null.

The mechanical model is used to determine null.

The thermal model is used to determine null.

Find a named range.

Returns: r - range pointer

Determine range inclusion status.

Returns: b - range inclusion status

a - index, pointer, or vector

l an object may belong to only one group within a given slot

data scalar group "one" slot "main" range id 1,5

Once processed, we have: