GEOS Utilities

The geos-utils python package defines utilities for all GEOS python packages including a logger, GEOS constants, basic functions, and unit management tools.

API

geos.utils.ConnectionSet module

Defines connection set and connection set collection data structures.

class geos.utils.ConnectionSet.ConnectionSet(cellIdRef, connectedCellIds)[source]

Bases: object

Define connection set data structure.

A ConnectionSet stores information of connection between a reference cell and adjacent cells. Cell information relies on unique ids, and each connected cell is associated with a side according to connection face normal vector.

Parameters:

cellIdRef (int) – reference cell id.
connectedCellIds (int) – map of connected cell ids with the side.

addConnectedCells(connectedCellsToAdd)[source]

Add connected cells to the existing map of connected cells.

The addConnectedCells() method adds element(s) to the dictionary if the cell Id is not in the dictionary. If the cell Id is in the dictionary, it updates the cell Id with the new side value.

Parameters:: connectedCellsToAdd (dict[int, bool]) – connected cells to add.

copy()[source]

Create a deep copy of self.

Returns:: copy of ConnectionSet
Return type:: ConnectionSet

getCellIdRef()[source]

Get the reference cell id.

Returns:: reference cell id.
Return type:: int

getConnectedCellIds()[source]

Get connected cell ids.

Returns:: map of connected cell ids with side.
Return type:: int

setCellIdRef(cellIdRef)[source]

Set the reference cell id.

Parameters:: cellIdRef (int) – reference cell id.

setConnectedCellIds(connectedCellIds)[source]

Set the connected cell ids.

Parameters:: connectedCellIds (dict[int, bool]) – map of connected cell ids with side.

class geos.utils.ConnectionSet.ConnectionSetCollection[source]

Bases: MutableSet

Define a collection of ConnectionSet.

Because ConnectionSet relies on cell unique id, the collection imposes uniqueness of reference cell id.

add(item)[source]

Add a ConnectionSet to the collection.

Parameters:: item (ConnectionSet) – ConnectionSet to add.

addMultiple(items)[source]

Add an iterable of ConnectionSet to the collection.

Parameters:: items (Iterable[ConnectionSet]) – list of ConnectionSet to add.

containsCellIdRef(cellIdRef)[source]

Test if a ConnectionSet with cellIdRef is present in the collection.

Parameters:: cellIdRef (int) – reference cell id
Returns:: True if a ConnectionSet is present, False otherwise.
Return type:: bool

containsEqual(item)[source]

Test if a ConnectionSet is present in the collection.

Both th reference cell id and connected cell dictionnary must match the input ConnectionSet.

Parameters:: item (ConnectionSet) – ConnectionSet to add.

discard(item)[source]

Remove a ConnectionSet to the collection.

ConnectionSet is removed if both reference cell id and connected cell dictionnary match an element of the collection.

Parameters:: item (ConnectionSet) – ConnectionSet to remove.

discardCellIdRef(cellIdRef)[source]

Remove a ConnectionSet to the collection using the reference cell id.

Parameters:: cellIdRef (int) – reference cell id to remove.

get(cellIdRef)[source]

Get ConnectionSet from reference cell id.

Parameters:: cellIdRef (int) – reference cell id
Returns:: ConnectionSet with cellIdRef.
Return type:: Optional[ConnectionSet]

getReversedConnectionSetCollection()[source]

Get the set of reversed connection set.

Returns:: reversed collection of ConnectionSet
Return type:: ConnectionSetCollection

replace(item)[source]

Replace a ConnectionSet if another one with the same cellIdRef exists.

Parameters:: item (ConnectionSet) – ConnectionSet to add.

update(item)[source]

Update or add a ConnectionSet to the collection.

Parameters:: item (ConnectionSet) – ConnectionSet

geos.utils.enumUnits module

class geos.utils.enumUnits.Density(value)[source]

Bases: Enum

An enumeration.

G_PER_CUBIC_CENTIMETER = <geos.utils.enumUnits.Unit object>

KG_PER_CUBIC_METER = <geos.utils.enumUnits.Unit object>

POUND_PER_BBL = <geos.utils.enumUnits.Unit object>

class geos.utils.enumUnits.Length(value)[source]

Bases: Enum

An enumeration.

