Zone

class itasca.zone.Zone

Objects of this type should not be created (instantiated) directly in Python. Use the module functions that return instances of this type.

adjacent_zones() → length 6 tuple in 3D and length 4 tuple in 2D of Zone objects or None.

Return a tuple of the zones adjacent to this zone via a topologically perfect face. If there is no face adjacent to face i the ith element of the tuple will be None.

aspect() → float.

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.

condition() → float.

Get the zone condition number. This is a general value indication how geometrically well formed the zone is. A value of 1.0 indicates a perfect zone. A value of 0.0 indicates an unusable zone. For more information, see “zone.condition” FISH function.

copy_to(destination: itasca.zone.Zone) → None.

Copy the zone state information from this zone to the destination zone.

create_interface_element(face_index: int, interface_name: str) → int.

Create new interface elements attached to the face given by \(face_index\). \(face_index\) starts at 0. The newly created interface elements will be added to the interface given by interface_name. If this interface does not exist it will be created. The return value is the number if interface elements created. A value of zero is returned if the face already has an interface.

density() → float.

Get the zone density.

extra(slot: int) → any.

Get the zone extra data in the given slot.

face_areas() → tuple of floats (3D ONLY).

Get the area of the faces of this zone.

face_extra(face_index: int, extra_index: int) → any.

Get the value of the extra variable at the index \(extra_index\) associated with \(face_index\). \(face_index\) starts at zero, \(extra_index\) starts at 1.

face_find(gp0, gp1, gp2(3D ONLY)) → int or None.

Get the face index of the zone that contains gridpoints gp0, gp1 and gp2 (3D ONLY). Each gridpoint may be specified by a itasca.gridpoint.Gridpoint object or by ID number. If the face is found a value beteen 0 and 5 is returned in 3D case and between 0 and 3 in 2D case. If no face is found, None is returned.

face_find_normal(normal: vec) → int.

Get the face index of the zone that has outward facing normal closest to the direction normal. This function returns a value from 0 to 5 in 3D and from 0 to 3 in 2D.

face_group(face_index: int, slot='Default') → str or None.

Get the group name associated with the face identified by \(face_index\) in slot \(slot\). \(face_index\) starts at zero. None is returned if no group is assigned to the given slot.

face_group_remove(face_index: int, group_name: str) → bool.

Removes the group_name from the face identified and \(face_index\). The return value will be false if that group had not been assigned to that face. It will remove the group name from any slot it is found in. \(face_index\) starts at zero.

face_in_group(face_index: int, group_name: str, slot='Default') → bool.

Check if the group_name is associated with the zone face indicated by \(face_index\). By default will check if there is a match in any slot, if the slot optional 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. \(face_index\) starts at zero.

face_normals() → tuple of vec.

Get the outward facing normal vector of all the faces of the zone.

faces() → tuple of tuples of Gridpoint objects.

Get a tuple of tuples containing the gridpoint objects for each face. Note that zone edges in 2D are referred to and treated as faces (e.g., a 2D edge represents an infinite face in plane-strain analysis).

flow() → vec.

Get the zone specific discharge vector for the zone (vector).

flow_x() → float.

Get the x-component of the zone specific discharge vector for the zone.

flow_y() → float.

Get the y-component of the zone specific discharge vector for the zone.

flow_z() → float.

Get the z-component of the zone specific discharge vector for the zone.

fluid_prop(property_name: str) → float.

Get a fluid property value of this zone.

fluid_props() → dict {str: any}.

Return a dictionary containing the fluid properties.

flux() → vec.

Get the zone zone average heat flux vector (vector).

flux_x() → float.

Get the x-component of the zone zone average heat flux vector.

flux_y() → float.

Get the y-component of the zone zone average heat flux vector.

flux_z() → float.

Get the z-component of the zone zone average heat flux vector.

geom_test() → bool.

Test the geometric fitness of a zone. Returns true if the zone does not contain any degenerate internal tera (in 3D) or triangles (in 2D). Otherwise, returns false.

gridpoints() → tuple of Gridpoint objects.

Get a tuple of gridpoint objects correposnding to the zone’s gridpoints.

group([slot: str or int]) → str.

Get the zone group name in a given slot.

group_remove(group_name: str or int[, slot: str or int]) → bool.

Remove from the given group from all group slots of the zone. One argument of type string, giving the group name, is required. The return value is a bool which is True if the group was removed from any slot, otherwise False.

groups() → {slot: group_name}.

Get a dictionary describing which groups this zone is part of. The keys of the dictionary are the slot names and the values are the group names.

has_prop(property_name: str) → bool.

Returns True if the zone has the given property.

hysteretic_props() → dict {string: float}.

Get the hysteretic damping properties of this zone as a Python dictionary.

id() → int.

Get the zone id.

in_group(group_name: str or int[, slot: str or int]) → bool.

