Range Phrase Keyword Reference

range keyword ...

Primary keywords:

union use-hidden selected deselected by not extent annulus aspect-ratio circle cmodel collection component-id component-id-list id-list concave contact cylinder deformable dfn dfn-3dec displacement edge-length ellipse excavated extra extra-list face-area fish fracture-id geometry-distance geometry-space group group-intersection id id-list index-list interface jmodel joint-set master-id named-range orientation plane polygon position position-x position-y position-z project-range rectangle seed set sphere state structure-type surface velocity volume wall

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. [common problem] See ref-selecthide-.

selected

Include selected objects. This causes the range to only consider objects that are selected. [common problem] See ref-selecthide-.

deselected

Include not selected objects. This causes the range to only consider objects that are not selected. [common problem] See ref-selecthide-.

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 would be selected. It is also possible to specify which type of object should be considered for this purpose using the by keyword. For instance, when checking to see if a zone is selected by a range one might like to restrict the query to the gridpoints of the zone. Unless the all keyword is given, any sub-object of a parent object must be selected for the parent object to be selected. For instance, without the all keyword but with the zone-gridpoint keyword, only one zone gridpoint in a zone must be selected for the zone to be selected. The following are acceptable types:

Zone data types may specify: zone-face, zone-gridpoint, or zone.

Block data types may specify: block, block-face, block-gridpoint, or block-zone.

Geometry data types may specify: geometry-node, geometry-edge, geometry-polygon, or geometry-set.

Discrete fracture network data types may specify: dfn, fracture, intersection, or intersection-set.

Rigid block data types may specify: rblock-vertex or rblock-facet.

all

Specify that all sub-objects must be selected for the their parent object to be selected. By default only one sub-object must be selected.

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.

aspect-ratio fl fu (3DEC-specific): Select blocks with a maximum aspect ratio between the specified upper and lower limits. The aspect ratio is defined as the maximum edge length divided by the cube root of the volume. Other objects will be selected if they are associated with a block that matches the criterion.

circle keyword ... (2D ONLY)

Select objects within a circular region.

center f: Center of the circular region.

radius f: Radius of the circular region.

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.

collection il <iu > (3DEC-specific): Select structural elements (beams, cables, liners, reinforcements) with the collection ID specified. The interval (il, iu) is inclusive — if iu is not specified, then iu is set equal to il.

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 structural elements an ID number refers to a user-defined number identifying a collection of elements. In this case component-id range element refers to the internal unique ID number of the individual object.

component-id-list i1 ...: For most objects, this is the same as the id-list range element. It selects objects based on an ID number assigned to an object internally upon creation. For structural elements an ID number refers to a user-defined number identifying a collection of elements. In this case component-id-list range element refers to the internal unique ID number of the individual object.

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.

concave f (3DEC-specific): Select blocks that are concave. Blocks are considered concave if two adjacent faces make an angle greater than f degrees. The default value of f is 180. Other objects will be selected if they are associated with a block that matches the criterion.

contact keyword ... (PFC-specific)

Select contacts.

active: Select only active contacts. The activity status depends on the contact model installed at the contacts.

all: Select all contacts (active and inactive). This is the default behavior. The activity status depends on the contact model installed at the contacts.

gap f1 <f2 >: Select contacts based on their gap (see Contact Resolution). If only one value f1 is specified, then only contacts with a gap \(g \leq f_1\) are selected. If a second value f2 is input, than all contacts with a gap in the range \(f_1 \leq g \leq f_2\) are selected.

inactive: Select only inactive contacts. The activity status depends on the contact model installed at the contacts.

model s: Select contacts based on their contact model name.

type s: Select contacts based on their contact type (e.g. ball-ball, ball-pebble, ball-wallfacet, ball-rblock , …)

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.

deformable (3DEC-specific): Select blocks that are deformable (zoned). Other objects will be selected if they are associated with a block that matches the criterion.

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.

dominance b: Change the dominance state for selection with contacts. By default the fracture with lowest dominance index is identified per contact to decide if the contact is in range. If turned off, a contact is considered in range if any fracture, regardless of dominance, fits the range criteria.

name s: Specify additional DFNs to include during distance testing.