FEET = <geos.utils.enumUnits.Unit object>

KILOMETER = <geos.utils.enumUnits.Unit object>

METER = <geos.utils.enumUnits.Unit object>

MILE = <geos.utils.enumUnits.Unit object>

class geos.utils.enumUnits.Mass(value)[source]

Bases: Enum

An enumeration.

KG = <geos.utils.enumUnits.Unit object>

MEGATON = <geos.utils.enumUnits.Unit object>

POUND = <geos.utils.enumUnits.Unit object>

TON = <geos.utils.enumUnits.Unit object>

class geos.utils.enumUnits.MassRate(value)[source]

Bases: Enum

An enumeration.

KG_PER_DAY = <geos.utils.enumUnits.Unit object>

KG_PER_HOUR = <geos.utils.enumUnits.Unit object>

KG_PER_SECOND = <geos.utils.enumUnits.Unit object>

MTPA = <geos.utils.enumUnits.Unit object>

TON_PER_DAY = <geos.utils.enumUnits.Unit object>

class geos.utils.enumUnits.NoUnit(value)[source]

Bases: Enum

An enumeration.

SAME = <geos.utils.enumUnits.Unit object>

class geos.utils.enumUnits.Permeability(value)[source]

Bases: Enum

An enumeration.

DARCY = <geos.utils.enumUnits.Unit object>

MILLI_DARCY = <geos.utils.enumUnits.Unit object>

SQUARE_METER = <geos.utils.enumUnits.Unit object>

class geos.utils.enumUnits.Pressure(value)[source]

Bases: Enum

An enumeration.

BAR = <geos.utils.enumUnits.Unit object>

GPA = <geos.utils.enumUnits.Unit object>

KPA = <geos.utils.enumUnits.Unit object>

MPA = <geos.utils.enumUnits.Unit object>

PA = <geos.utils.enumUnits.Unit object>

PSI = <geos.utils.enumUnits.Unit object>

class geos.utils.enumUnits.Temperature(value)[source]

Bases: Enum

An enumeration.

CELSIUS = <geos.utils.enumUnits.Unit object>

FAHRENHEIT = <geos.utils.enumUnits.Unit object>

K = <geos.utils.enumUnits.Unit object>

class geos.utils.enumUnits.Time(value)[source]

Bases: Enum

An enumeration.

DAY = <geos.utils.enumUnits.Unit object>

HOUR = <geos.utils.enumUnits.Unit object>

MONTH = <geos.utils.enumUnits.Unit object>

SECOND = <geos.utils.enumUnits.Unit object>

YEAR = <geos.utils.enumUnits.Unit object>

class geos.utils.enumUnits.Unit(conversionMultiplier, conversionAdder, unitLabel)[source]

Bases: object

Unit enumeration.

Parameters:

conversionMultiplier (float) – conversion multiplier
conversionAdder (float) – conversion adder
unitLabel (str) – symbol of the unit.

class geos.utils.enumUnits.Volume(value)[source]

Bases: Enum

An enumeration.

BBL = <geos.utils.enumUnits.Unit object>

CUBIC_FEET = <geos.utils.enumUnits.Unit object>

CUBIC_METER = <geos.utils.enumUnits.Unit object>

class geos.utils.enumUnits.VolumetricRate(value)[source]

Bases: Enum

An enumeration.

BBL_PER_DAY = <geos.utils.enumUnits.Unit object>

CUBIC_METER_PER_DAY = <geos.utils.enumUnits.Unit object>

CUBIC_METER_PER_HOUR = <geos.utils.enumUnits.Unit object>

CUBIC_METER_PER_SECOND = <geos.utils.enumUnits.Unit object>

geos.utils.enumUnits.convert(number, unitObj)[source]

Converts a float number that has SI unit to a specific unit.

Parameters:

number (float) – Number to convert.
unitObj (Unit) – Object containing conversion multiplier and adder.

Returns:

number converted to the correct unit.

Return type:

float

geos.utils.enumUnits.enumerationDomainUnit(enumObj)[source]

Get the xml code corresponding to unit enum object for drop down list.

Parameters:: enumObj (Enum) – Unit enum object.
Returns:: xml text.
Return type:: str

geos.utils.enumUnits.getPropertyUnitEnum(propertyName)[source]