Test if the zone is part of a given group. If the optional argument slot is given, only that slot is searched. Otherwise, all group slots are searched.

live() → bool.

Checks if the zone is live, meaning it has a non-null mechanical, thermal, or fluid constitutive model.

model() → string.

Get the zone the current zone mechanical constitutive model.

model_init() → None.

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 itasca.zone.force_update() function.

num_gp() → int.

Get the number of unique gridpoints associated with this type of zone.

ortho() → float.

Get a measure of orthogonality for the zone. A value near zero indicates that the zone is very non-orthogonal.

overlays() → int.

Get the number of overlays available in the zone. This number will normally be 2. A value of 1 can occurr if the zone is deformed sufficiently to cause one overlay to contain an internal tetra (in 3D) or triangle (in 2D) 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/triangles have never been created.

planarity() → float (3D ONLY).

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 nonplanar the faces are.

plane_traction(vdir: vec) → (traction: vec, normal_stress: float, max_shear_stress: float, max_shear_stress_direction: vec).

Get the traction on the zone in the plane normal to vdir (3D or 2D vector). In 2D plane-strain analysis, the plane is assumed to extend in out-of-plane direction. The return value is a tuple which contains the traction(vec), normal stress(float), maximum shear stress(float) and maximum shear stress direction (vec).

pos() → vec.

Get the zone centroid location (vector).

pos_x() → float.

Get the x-component of the zone centroid location.

pos_y() → float.

Get the y-component of the zone centroid location.

pos_z() → float.

Get the z-component of the zone centroid location.

pp() → float.

Get the zone average zone pore pressure.

prop(property_name: str) → any.

Get a property value of this zone.

props() → dict {str: any}.

Return a dictionary containing the mechanical properties.

rotation() → stens3.

Get the zone rotational increment tensor. This is calculated using the current displacement field. The symmetric tensor components are used (xx,yy,zz,xy,yz,xz).

rotation_rate() → stens3.

Get the zone rotation rate tensor. This is calculated using the current velocity field. The symmetric tensor components are used (xx,yy,zz,xy,yz,xz).

set_density(value: float) → None.

Set the zone density.

set_extra(slot: int, value: any) → None.

Set the zone extra data in the given slot.

set_face_extra(face_index: int, extra_index: int, value: any) → None.

Set the value of the extra variable at the index \(extra_index\) associated with \(face_index\). \(face_index\) starts at zero.

set_face_group(face_index: int, group_name: str, slot='Default') → None.

Set the group name associated with the face identified by \(face_index\) in slot \(slot\). \(face_index\) starts at zero.

set_fluid_prop(property_name: str) → float.

Set a fluid property value of this zone.

set_group(group_name: str or int[, slot: str or int]) → None.

Set the zone group name in a given slot.

set_model(value: string) → None.

Set the zone the current zone mechanical constitutive model.

set_pp(value: float) → None.

Set the zone average zone pore pressure.

set_prop(property_name: str, value: any) → None.

Set a property of this zone.

set_state(state: int) → None.

Set the current plasticity state indicators of this zone.

set_stress(stress: stens3) → None.

Set the 3D zone stress tensor. The tensor components must be provided in the order xx,yy,zz,xy,yz,xz.

set_temp(value: float) → None.

Set the zone temperature.

set_therm_prop(property_name: str) → float.

Set a thermal property value of this zone.

set_thermal_model(model: str) → None.

Set the thermal flow constitituve model for the zone. The currently available constitutive models are advection-conduction, anisotropic, hydration, isotropic, and null.

set_work_elastic_shear(value: float) → None.

Set the zone shear elastic work dissipated.

set_work_elastic_vol(value: float) → None.

Set the zone volumetric elastic work dissipated.

set_work_plastic_shear(value: float) → None.

Set the zone shear plastic work dissipated.

set_work_plastic_vol(value: float) → None.

Set the zone volumetric plastic work dissipated.

state(average: bool) → int.

Get the current plasticity state indicators of this zone. The argument average, if true, indicates that the state indicator will be set if 50% or more of the volume averaged tetra/triangle have that indicator. If false then the state indicator will be set if any tetra/triangle in the zone have that indicator. For more information, see “zone.state” FISH function.

strain() → stens3.

Get the zone strain increment tensor, based on the current displacement field. The symmetric tensor components are used (xx,yy,zz,xy,yz,xz).

strain_rate() → stens3.

Get the zone strain rate tensor, based on the current velocity field. The symmetric tensor components are used (xx,yy,zz,xy,yz,xz).

strain_shear_inc() → float.

Get the zone shear strain increment, based on the current displacement field. This is the square root of the second invariant of full 3D strain increment deviator.

strain_shear_rate() → float.

Get the zone shear strain rate, based on the current velocity field. This is the square root of the second invariant of full 3D strain rate deviator.