orientation b <f >: Only select objects if their orientation is within f of the fracture, where f is an angle in degrees. If not given, f defaults to 2 degrees.

dfn-3dec s keyword ... (3DEC-specific): Select faces, contacts or subcontacts created by the discrete fracture network with name s. Objects will only be selected in they lie on a DFN fracture. Other objects will be selected based on their associated contact or subcontact.

displacement fl fu: Select an object with displacement between the specified upper and lower limits. Use the by keyword to limit by sub-objects (e.g., block-gridpoint).

edge-length fl fu (3DEC-specific): Select blocks with the minimum edge length between the specified upper and lower limits. Other objects will be selected if they are associated with a block that matches the criterion.

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.

excavated (3DEC-specific): Select blocks that are excavate. Other objects will be selected if they are associated with a block that matches the criterion.

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.

face-area fl fu (3DEC-specific): Select blocks with a minimum face area between the specified upper and lower limits. Other objects will be selected if they are associated with a block that matches the criterion.

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.

fracture-id il <iu > (3DEC-specific): Select contacts, subcontacts or faces with the fracture ID specified. The fracture ID corresponds to the ID of the DFN fracture used to create the object. Zones, blocks and vertices will be selected if one of their faces meets the criterion. A flow plane vertex will be selected if its associated subcontact meets the criterion. The interval (il, iu) is inclusive — if iu is not specified, then iu is set equal to il.

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:

i: 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 of the 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 Groups section. [common problem] of ref-flac3dcommandconstructs-.

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.

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.

group-intersection s1 s2 <slot s3 > (3DEC-specific)

Select objects at the intersection of blocks with group s1 and s2 in group slot \(s3\). If no slot is specified then the group will be checked in all slots the objects contains.

This can be used to select contacts or faces that lie between blocks with different group names (for example, to identify the surface of a tunnel prior to excavation).

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.

Note that for structural elements this selects by the group ID number assigned on creation. To select an individual element, node, or link use the component-id range element.

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.

Note that for structural elements this selects by the group ID number assigned on creation. To select individual elements, nodes, or links use the component-id-list range element.

index-list i1 ... (3DEC-specific): Selects objects with indices (offsets) that match the list of index numbers supplied. These index numbers do not have to be sequential. The range element is optimized for efficient searching even if a large number of index 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.

jmodel s (3DEC-specific): Select subcontacts with joint model names that match s. See the block contact jmodel command for keyword names.

joint-set i ... (3DEC-specific)

Select objects associated with the specified joint-set ID. Any number of IDs may be specified, the element will return a match if the object is associated with any of them.

This can be used to directly select block contacts, subcontacts and faces. Blocks, zones, vertices will be selected if one of the host blocks has a matching contact. Similarly flow planes, flowplane zones and flow plane vertices will be selected if the flow plane contact is a match.

master-id i ... (3DEC-specific): Select objects associated with the specified block master ID. This is for use with joined blocks. If blocks are unjoined, master ID = 0, and objects will not be selected. Zones, faces, and gridpoints will be selected if the host block has a matching master ID.

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-direc- tion 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). 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)

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.

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 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.

position-z f1 <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 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.

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 Groups.

uniform: Selects all objects.

set keyword ...

Select based on a parent/child relationship.

id i: Id of set to filter by.

name s: Name of set to filter by.

typename s: Typename of set to filter by. This can be used with nested hierarchies.

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. In 3DEC blocks will be selected if they contain a zone that is selected.

The following keywords change how the zone state is reported, based on the separate states kept in their component tetrahedra overlays.

any (FLAC3D only): The zone is considered to have that state if any of its internal tetrahedra have that state.

average (FLAC3D only): 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.

velocity fl fu: Select an object with a velocity between the specified upper and lower limits. Use the by keyword to limit by sub-objects (e.g. block-gridpoint).

volume fl fu: Select an object with a volume between the specified upper and lower limits.

wall (3DEC-specific): Select blocks that are walls. Other objects will be selected if they are associated with a block that matches the criterion.

⇄

⇐ Named Ranges | FISH Functions ⇒

Was this helpful? ...

Updated: Feb 25, 2024