Get the Unit enum from property name.

Parameters:: propertyName (str) – name of the property.
Returns:: Unit enum.
Return type:: Enum

geos.utils.enumUnits.getSIUnits()[source]

Get the dictionary of property Names:Units.

Generates a dict where the keys are meta-properties like pressure, mass etc … and where the values are Unit composed of a conversion factor and its unit associated. Here, the conversion factor will always be 1.0 and the unit will be the SI associate because we work with SI units.

Returns:: dictionary of unit names as keys and Unit enum as value.
Return type:: dict[str, Unit]

geos.utils.geometryFunctions module

Functions to permform geometry calculations.

geos.utils.geometryFunctions.computeAngleFromPoints(pt1, pt2, pt3)[source]

Compute angle from 3 points.

Parameters:

pt1 (npt.NDArray[np.float64]) – First point
pt2 (npt.NDArray[np.float64]) – Second point
pt3 (npt.NDArray[np.float64]) – Third point

Returns:

Angle

Return type:

float

geos.utils.geometryFunctions.computeAngleFromVectors(vec1, vec2)[source]

Compute angle from 2 vectors.

Parameters:

vec1 (npt.NDArray[np.float64]) – First vector
vec2 (npt.NDArray[np.float64]) – Second vector

Returns:

angle

Return type:

float

geos.utils.geometryFunctions.computeCoordinatesInNewBasis(vec, changeOfBasisMatrix)[source]

Computes the coordinates of a matrix from a basis B in the new basis B’.

Parameters:

vec (npt.NDArray[np.floating[Any]]) – Vector to compute the new coordinates
changeOfBasisMatrix (npt.NDArray[np.floating[Any]]) – Change of basis matrix

Returns:

The new coordinates of the matrix in the basis B’.

Return type:

npt.NDArray[np.floating[Any]]

geos.utils.geometryFunctions.computeCosineFromVectors(vec1, vec2)[source]

Compute cosine from 2 vectors.

Parameters:

vec1 (npt.NDArray[np.float64]) – First vector
vec2 (npt.NDArray[np.float64]) – Second vector

Returns:

Cosine

Return type:

float

geos.utils.geometryFunctions.computeNormalFromPoints(pt1, pt2, pt3)[source]

Compute the normal of a plane defined from 3 points.

Parameters:

pt1 (npt.NDArray[np.float64]) – First point
pt2 (npt.NDArray[np.float64]) – Second point
pt3 (npt.NDArray[np.float64]) – Third point

Returns:

Normal vector coordinates

Return type:

npt.NDArray[np.float64]

geos.utils.geometryFunctions.computeNormalFromVectors(vec1, vec2)[source]

Compute the normal of a plane defined from 2 vectors.

Parameters:

vec1 (npt.NDArray[np.float64]) – First vector
vec2 (npt.NDArray[np.float64]) – Second vector

Returns:

Normal vector coordinates

Return type:

npt.NDArray[np.float64]

geos.utils.geometryFunctions.computePlaneFrom3Points(pt1, pt2, pt3)[source]

Compute the 4 coefficients of a plane equation.

Let’s defined a plane from the following equation: ax + by + cz + d = 0. This function determines a, b, c, d from 3 points of the plane.

Parameters:

pt1 (npt.NDArray[np.floating[Any]]) – 1st point of the plane.
pt2 (npt.NDArray[np.floating[Any]]) – 2nd point of the plane.
pt3 (npt.NDArray[np.floating[Any]]) – 3rd point of the plane.

Returns:

Tuple of the 4 coefficients.

Return type:

tuple[float, float, float, float]

geos.utils.geometryFunctions.getCellSideAgainstPlane(cellPtsCoords, planePt, planeNormal)[source]

Get the side of input cell against input plane.

Input plane is defined by a point on it and its normal vector.

Parameters:

cellPtsCoords (npt.NDArray[np.floating[Any]]) – Coordinates of the vertices of the cell to get the side.
planePt (npt.NDArray[np.floating[Any]]) – Point on the plane.
planeNormal (npt.NDArray[np.floating[Any]]) – Normal vector to the plane.

Returns:

True if the cell is in the direction of the normal vector, False otherwise.

Return type:

bool