strain_vol_inc() → float.

Get the zone volumetric strain increment, based on the current displacement field. This is the trace of full 3D strain increment tensor.

strain_vol_rate() → float.

Get the zone volumetric strain rate, based on the current velocity field. This is the trace of full 3D strain rate tensor.

stress() → stens3.

Get the zone stress tensor, calculated from the volume (in 3D) or area (in 2D) weighted average of the internal tetra/triangle stresses. The symmetric tensor components are used (xx,yy,zz,xy,yz,xz).

stress_effective() → stens3.

Get the zone effective stress. This is the volume (in 3D) or area (in 2D) weighted average of the internal tetra/triangles stresses, plus the zone averaged pore-pressure. The symmetric tensor components are used (xx,yy,zz,xy,yz,xz).

stress_int() → float.

Get the intermediate principal stress of the volume (in 3D) or area (in 2D) weighted average of the zone tetra/triangle stresses. Note that compressive stresses are negative in FLAC.

stress_max() → float.

Get the maximum (most positive) principal value of the volume (in 3D) or area (in 2D) weighted averaged tetra/triangle stress. Note that compressive stresses are negative in FLACD.

stress_min() → float.

Get the minimum (most negative) principal value of the volume (in 3D) or area (in 2D) weighted averaged tetra/triangle stress. Note that compressive stresses are negative in FLAC.

stress_prin() → vec.

Get the zone zone principal stress, calculated from the volume (in 3D) or area (in 2D) weighted average of the internal tetra/triangle stresses (vector).

stress_prin_dir() → (vec3, tens3).

Return a tuple containing the principle stress magnitudes as a vec3 and the principle stress directions as a tens3.

stress_prin_x() → float.

Get the x-component of the zone zone principal stress, calculated from the volume (in 3D) or area (in 2D) weighted average of the internal tetra/triangle stresses.

stress_prin_y() → float.

Get the y-component of the zone zone principal stress, calculated from the volume (in 3D) or area (in 2D) weighted average of the internal tetra/triangle stresses.

stress_prin_z() → float.

Get the z-component of the zone zone principal stress, calculated from the volume (in 3D) or area (in 2D) weighted average of the internal tetra/triangle stresses.

temp() → float.

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

test_quality() → (length_vol: float, skew: float) (3D ONLY).

Get measures of the zone quality, or how the zone shape may affect solution accuracy. The first value indicates a test of volume over edge length. The second value 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.

tet_strain_rates() → tuple of tuples of stens3.

Get all the internal tets/triangles strain rate tensors. Returns two tuples (one per overlay), each containing symmetric part of full 3D tets/triangles strain rate tensor.

tet_strains() → tuple of tuples of stens3.

Get all the internal tets/triangles strain tensors. Returns two tuples (one per overlay), each containing symmetric part of full 3D tet/triangles strain tensor.

tet_stresses() → tuple of tuples of stens3.

Get the symmetric 3D stress tensors for each internal tet (3D) or triangle (2D). Returns two tuples of stens3, one for each overlay.

tet_volumes() → tuple of tuples of float.

Get volume (in 3D) or area (in 2D) of each internal tet/triangle. Returns two tuples, one for each overlay. These values are zero before any cycling has occured.

tets() → tuple of tuples of tuples of itasca.

gridpoint.Gridpoint objects. Get the gridpoints which make of each internal tet/triangle. Returns two tuples, one for each overlay.

therm_prop(property_name: str) → float.

Get a thermal property value of this zone.

therm_props() → dict {str: any}.

Return a dictionary containing the thermal properties.

thermal_model() → str.

Get the thermal flow constitituve model for the zone.

type() → str.

Get the zone type. In 3D it is one of: “brick”, “wedge”, “pyramid”, “dbrick” or “tetra”. In 2D it is either “quadrilateral” or “triangle”.

valid() → bool.

Returns True if this zone is live.

vol() → float.

Get the zone volume (in 3D) or area (in 2D) calculated using the current position of the zone’s gridpoints.

vol_deformed() → float.

Get the volume (in 3D) or area (in 2D) of a zone using gridpoint positions that take into account accumulated gridpoint displacements. This method is meant to be used in a small-strain analysis when deformed zone volumes/areas are required. This method should not be used in a large-strain analysis (an incorrect volume/area will be returned). Use the .vol() of the zone object in large-strain mode.

work_elastic_shear() → float.

Get the zone shear elastic work dissipated.

work_elastic_total() → float.

Get the total elastic work.

work_elastic_vol() → float.

Get the zone volumetric elastic work dissipated.

work_plastic_shear() → float.

Get the zone shear plastic work dissipated.

work_plastic_total() → float.

Get the total plastic work dissipated.

work_plastic_vol() → float.

Get the zone volumetric plastic work dissipated.