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
groupkeyword, 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.
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 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.
- 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 cmodelcommand 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).
- 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.
- 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.
- 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.pointerortype.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.
- 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 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.
- group s keyword
Select objects associated with the group s. Use of the group logic is described in the Group 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.
- 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 solveormodel cyclecommand, 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.
- 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
- 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.
- 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.
- 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.
- 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 within 1.19e-7 if f1 is 0.0. This geometric element accepts the extent range element modifier.
- 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.
- 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.
| Was this helpful? ... | PFC 6.0 © 2019, Itasca | Updated: Nov 19, 2021 |