geos.utils.geometryFunctions.getChangeOfBasisMatrix(basisFrom, basisTo)[source]

Get the change of basis matrix from basis basisFrom to basis basisTo.

Let’s define the basis (basisFrom) (b1, b2, b3) and basis (basisTo) (c1, c2, c3) where b1, b2, b3, and c1, c2, c3 are the vectors of the basis in the canonic form. This method returns the change of basis matrix P from basisFrom to basisTo.

The coordinates of a vector Vb(vb1, vb2, vb3) from the basis B in the basis C is then Vc = P.Vb

Parameters:

basisFrom (tuple[npt.NDArray[np.floating[Any]], npt.NDArray[np.floating[Any]], npt.NDArray[np.floating[Any]]]) – Origin basis
basisTo (tuple[npt.NDArray[np.floating[Any]], npt.NDArray[np.floating[Any]], npt.NDArray[np.floating[Any]]]) – Destination basis

Returns:

Change of basis matrix.

Return type:

npt.NDArray[np.floating[Any]]

geos.utils.geometryFunctions.getPointSideAgainstPlane(ptCoords, planePt, planeNormal)[source]

Get the side of input point against input plane.

Input plane is defined by a point on it and its normal vector.

Parameters:

ptCoords (npt.NDArray[np.floating[Any]]) – Coordinates of the point to get the side.
planePt (npt.NDArray[np.floating[Any]]) – Point on the plane.
planeNormal (npt.NDArray[np.floating[Any]]) – Normal vector to the plane.

Returns:

True if the point is in the direction of the normal vector, False otherwise.

Return type:

bool

geos.utils.GeosOutputsConstants module

GeosOutputsConstants module defines useful constant names such as attribute names, domain names, phase types, and the lists of attribute names to process.

Warning

Names may need to be updated when modifications occur in the GEOS code.

Todo

If possible, link GEOS names directly with GEOS code instead of redefining them here.

class geos.utils.GeosOutputsConstants.AttributeEnum(value)[source]

Bases: Enum

An enumeration.

Define the enumeration to store attribute properties.

Parameters:

attributeName (str) – name of the attribute
nbComponent (int) – number of component: 1 is scalar attribute, >1 is vectorial attribute
onPoints (bool) – location of the attribute: on Points (True) or on Cells (False)

class geos.utils.GeosOutputsConstants.ComponentNameEnum(value)[source]

Bases: Enum

An enumeration.

NONE = ('',)

NORMAL_TANGENTS = ('normal', 'tangent1', 'tangent2', 'T1T2', 'NT2', 'NT1')

XYZ = ('XX', 'YY', 'ZZ', 'YZ', 'XZ', 'XY')

class geos.utils.GeosOutputsConstants.FluidPrefixEnum(value)[source]

Bases: Enum

Define usual names used for the fluid phase.

FLUID = 'fluid'

GAS = 'gas'

WATER = 'water'

class geos.utils.GeosOutputsConstants.GeosDomainNameEnum(value)[source]

Bases: Enum

Name of the nodes in the MultiBlock data tree.

FAULT_DOMAIN_NAME = 'SurfaceElementRegion'

VOLUME_DOMAIN_NAME = 'CellElementRegion'

WELL_DOMAIN_NAME = 'WellElementRegion'

class geos.utils.GeosOutputsConstants.GeosLogOutputsEnum(value)[source]

Bases: Enum

Define the keywords in Geos log.

PHASE = 'phase'

class geos.utils.GeosOutputsConstants.GeosMeshOutputsEnum(value)[source]

Bases: AttributeEnum

Attribute names that come from Geos.

Define the names of Geos outputs, the number of components for vectorial attributes, and the location (Point or Cell) in the mesh

Define the enumeration to store attribute properties.

Parameters:

attributeName (str) – name of the attribute
nbComponent (int) – number of component: 1 is scalar attribute, >1 is vectorial attribute
onPoints (bool) – location of the attribute: on Points (True) or on Cells (False)

BULK_MODULUS = ('bulkModulus', 1, False)

CELL_ID = ('Cell ID', 1, False)

DELTA_PRESSURE = ('deltaPressure', 1, False)

DISPLACEMENT_JUMP = ('displacementJump', 3, False)

ELEMENT_CENTER = ('elementCenter', 1, False)

GRAIN_BULK_MODULUS = ('bulkModulusGrains', 1, False)

MASS = ('mass', 1, False)

PERMEABILITY = ('permeability', 1, False)

POINT = ('Points', 3, True)

POINTS_ID = ('Point ID', 1, True)

POROSITY = ('porosity', 1, False)

POROSITY_INI = ('porosityInitial', 1, False)

PRESSURE = ('pressure', 1, False)

ROCK_DENSITY = ('density', 1, False)

SHEAR_MODULUS = ('shearModulus', 1, False)

STRESS_EFFECTIVE = ('stressEffective', 6, False)

TOTAL_DISPLACEMENT = ('totalDisplacement', 4, True)

TRACTION = ('traction', 3, False)

VTK_ORIGINAL_CELL_ID = ('vtkOriginalCellIds', 1, False)

WATER_DENSITY = ('water_density', 1, False)

class geos.utils.GeosOutputsConstants.GeosMeshSuffixEnum(value)[source]

Bases: Enum

Define the suffix of attributes in Geos output mesh.

BIOT_COEFFICIENT_SUFFIX = '_biotCoefficient'

BULK_MODULUS_SUFFIX = '_bulkModulus'

DENSITY_SUFFIX = '_density'

GRAIN_BULK_MODULUS_SUFFIX = '_grainBulkModulus'

PERMEABILITY_SUFFIX = '_permeability'

PHASE_DENSITY_SUFFIX = '_phaseDensity'

PHASE_FRACTION_SUFFIX = '_phaseFraction'

PHASE_MASS_DENSITY_SUFFIX = '_phaseMassDensity'

PHASE_VISCOSITY_SUFFIX = '_phaseViscosity'

POROSITY_REF_SUFFIX = '_referencePorosity'

POROSITY_SUFFIX = '_porosity'

SHEAR_MODULUS_SUFFIX = '_shearModulus'

STRAIN_SUFFIX = 'strain'

STRESS_SUFFIX = '_stress'

SURFACE_MINUS_SUFFIX = '_Minus'

SURFACE_PLUS_SUFFIX = '_Plus'

class geos.utils.GeosOutputsConstants.OutputObjectEnum(value)[source]

Bases: Enum

Kind of objects present in GEOS pvd output.

FAULTS = 'Faults'

VOLUME = 'Volume'

WELLS = 'Wells'

geos.utils.GeosOutputsConstants.PHASE_SEP = '_': Phase separator in Geos output log file.

class geos.utils.GeosOutputsConstants.PhaseTypeEnum(value)[source]

Bases: Enum

An enumeration.

Define the main phases and associated property suffix.

Parameters:

phaseType (str) – name of the type of phase
attributes (tuple[str,...]) – list of attributes

FLUID = ('Fluid', ('_phaseDensity', '_phaseViscosity', '_phaseFraction', '_phaseMassDensity'))

ROCK = ('Rock', ('_density', '_stress', '_bulkModulus', '_shearModulus', '_porosity', '_referencePorosity', '_permeability'))

UNKNOWN = ('Other', ())

class geos.utils.GeosOutputsConstants.PostProcessingOutputsEnum(value)[source]

Bases: AttributeEnum

Compute attributes enumeration.

Define the names of post-processing outputs, the number of components for vectorial attributes, and the location (Point or Cell) in the mesh

Define the enumeration to store attribute properties.

Parameters:

attributeName (str) – name of the attribute
nbComponent (int) – number of component: 1 is scalar attribute, >1 is vectorial attribute
onPoints (bool) – location of the attribute: on Points (True) or on Cells (False)

ADJACENT_CELL_SIDE = ('SurfaceAdjacentCells', 1, False)

BIOT_COEFFICIENT = ('biotCoefficient', 1, False)

BIOT_COEFFICIENT_INITIAL = ('biotCoefficientInitial', 1, False)

BLOCK_INDEX = ('blockIndex', 1, False)

BULK_MODULUS_INITIAL = ('bulkModulusInitial', 1, False)

COMPRESSIBILITY = ('compressibilityCoefficient', 1, False)

COMPRESSIBILITY_OED = ('compressibilityCoefficient_oed', 1, False)

COMPRESSIBILITY_REAL = ('compressibilityCoefficient_real', 1, False)

CRITICAL_PORE_PRESSURE = ('porePressureCritical_real', 1, False)

CRITICAL_PORE_PRESSURE_THRESHOLD = ('porePressureThreshold_real', 1, False)

CRITICAL_TOTAL_STRESS_RATIO = ('totalStressRatioCritical_real', 1, False)

LITHOSTATIC_STRESS = ('stressLithostatic', 1, False)

OEDOMETRIC_MODULUS = ('oedometricModulus', 1, False)

POISSON_RATIO = ('poissonRatio', 1, False)

POISSON_RATIO_INITIAL = ('poissonRatioInitial', 1, False)

RSP_OED = ('rsp_oed', 1, False)

RSP_REAL = ('rsp_real', 6, False)

SCU = ('SCU', 1, False)

SHEAR_MODULUS_INITIAL = ('shearModulusInitial', 1, False)

SPECIFIC_GRAVITY = ('specificGravity', 1, False)

STRAIN_ELASTIC = ('strainElastic', 6, False)

STRESS_EFFECTIVE_INITIAL = ('stressEffectiveInitial', 6, False)

STRESS_EFFECTIVE_RATIO_OED = ('stressEffectiveRatio_oed', 1, False)

STRESS_EFFECTIVE_RATIO_REAL = ('stressEffectiveRatio_real', 1, False)

STRESS_TOTAL = ('stressTotal', 6, False)

STRESS_TOTAL_DELTA = ('deltaStressTotal', 6, False)

STRESS_TOTAL_INITIAL = ('stressTotalInitial', 6, False)

STRESS_TOTAL_RATIO_REAL = ('stressTotalRatio_real', 1, False)

TOTAL_STRESS_RATIO_THRESHOLD = ('totalStressRatioThreshold_real', 1, False)

YOUNG_MODULUS = ('youngModulus', 1, False)

YOUNG_MODULUS_INITIAL = ('youngModulusInitial', 1, False)

geos.utils.GeosOutputsConstants.getAttributeToTransferFromInitialTime()[source]

Get the list of attributes to copy from initial time step.

Returns:: dictionary where attribute names are keys and copied names are values
Return type:: dict[str,str]

geos.utils.GeosOutputsConstants.getRockSuffixRenaming()[source]

Get the list of attributes to rename according to suffix.

Returns:: dictionary where suffix are keys and new names are values
Return type:: dict[str,str]

geos.utils.algebraFunctions module

The algebraFunctions module of geos-utils package defines methods to switch from vector <> matrix and conversely, following GEOS outputs conventions.

geos.utils.algebraFunctions.getAttributeMatrixFromVector(attrArray)[source]

Get the matrix of attribute values from the vector.

Matrix to vector conversion is the following:

if input vector size is 3:
\[\begin{split}(v1, v2, v3) => \\begin{bmatrix} v0 & 0 & 0 \\ 0 & v1 & 0 \\ 0 & 0 & v2 \\end{bmatrix}\end{split}\]
if input vector size is 9:
\[\begin{split}(v1, v2, v3, v4, v5, v6, v7, v8, v9) => \\begin{bmatrix} v1 & v6 & v5 \\ v9 & v2 & v4 \\ v8 & v7 & v3 \\end{bmatrix}\end{split}\]
if input vector size is 6 (symmetrical tensor):
\[\begin{split}(v1, v2, v3, v4, v5, v6) => \\begin{bmatrix} v1 & v6 & v5 \\ v6 & v2 & v4 \\ v5 & v4 & v3 \\end{bmatrix}\end{split}\]

Note

In the case of 3 x 3 tensors, GEOS is currently only implemented for symmetrical cases.

Parameters:: attrArray (npt.NDArray[np.float64]) – Vector of attribute values.
Raises:: ValueError – The input vector must be of size 3, 9 or 6 (symmetrical case).
Returns:: The matrix of attribute values.
Return type:: npt.NDArray[np.float64]

geos.utils.algebraFunctions.getAttributeVectorFromMatrix(attrMatrix, size)[source]

Get the vector of attribute values from the matrix.

Matrix to vector conversion is the following:

3x3 diagonal matrix:
\[\begin{split}\\begin{bmatrix} M00 & 0 & 0 \\ 0 & M11 & 0 \\ 0 & 0 & M22 \\end{bmatrix} => (M00, M11, M22)\end{split}\]
3x3 Generic matrix:
\[\begin{split}\\begin{bmatrix} M00 & M01 & M02 \\ M10 & M11 & M12 \\ M20 & M21 & M22 \\end{matrix} => (M00, M11, M22, M12, M02, M01, M21, M20, M10)\end{split}\]
Symmetric case
\[\begin{split}\\begin{bmatrix} M00 & M01 & M02 \\ M01 & M11 & M12 \\ M02 & M12 & M22 \\end{bmatrix} => (M00, M11, M22, M12, M02, M01)\end{split}\]

Note

In the case of 3 x 3 tensors, GEOS is currently only implemented for symmetrical cases.

Parameters:

attrMatrix (npt.NDArray[np.float64]) – Matrix of attribute values.
size (int) – Size of the final vector. Values accepted are 3, 9 or 6.

Raises:

ValueError – The output vector size requested can only be 3, 9 or 6.
ValueError – Input matrix shape must be (3,3).

Returns:

Vector of attribute values.

Return type:

npt.NDArray[np.float64]

geos.utils.Logger module

Logger module manages logging tools.

Code was modified from <https://stackoverflow.com/questions/384076/how-can-i-color-python-logging-output>

It also include adaptor strategy to make vtkLogger behave as a logging’s logger. Indeed, C++ adapted class is based on private Callback assignement which is not compatible with logging python’s logic.

Usage:

# near logger definition
from vtkmodules.vtkCommonCore import vtkLogger

vtkLogger.SetStderrVerbosity(vtkLogger.VERBOSITY_TRACE)
logger.addFilter(RegexExceptionFilter())

...

# near VTK calls
with VTKCaptureLog() as captured_log:
    vtkcalls..
    captured_log.seek(0)  # be kind let's just rewind
    captured = captured_log.read().decode()

logger.error(captured.strip())

class geos.utils.Logger.CountWarningHandler[source]

Bases: Handler

Create an handler to count the warnings logged.

Init the handler.

emit(record)[source]

Count all the warnings logged.

Parameters:: record (logging.LogRecord) – Record.

class geos.utils.Logger.CustomLoggerFormatter(use_color=False)[source]

Bases: Formatter

Custom formatter for the logger.

Warning

Colors do not work in the output message window of Paraview.

To use it:

logger = logging.getLogger( "Logger name", use_color=False )
# Ensure handler is added only once, e.g., by checking logger.handlers
if not logger.handlers:
    ch = logging.StreamHandler()
    ch.setFormatter(CustomLoggerFormatter())
    logger.addHandler(ch)

Initialize the log formatter.

Parameters:: use_color (bool) – If True, use color-coded log formatters. Defaults to False.

FORMATS_COLOR = {10: '\x1b[38;20m%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)\x1b[0m', 20: '\x1b[32;20m%(asctime)s - %(name)s - %(levelname)s - %(message)s\x1b[0m', 30: '\x1b[33;20m%(asctime)s - %(name)s - %(levelname)s - %(message)s\x1b[0m', 40: '\x1b[31;20m%(asctime)s - %(name)s - %(levelname)s - %(message)s\x1b[0m', 50: '\x1b[31;1m%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)\x1b[0m', 60: '\x1b[32;20m%(name)s - %(levelname)s - %(message)s\x1b[0m'}: format for each logger output type with colors

FORMATS_PLAIN = {10: '%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)', 20: '%(asctime)s - %(name)s - %(levelname)s - %(message)s', 30: '%(asctime)s - %(name)s - %(levelname)s - %(message)s', 40: '%(asctime)s - %(name)s - %(levelname)s - %(message)s', 50: '%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)', 60: '%(name)s - %(levelname)s - %(message)s'}: format for each logger output type without colors (e.g., for Paraview)

bold_red = '\x1b[31;1m'

format(record)[source]

Return the format according to input record.

Parameters:: record (logging.LogRecord) – record
Returns:: format as a string
Return type:: str

format1 = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'

format2 = '%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)'

format_results = '%(name)s - %(levelname)s - %(message)s'

green = '\x1b[32;20m'

grey = '\x1b[38;20m'

red = '\x1b[31;20m'

reset = '\x1b[0m'

yellow = '\x1b[33;20m'

class geos.utils.Logger.RegexExceptionFilter[source]

Bases: Filter

Class to regexp VTK messages rethrown into logger by VTKCaptureLog.

This transforms silent VTK errors into catchable Python exceptions.

Init filter with class based pattern as this is patch to logging logic.

filter(record)[source]

Filter VTK Error from stdErr.

Parameters:: record (loggging.LogRecord) – record that logger will provide as evaluated
Raises:: VTKError(geos.utils.Error) if a pattern symbol is caught in the stderr. –

pattern = '\\bERR\\|'

geos.utils.Logger.VTKCaptureLog()[source]

Hard way of adapting C-like vtkLogger to logging class by throwing in stderr and reading back from it.

Returns:: Buffering os stderr.
Return type:: Generator

geos.utils.Logger.getLogger(title, use_color=False)[source]

Return the Logger with pre-defined configuration.

This function is now idempotent regarding handler addition. Calling it multiple times with the same title will return the same logger instance without adding more handlers if one is already present.

Example:

# module import
import Logger

# logger instantiation
logger :Logger.Logger = Logger.getLogger("My application")

# logger use
logger.debug("debug message")
logger.info("info message")
logger.warning("warning message")
logger.error("error message")
logger.critical("critical message")
logger.results("results message")

Parameters:

title (str) – Name of the logger.
use_color (bool) – If True, configure the logger to output with color. Defaults to False.

Returns:

logger

Return type:

Logger

geos.utils.Logger.results(self, message, *args, **kws)[source]

Logs a message with the custom ‘RESULTS’ severity level.

This level is designed for summary information that should always be visible, regardless of the logger’s verbosity setting.

Parameters:

self (logging.Logger) – The logger instance.
message (str) – The primary log message, with optional format specifiers (e.g., “Found %d issues.”).
*args – The arguments to be substituted into the message string.
**kws – Keyword arguments for special functionality.

geos.utils.PhysicalConstants module

Define default values of usefull physical constants.

geos.utils.PhysicalConstants.DEFAULT_FRICTION_ANGLE_DEG = 10.0: default friction angle (deg)

geos.utils.PhysicalConstants.DEFAULT_FRICTION_ANGLE_RAD = 0.17453292519943295: default friction angle (rad)

geos.utils.PhysicalConstants.DEFAULT_GRAIN_BULK_MODULUS = 38000000000.0: default grain bulk modulus is that of Quartz (Pa)

geos.utils.PhysicalConstants.DEFAULT_ROCK_COHESION = 0.0: default rock cohesion - fractured case - (Pa)

geos.utils.PhysicalConstants.EPSILON = 1e-06: epsilon

geos.utils.PhysicalConstants.GRAVITY = 9.81: gravity (m/s)

geos.utils.PhysicalConstants.WATER_DENSITY = 1000.0: water density (kg/m³)

geos.utils.PhysicalConstants.WATER_DYNAMIC_VISCOSITY = 0.001: water dynamic viscosity (kg.m^-1/s^-1 = Pa.s)

geos.utils.PhysicalConstants.WATER_KINEMATIC_VISCOSITY = 1e-06: water kinematic viscosity (m²/s)

geos.utils.UnitRepository module

class geos.utils.UnitRepository.UnitRepository(userPropertiesUnitChoice=None)[source]

Bases: object

Unit repository.

Input example : { “pressure”: 4, “bhp”: 4,”stress”: 3, “length”: 2, …}
Output example{ “pressure”: Pressure.BAR.value, “bhp”: Pressure.BAR.value,
“stress”: Pressure.MPA.value, “length”: Lenght.FEET.value, … }

These Pressure.BAR.value corresponds to Unit objects that have a conversion multiplier and a conversion adder, and also a unit label.

Parameters:

userPropertiesUnitChoice (dict[str, int], Optional) –

dictionary of unit user choices.

Defaults {}.

getPropertiesUnit()[source]

Access the m_propertiesUnit attribute.

Returns:: dictionary of unit as values for each property as keys.
Return type:: dict[str, Unit]

initPropertiesUnit()[source]: Initialize the attribute m_propertiesUnit.