API Reference

Copyright (c) 2024-2025 ROCK LAB PRIVATE LIMITED This file is part of “Stresslog” project and is released under the GNU Affero General Public License v3.0 (AGPL-3.0) See the GNU Affero General Public License for more details: <https://www.gnu.org/licenses/agpl-3.0.html>

stresslog.add_curves(well, df, clear=False)

Add all columns from a DataFrame as curves to a Welly Well object.

Parameters:

• well (welly.Well) – The Well object to which curves will be added.

• df (pandas.DataFrame) – DataFrame containing the curves to add. Must include a ‘DEPT’ column for the depth index.

• clear (bool, optional) – If True, clears all existing curves in the well before adding new ones. Default is False.

Returns:

well – The Well object with the new curves added.

Return type:

welly.Well

Notes

If a curve with the same mnemonic already exists in the well, it is skipped.

stresslog.compute_geomech(well, rhoappg=16.33, lamb=0.0008, ul_exp=0.0008, ul_depth=0, a=0.63, nu=0.25, mu=0.65, sfs=1.0, window=1, plotstart=0, plotend=6000, dtml=210, dtmt=60, water=1.0, underbalancereject=1, tecb=0, doi=0, offset=0, dip_dir=0, dip=0, mudtemp=0, res0=0.98, be=0.00014, ne=0.6, dex0=0.5, de=0.00017, nde=0.5, lala=-1.0, lalb=1.0, lalm=5, lale=0.5, lall=5, horsruda=0.77, horsrude=2.93, mabw=90, unitchoice=None, ureg=None, mwvalues=None, flowgradvals=None, fracgradvals=None, flowpsivals=None, fracpsivals=None, attrib=None, flags=None, UCSs=None, forms=None, lithos=None, user_home=None, program_option=None, writeFile=False, aliasdict=None, unitdict=None, debug=False, penetration=False, ten_fac=10, ehmin=None, ehmax=None, writeConfig=True, display=False)

Performs geomechanical calculations, data processing, and pore pressure estimation based on well log data and additional user inputs.

Parameters:

• well (welly.Well) – The well data containing curves for various parameters. It is essential that the curves extend all the way to 0 depth and contain deviation data (even if the well is vertical).

• rhoappg (float, optional) – Density at mudline in g/cc (default is 16.33).

• lamb (float, optional) – Compaction exponent for regions without unloading (default is 0.0008).

• ul_exp (float, optional) – Compaction exponent for regions with unloading (default is 0.0008).

• ul_depth (float, optional) – Depth where unloading starts, in metres (default is 0).

• a (float, optional) – Density compaction exponent for overburden calculations (default is 0.630).

• nu (float, optional) – Poisson’s ratio, used in stress calculations (default is 0.25).

• mu (float, optional) – Coefficient of sliding friction, used in shmin (zoback) calculation (default is 0.65).

• sfs (float, optional) – Shale flag resistivity or GR cutoff, representing the difference between deep and shallow resistivity in ohm.m (default is 1.0).

• window (int, optional) – The window size for down-sampling well data (default is 1).

• plotstart (int, optional) – Starting depth for plotted image (if any), in metres (default is 0).

• plotend (int, optional) – End depth for plotted image (if any), in metres (default is 2000).

• dtml (int, optional) – Delta T at mudline, in microseconds per foot (default is 210).

• dtmt (int, optional) – Delta T of matrix, in microseconds per foot (default is 60).

• res0 (float, optional) – Resistivity at mudline (default is 0.98).

• be (float, optional) – Base exponential coefficient for resistivity gradient calculation (default is 0.00014).

• ne (float, optional) – Exponent for normal resistivity calculations (default is 0.6).

• dex0 (float, optional) – D-exp at mudline (default is 0.5).

• de (float, optional) – Coefficient for drilling exponent gradient calculation (default is 0.00014).

• nde (float, optional) – Exponent for normal drilling exponent calculations (default is 0.5).

• paths (dict, optional) – Dictionary containing paths for saving output files, including plots, CSVs, and models. Keys typically include output_dir, plot_figure, and others for structured saving (default is None).

• water (float, optional) – Water density in g/cc (default is 1.0).

• underbalancereject (int, optional) – Minimum pore pressure gradient (in g/cc) below which underbalanced data is rejected (default is 1).

• tecb (int, optional) – Daines’ parameter related to tectonic stress, used to calculate shmin (default is 0).

• doi (int, optional) – Depth of interest for detailed calculations, in metres (default is 0).

• offset (int, optional) – Azimuth of the maximum horizontal stress (SHMax) in degrees (default is 0).

• dip_dir (int, optional) – Dip direction of the stress tensor in degrees (default is 0).

• dip (int, optional) – Dip angle of the stress tensor in degrees (default is 0).

• mudtemp (int, optional) – Mud temperature, in degrees Celsius (default is 0).

• lala (float, optional) – Parameter for Lal’s cohesion method (default is -1.0).

• lalb (float, optional) – Parameter for Lal’s cohesion method (default is 1.0).

• lalm (int, optional) – Parameter for Lal’s cohesion method (default is 5).

• lale (float, optional) – Parameter for Lal’s cohesion method (default is 0.5).

• lall (int, optional) – Parameter for Lal’s cohesion method (default is 5).

• mabw (float, optional) – Maximum Allowable Breakout Width in degrees (default is 90).

• horsruda (float, optional) – Parameter for horsrud’s stress method (default is 0.77).

• horsrude (float, optional) – Parameter for horsrud’s stress method (default is 2.93).

• unitchoice (list, optional) – <DEPRECATED, will be removed in a future version> List specifying the unit system for file output plots (default is [0, 0, 0, 0, 0]).

• unitdict (dict, optional) – Unit dictionary to be used for unit conversion, default is {‘pressure’:’psi’, ‘strength’:’MPa’, ‘gradient’:’gcc’, ‘length’:’m’}.

• ureg (pint.UnitRegistry, optional) – Unit registry for unit conversions (default is a pint.UnitRegistry with autoconvert_offset_to_baseunit=True).

• mwvalues (list of lists, optional) – Section attributes, including parameters like maximum ECD, casing shoe depth, casing diameter, bit diameter, mud salinity, and bottom-hole temperature (BHT) at the shoe

• flowgradvals (list of lists, optional) – Flow gradient values for different depths (i.e. [emw in g/cc at which kick taken/RFT/DST/whathaveyou, MD]) (default is [[0, 0]]).

• fracgradvals (list of lists, optional) – Fracture gradient values for different depths (i.e. [emw in g/cc at which mud lost/(x)LOT/minifrac/whathaveyou, MD]) (default is [[0, 0]]).

• flowpsivals (list of lists, optional) – Flow pressure values for different depths (i.e. [bhp in psi at which kick taken/RFT/DST/whathaveyou, MD]) (default is [[0, 0]]).

• fracpsivals (list of lists, optional) – Fracture pressure values for different depths (i.e. [bhp in psi at which mud lost/(x)LOT/minifrac/whathaveyou, MD]) (default is [[0, 0]]).

• attrib (list, optional) – Well attributes list. The fields correspond to KB, GL/WD, WL, Latitude, Longitude, BHT, Mud Resistance, Mud filtrate Resistance (Note: the water level parameter will be implemented fully in the future) (default is [1, 0, 0, 0, 0, 0, 0, 0]).

• flags (pandas.DataFrame, optional) – Dataframe containing depths and conditions identified from image logs, such as breakouts or drilling-induced fractures (default is None).

• UCSs (pandas.DataFrame, optional) – Dataframe containing measured depth (MD) and unconfined compressive strength (UCS) values (default is None).

• forms (pandas.DataFrame, optional) – Dataframe containing formation tops and associated formation-specific parameters (default is None).

• lithos (pandas.DataFrame, optional) – Dataframe containing interpreted lithology data and lithology-specific parameters (default is None).

• user_home (str, optional) – Path to the root of output directories (default is ~/Documents).

• program_option (list, optional) – List controlling algorithm behavior. The entries are: dpi (of the saved plots), choice of pore pressure algorithm (0 is sonic, 1 is resistivity, 2 is dexp, 4-9 are best available with the priorities changing), choice of shmin algorithm (0 is daines, 1 is zoback), the last two parameters are reserved for future use. (default is [300, 4, 0, 0, 0]).

• writeFile (bool, optional) – Whether to write results to files in the specified paths (default is True).

• aliasdict (dict, optional) – Dictionary mapping curve mnemonics to standardized aliases (default is None).

• ten_fac (float, optional) – Parameter defining scaling factor from compressive to tensile strength (default 10) can be over-ridden from the lithology input.

• ehmin (float, optional) – Strain in direction of minimum horizontal stress, in absolute or microstrains (default None) if provided overrides the tecb parameter in shmin calculation.

• ehmax (float, optional) – Strain in direction of maximum horizontal stress, in absolute or microstrains (default None) if provided overrides the tecb parameter in shmin calculation.

• writeConfig (bool, optional) – Whether to write config files in the specified paths (default is True)

• display (bool, optional) – Whether to interactively show output during processing (default is False)

Returns:

The tuple contains the following:

• 0 : Well log DataFrame (original and computed values) with mnemonics as headers

• 1 : LAS file as StringIO object containing original and computed values

• 2 : Base64 encoded plot strings for properties calculated at depth of interest (or None if written to files or not calculated at doi=0)

• 3 : Depth of Interest as specified (in meters)

• 4 : Welly object containing all data

Return type:

tuple

Notes

• If writeFile is True, all generated plots and data will be saved to disk.

• If display is True, the stress polygon, directional stability plot, synthetic borehole image, sanding risk plot and well plot will be shown in addition to being saved to disk. writeFile is assumed to be True internally in this case.

• The following dataframes must have fixed formats for their respective columns:

  • forms: Must contain columns in this order:

    ‘Formation Top Measured Depth’, ‘Formation Number’, ‘Formation Name’, ‘GR Cutoff’, ‘Structural Top’, ‘Structural Bottom’, ‘Centroid Ratio’, ‘OWC Depth’, ‘GOC Depth’, ‘Coefficient of thermal expansion bulk’, ‘Alpha’, ‘Beta’, ‘Gamma’, ‘Tectonic Factor’, ‘SH/SV Ratio’, ‘Biot Coefficient’, ‘DT Normal’, ‘Resistivity Normal’, ‘DEX Normal’

  • lithos: Must contain columns in this order: ‘Measured Depth’, ‘Lithology Code’, ‘Poisson Ratio’, ‘Friction Coefficient’, ‘UCS’

  • flags: Must contain columns in this order: [‘Measured Depth’, ‘Condition Code’] - ‘Condition Code’ integer, allowed values:

    0 : No Image log exists 1 : Image log exists, No observations 2 : DITF observed on image log 3 : Breakouts observed on image log 4 : Both DITF and Breakouts observed on image log

  • UCSs: Must contain columns in this order: [‘Measured Depth’, ‘UCS in MPa’]

  Any deviation in column order, or missing values will result in errors during processing.

stresslog.compute_optimal_gradient(tvds, porepressures)

Compute the optimal fluid gradient that best fits the measured pore pressures.

Parameters:

• tvds (array_like) – Array of True Vertical Depths (meters)

• porepressures (array_like) – Array of pore pressures (psi)

Returns:

Optimal fluid gradient (g/cc)

Return type:

float

Notes

• Uses scipy.optimize.minimize to find the optimal gradient

• Handles NaN values in the pore pressure data

• Minimizes the absolute sum of differences between measured and calculated pressures

• Initial guess for gradient is 1.0 g/cc

stresslog.compute_optimal_offset(tvds, porepressures, gradient)

Compute the optimal depth offset that minimizes the difference between measured pore pressures and a hydrostatic gradient.

Parameters:

• tvds (array_like) – Array of True Vertical Depths (meters)

• porepressures (array_like) – Array of pore pressures (psi)

• gradient (float) – Fluid gradient (g/cc)

Returns:

Optimal depth offset (meters)

Return type:

float

Notes

• Uses scipy.optimize.minimize to find the optimal offset

• Handles NaN values in the pore pressure data

• Minimizes the absolute sum of differences between measured and calculated pressures

stresslog.convert_df_tvd(df, well)

Converts the first column of formation or other dataframes from MD to TVD, given a welly.Well object with valid deviation data.

Parameters:

• df (pandas.DataFrame) – The dataframe who’s first column has the measured depths we want to convert.

• well (welly.Well) – Source well object containing the original log data and wellbore information. Must valid deviation data.

Returns:

The dataframe with the first column converted to TVD and column name set to TopTVD

Return type:

pandas.DataFrame

stresslog.create_header(name, uwi, strt, stop, step, comp=None, fld=None, loc=None, cnty=None, stat=None, ctry=None, api=None, date=None, srvc=None, lati=None, long=None, gdat=None, kb='1', gl='0', nully='-999.25')

Create a LAS file header with well information.

Parameters:

• name (str) – Well name

• uwi (str) – Unique Well Identifier

• strt (str) – Start depth

• stop (str) – Stop depth

• step (str) – Depth step size

• comp (str, optional) – Company name

• fld (str, optional) – Field name

• loc (str, optional) – Location description

• cnty (str, optional) – County name

• stat (str, optional) – State name

• ctry (str, optional) – Country name

• api (str, optional) – API number

• date (str, optional) – Log date (DD-MMM-YYYY format)

• srvc (str, optional) – Service company name

• lati (str, optional) – Latitude (in degrees)

• long (str, optional) – Longitude (in degrees)

• gdat (str, optional) – Geodetic datum

• kb (str, optional) – Kelly bushing elevation in meters, by default “1”

• gl (str, optional) – Ground level elevation in meters, by default “0”

• nully (str, optional) – Null value indicator, by default “-999.25”

Returns:

DataFrame containing formatted LAS file header information

Return type:

pandas.DataFrame

stresslog.create_random_well(kb, gl, kop=0, maxangle=0, step=0.15, starter=0, stopper=5500, drop=None, seed=None)

Create a random well object with specified parameters.

Parameters:

• kb (float) – Kelly bushing elevation in meters

• gl (float) – Ground level elevation in meters

• kop (float, optional) – Kickoff point depth in meters, by default 0

• maxangle (float, optional) – Maximum deviation angle in degrees, by default 0

• step (float, optional) – Depth step size in meters, by default 0.15

• drop (list, optional) – List of curves to exclude from output, by default []

Returns:

Well object containing randomly generated log data

Return type:

welly.Well

stresslog.datasets_to_las(path, datasets, custom_units=None, **kwargs)

MIT License

Copyright (c) 2013-2020 Kent Inverarity and contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Write datasets to a LAS file on disk.

Parameters:

• path (Str) – Path to write LAS file to. If None, returns string buffer.

• datasets (Dict['<name>': pd.DataFrame]) – Dictionary maps a dataset name (e.g. ‘Curves’) or ‘Header’ to a pd.DataFrame.

• custom_units (Dict[str, str], optional) – Dictionary mapping curve names to their units. If a curve’s unit is not specified, it defaults to an empty string.

Returns:

• str – if path is None, returns the las file as a string

• None – if path is provided, writes to file and returns None

stresslog.draw(tvd, s1, s2, s3, deltaP, Pp, UCS=0, alpha=0, beta=0, gamma=0, offset=0, nu=0.35, azimuthu=0, inclinationi=0, bt=0, ym=0, delT=0, path=None, ten_fac=10, debug=False, display=False)

Generate wellbore stability plots showing mud weight headroom and breakout widths.

This function creates two polar projection plots: 1. A contour plot showing mud weight headroom in SG units 2. A contour plot showing breakout widths in degrees

The plots are generated for various wellbore orientations (inclination and azimuth) considering in-situ stresses, rock properties, and wellbore conditions.

Parameters:

• tvd (float) – True vertical depth in meters

• s1 (float) – Maximum principal stress

• s2 (float) – Intermediate principal stress

• s3 (float) – Minimum principal stress

• deltaP (float) – Pressure differential (wellbore pressure - pore pressure)

• Pp (float) – Pore pressure

• UCS (float, optional) – Unconfined compressive strength, default 0

• alpha (float, optional) – Principal stress rotation angle alpha in degrees, default 0

• beta (float, optional) – Principal stress rotation angle beta in degrees, default 0

• gamma (float, optional) – Principal stress rotation angle gamma in degrees, default 0

• offset (float, optional) – Azimuthal offset in degrees, default 0

• nu (float, optional) – Poisson’s ratio, default 0.35

• azimuthu (float, optional) – Wellbore azimuth in degrees, default 0

• inclinationi (float, optional) – Wellbore inclination in degrees, default 0

• bt (float, optional) – Biot’s coefficient, default 0

• ym (float, optional) – Young’s modulus, default 0

• delT (float, optional) – Temperature difference, default 0

• path (str, optional) – File path to save the plot. If None, returns the plot object

• debug (bool, optional) – Prints debug statements to console

• display (bool, optional) – Displays the plot in addition to saving

Returns:

• matplotlib.pyplot – If path is None, returns the matplotlib pyplot object containing the stability plots

• None – If path is provided, saves the plot to the specified path and returns None

Notes

The function uses Zhang’s equation (phi = np.arcsin(1-(2*nu))) for wellbore stability analysis. The first plot shows mud weight headroom in SG units with a jet_r colormap. The second plot shows breakout widths in degrees with a jet colormap. Both plots use polar projections with inclination (0-90°) and azimuth (0-360°).

The plots include:

• Contour plots of stability parameters

• Green marker showing the actual wellbore orientation

• Horizontal colorbars with appropriate units

• Title showing TVD and key parameters (UCS, deltaP, deltaT, Nu)

stresslog.drawSP(Sv, Pp, bhp, shmin, UCS=0, phi=0, flag=0, mu=0.65, nu=0.25, bt=0, ym=0, delT=0, PhiBr=15, biot=1, path=None, debug=False, display=False)

Draw a stress polygon visualization for wellbore stability analysis.

Parameters:

• Sv (float) – Vertical stress in MPa

• Pp (float) – Pore pressure in MPa

• bhp (float) – Bottom hole pressure in MPa

• shmin (float) – Minimum horizontal stress in MPa

• UCS (float, optional) – Unconfined compressive strength in MPa, by default 0

• phi (float, optional) – Internal friction angle in radians, by default 0

• flag (int, optional) – Condition flag for stress calculation: 0 - No image log exists 1 - Image log exists, no breakouts or tensile fractures observed 2 - Breakouts observed 3 - Tensile fractures observed 4 - Both breakouts and tensile fractures observed By default 0

• mu (float, optional) – Friction coefficient, by default 0.65

• nu (float, optional) – Poisson’s ratio, by default 0.25

• bt (float, optional) – Linear thermal expansion coefficient, by default 0

• ym (float, optional) – Young’s modulus in MPa, by default 0

• delT (float, optional) – Temperature difference in degrees Celsius, by default 0

• PhiBr (float, optional) – Breakout width in degrees, by default 15

• biot (float, optional) – Biot’s poroelastic constant, by default 1

• path (str, optional) – File path to save the plot, by default None

Returns:

• matplotlib.pyplot – If path is None, returns the matplotlib plot object

• None – If path is provided, saves the plot to the specified path

Notes

The units to the function are not strictly in MPa, other units will work just fine, as long as all units are compatible with each other (for example Sv, Pp, bhp and ucs can all be in psi and the plot will also be in psi).

This function creates a stress polygon visualization that includes:

• Stress regime domains (Normal, Strike-slip, Reverse)

• Breakout analysis with UCS variations

• Drilling-induced tensile fracture (DITF) analysis

• Stress bounds and interpolated values

stresslog.find_TVD(well, md)

Calculate True Vertical Depth (TVD) from Measured Depth (MD).

This function uses a cubic spline interpolation based on the well’s deviation survey to find the TVD corresponding to a given MD.

Parameters:

• well (welly.Well) – The welly well object containing valid deviation data (MD and TVDM curves).

• md (float) – The Measured Depth (MD) at which to calculate the TVD.

Returns:

The calculated True Vertical Depth (TVD).

Return type:

float

stresslog.getAlignedStress(sx, sy, sz, alpha, beta, gamma, azim, inc)

Calculate the stress tensor aligned to a given well azimuth and inclination (Borehole coordinate system)

Parameters:

• sx (float) – Stress component in x-direction

• sy (float) – Stress component in y-direction

• sz (float) – Stress component in z-direction

• alpha (float) – First rotation angle in degrees

• beta (float) – Second rotation angle in degrees

• gamma (float) – Third rotation angle in degrees

• azim (float) – Azimuth angle in degrees

• inc (float) – Inclination angle in degrees

Returns:

3x3 stress tensor in the rotated coordinate system

Return type:

ndarray

stresslog.getColumnHeights(tvd, structop, goc, owc)

Calculate the heights of water, oil, and gas columns based on depth parameters.

Parameters:

• tvd (float) – True Vertical Depth - the depth at which to calculate column heights

• structop (float) – Structural top - the shallowest depth of the structure

• goc (float) – Gas-Oil Contact depth

• owc (float) – Oil-Water Contact depth

Returns:

A list containing three heights [h1, h2, h3] where:

• h1: height of water column (negative value)

• h2: height of oil column (negative value)

• h3: height of gas column (negative value)

Return type:

list of float

Notes

• All depths should be in meters

• The function handles invalid inputs by setting appropriate defaults

• If goc or owc are NaN, 0, or less than structop, they are set to structop

• If goc > owc, goc is set to owc as this is physically impossible

stresslog.getEuler(alpha, strike, dip)

Optimize beta and gamma angles to match given strike and dip.

Parameters:

• alpha (float) – Fixed rotation angle alpha in degrees

• strike (float) – Target strike angle in degrees

• dip (float) – Target dip angle in degrees

Returns:

beta_optfloat

Optimized beta angle in degrees

gamma_optfloat

Optimized gamma angle in degrees

Return type:

tuple

Notes

Uses Nelder-Mead optimization to find beta and gamma angles that produce the desired strike and dip angles.

stresslog.getGasDensity(p, t=100)

Calculate gas density using the ideal gas law.

Parameters:

• p (float) – Pressure (psi)

• t (float, optional) – Temperature (Celsius), default=100

Returns:

Gas density (kg/m³)

Return type:

float

Notes

• Uses ideal gas law (PV = nRT)

• Assumes methane (CH4) with molar mass of 16.04 g/mol

• Converts input pressure from psi to Pa

• Converts input temperature from Celsius to Kelvin

stresslog.getHoop(inc, azim, s1, s2, s3, deltaP, Pp, ucs, alpha=0, beta=0, gamma=0, nu=0.35, bt=0, ym=0, delT=0, path=None, ten_fac=10)

Calculate and plot hoop stresses around a wellbore circumference.

This function computes various stress components around the wellbore wall and generates a plot showing hoop stresses, stress angles, and identifies regions of potential failure. It uses modified Zhang equations for stress calculations.

Parameters:

• inc (float) – Wellbore inclination in degrees

• azim (float) – Wellbore azimuth in degrees

• s1 (float) – Maximum principal stress

• s2 (float) – Intermediate principal stress

• s3 (float) – Minimum principal stress

• deltaP (float) – Pressure differential (wellbore pressure - pore pressure)

• Pp (float) – Pore pressure

• ucs (float) – Unconfined compressive strength

• alpha (float, optional) – Principal stress rotation angle alpha in degrees, default 0

• beta (float, optional) – Principal stress rotation angle beta in degrees, default 0

• gamma (float, optional) – Principal stress rotation angle gamma in degrees, default 0

• nu (float, optional) – Poisson’s ratio, default 0.35

• bt (float, optional) – Biot’s coefficient, default 0

• ym (float, optional) – Young’s modulus, default 0

• delT (float, optional) – Temperature difference, default 0

• path (str, optional) – File path to save the plot. If None, returns the plot object

Returns:

If path is provided:

• crushndarray

  Binary array indicating compressive failure regions (1 for failure)

• fracndarray

  Binary array indicating tensile failure regions (1 for failure)

• minstressint

  Index of minimum stress location in first 180 degrees

• maxstressint

  Index of maximum stress location in first 180 degrees

• angle_minfloat

  Principal stress angle at minimum stress location

• angle_min_oppositefloat

  Principal stress angle at opposite of minimum stress location

• anglendarray

  Array of principal stress angles around wellbore

If path is None:

Returns all above plus matplotlib.pyplot object as the last element

Return type:

tuple

Notes

The function calculates:

• Tangential (hoop) stresses

• Axial stresses

• Shear stresses

• Principal stress angles

• Potential failure regions (both tensile and compressive)

The plot shows:

• Principal stress angles

• Effective hoop stresses (STT - Pp)

• Effective axial stresses (SZZ - Pp)

• Shear stresses (TTZ)

Uses Zhang’s equations with internal friction angle calculated from Poisson’s ratio:

phi = arcsin(1-2nu)

stresslog.getHydrostaticPsi(tvd, gradient)

Calculate hydrostatic pressure in psi at a given depth for a given pressure gradient.

Parameters:

• tvd (float) – True Vertical Depth (meters)

• gradient (float) – Fluid gradient (g/cc)

Returns:

Hydrostatic pressure (psi)

Return type:

float

Notes

• Converts input depth from meters to feet

• Uses conversion factors to calculate pressure in psi

• Formula: pressure = gradient * 8.3454063545262 * tvd * 3.28084 * 0.052

stresslog.getOrit(s1, s2, s3, alpha, beta, gamma)

Calculate principal stress directions after stress tensor rotation.

Parameters:

• s1 (float) – First principal stress magnitude

• s2 (float) – Second principal stress magnitude

• s3 (float) – Third principal stress magnitude

• alpha (float) – First rotation angle in degrees

• beta (float) – Second rotation angle in degrees

• gamma (float) – Third rotation angle in degrees

Returns:

3x3 matrix where each column represents a principal stress direction in the rotated coordinate system. The columns correspond to the vertical, north, and east directions respectively.

Return type:

ndarray

stresslog.getPPfromTop(sealintegrity, stressratio, overburden, oilgrad, watergrad, structop, goc, owc, tvd)

Calculate hydraulic pore pressure using a simplified method based on fluid gradients and column heights.

Parameters:

• sealintegrity (float) – Seal integrity pressure (psi)

• stressratio (float) – Stress ratio (dimensionless)

• overburden (float) – Overburden pressure (psi)

• oilgrad (float) – Oil gradient (g/cc)

• watergrad (float) – Water gradient (g/cc)

• structop (float) – Structural top depth (m)

• goc (float) – Gas-Oil Contact depth (m)

• owc (float) – Oil-Water Contact depth (m)

• tvd (float) – True Vertical Depth (m)

Returns:

Calculated pore pressure (psi)

Return type:

float

Notes

• Uses a constant conversion factor k = 0.145037737731556 for unit conversion

• Gas density is calculated based on pressure at the top of the structure

• Assumes constant gradients for oil and water

stresslog.getPPfromTopRecursive(sealintegrity, stressratio, overburden, oilgrad, watergrad, structop, goc, owc, tvd)

Calculate hydraulic pore pressure using a recursive method that accounts for gas density variation with depth.

Parameters:

• sealintegrity (float) – Seal integrity pressure (psi)

• stressratio (float) – Stress ratio (dimensionless)

• overburden (float) – Overburden pressure (psi)

• oilgrad (float) – Oil gradient (g/cc)

• watergrad (float) – Water gradient (g/cc)

• structop (float) – Structural top depth (m)

• goc (float) – Gas-Oil Contact depth (m)

• owc (float) – Oil-Water Contact depth (m)

• tvd (float) – True Vertical Depth (m)

Returns:

Calculated pore pressure (psi)

Return type:

float

Notes

• Uses recursive calculation for gas pressure to account for gas compressibility

• Steps through the gas column in 1-meter increments

• More accurate than getPPfromTop for thick gas columns

• Assumes constant gradients for oil and water

stresslog.getRota(alpha, beta, gamma)

Generate a rotation matrix from Euler angles.

Parameters:

• alpha (float) – First rotation angle in degrees

• beta (float) – Second rotation angle in degrees

• gamma (float) – Third rotation angle in degrees

Returns:

3x3 rotation matrix

Return type:

ndarray

stresslog.getSP(Sv, Pp, bhp, shmin, UCS=0, phi=0, flag=0, mu=0.6, nu=0.25, bt=0, ym=0, delT=0, PhiBr=15, biot=1)

Calculate SHmax using stress polygon logic, returns said value without visualisation.

Parameters:

• Sv (float) – Vertical stress in MPa

• Pp (float) – Pore pressure in MPa

• bhp (float) – Bottom hole pressure in MPa

• shmin (float) – Minimum horizontal stress in MPa

• UCS (float, optional) – Unconfined compressive strength in MPa, by default 0

• phi (float, optional) – Internal friction angle in radians, by default 0

• flag (int, optional) –

  Condition flag for stress calculation:

  • 0 : No image log exists

  • 1 : Image log exists, no breakouts or tensile fractures observed

  • 2 : Breakouts observed

  • 3 : Tensile fractures observed

  • 4 : Both breakouts and tensile fractures observed

  By default 0

• mu (float, optional) – Friction coefficient, by default 0.6

• nu (float, optional) – Poisson’s ratio, by default 0.25

• bt (float, optional) – Linear thermal expansion coefficient, by default 0

• ym (float, optional) – Young’s modulus in MPa, by default 0

• delT (float, optional) – Temperature difference in degrees Celsius between hole-wall and circulating fluid, by default 0

• PhiBr (float, optional) – Breakout width in degrees, by default 15

• biot (float, optional) – Biot’s poroelastic constant, by default 1

Returns:

A list containing three float values:

• minSH: Minimum Max horizontal stress (SHMax)(MPa)

• maxSH: Maximum Max horizontal stress (SHMax)(MPa)

• midSH: Best Estimate Max horizontal stress (SHMAx)(MPa)

Return type:

list

Notes

The units to the function are not strictly in MPa, other units will work just fine, as long as all units are compatible with each other (for example Sv, Pp, bhp and ucs can all be in psi and the returned SHMax will also be in psi) This function performs the same stress polygon calculations as drawSP but returns the numerical results without creating a visualization.

stresslog.getSigmaTT(s1, s2, s3, alpha, beta, gamma, azim, inc, theta, deltaP, Pp, nu=0.35, bt=0, ym=0, delT=0)

Calculate stress components at a point on the wall of an inclined borehole.

Parameters:

• s1 (float) – First principal stress magnitude

• s2 (float) – Second principal stress magnitude

• s3 (float) – Third principal stress magnitude

• alpha (float) – First rotation angle in degrees

• beta (float) – Second rotation angle in degrees

• gamma (float) – Third rotation angle in degrees

• azim (float) – Borehole azimuth in degrees

• inc (float) – Borehole inclination in degrees

• theta (float) – Angular position on borehole wall in degrees

• deltaP (float) – Difference between mud pressure and pore pressure

• Pp (float) – Pore pressure

• nu (float, optional) – Poisson’s ratio, default is 0.35

• bt (float, optional) – Linear thermal expansion coefficient, default is 0

• ym (float, optional) – Young’s modulus, default is 0

• delT (float, optional) – Temperature difference, default is 0

Returns:

Sttfloat

Tangential stress

Szzfloat

Axial stress

Ttzfloat

Shear stress

STMaxfloat

Maximum principal stress

STMinfloat

Minimum principal stress

omegafloat

Angle between maximum principal stress and borehole axis

oritlist

List containing orientation angles [NorthAzimuth, NorthInclination, EastAzimuth, EastInclination, VerticalInclination, VerticalAzimuth]

Return type:

tuple

Notes

This function converts far-field stress tensor to at-wall stress state at a single point on the wall of an inclined borehole, accounting for thermal and poroelastic effects.

stresslog.getStens(sx, sy, sz, alpha, beta, gamma, debug=False)

Calculate the stress tensor in the NED (Geographic) Coordinate System.

Parameters:

• sx (float) – Stress component in x-direction

• sy (float) – Stress component in y-direction

• sz (float) – Stress component in z-direction

• alpha (float) – First rotation angle in degrees

• beta (float) – Second rotation angle in degrees

• gamma (float) – Third rotation angle in degrees

Returns:

Three 1D arrays representing the rows of the rotated stress tensor (σxx, σxy, σxz), (σyx, σyy, σyz), (σzx, σzy, σzz)

Return type:

tuple

Notes

Optionaly prints eigenvalues, eigenvectors, vector dip, dip direction, and vertical/horizontal stress components.

stresslog.getStrikeDip(alpha, beta, gamma)

Calculate strike, dip, and dip direction from Euler angles.

Parameters:

• alpha (float) – First rotation angle in degrees

• beta (float) – Second rotation angle in degrees

• gamma (float) – Third rotation angle in degrees

Returns:

strike_directionfloat

Strike direction in degrees

dip_anglefloat

Dip angle in degrees

dip_directionfloat

Dip direction in degrees

Return type:

tuple

stresslog.getVertical(sx, sy, sz, alpha=0, beta=0, gamma=0)

Calculate the vertical stress component after stress tensor rotation.

Parameters:

• sx (float) – Stress component in x-direction

• sy (float) – Stress component in y-direction

• sz (float) – Stress component in z-direction

• alpha (float, optional) – Rotation angle alpha in degrees, default is 0

• beta (float, optional) – Rotation angle beta in degrees, default is 0

• gamma (float, optional) – Rotation angle gamma in degrees, default is 0

Returns:

Vertical stress component with imaginary part representing maximum horizontal stress depending on faulting regime:

• Normal slip: imaginary part is max(σyy, σxx)

• Strike slip: imaginary part is max(σyy, σxx)

• Reverse slip: imaginary part is 0

Return type:

complex

stresslog.get_Dxc(ROP, RPM, WOB, BTDIA, ECD, pn)

Calculate corrected d-exponent.

Parameters:

• ROP (float) – Rate of penetration in ft/hr

• RPM (float) – Rotations per minute

• WOB (float) – Weight on bit in lbs

• BTDIA (float) – Bit diameter in inches

• ECD (float) – Equivalent circulating density

• pn (float) – Hydrostatic pressure gradient, in same units as ECD

Returns:

Corrected d-exponent if greater than 0.1, otherwise NaN

Return type:

float

Notes

This is the scalar version of the corrected d-exponent calculation. For vectorized operations, use get_Dxc_vec.

stresslog.get_Dxc_vec(ROP, RPM, WOB, BTDIA, ECD, pn)

Calculate corrected d-exponent with vectorized inputs.

Parameters:

• ROP (array_like) – Rate of penetration in ft/hr

• RPM (array_like) – Rotations per minute

• WOB (array_like) – Weight on bit in lbs

• BTDIA (array_like) – Bit diameter in inches

• ECD (array_like) – Equivalent circulating density

• pn (array_like) – Hydrostatic pressure gradient, in same units as ECD

Returns:

Array of corrected d-exponent values

Return type:

ndarray

Notes

Vectorized version of the corrected d-exponent calculation. All inputs are broadcast to compatible shapes before calculation. Arrays must be of the same length if used.

stresslog.get_OBG_pascals_vec(tvd, tvdbgl, tvdmsl, rhogcc, water, glwd)

Vectorized calculation of comprehensive overburden stress considering offshore and onshore scenarios.

Parameters:

• tvd (array-like) – True Vertical Depth

• tvdbgl (array-like) – True Vertical Depth Below Ground Level

• tvdmsl (array-like) – True Vertical Depth from Mean Sea Level

• rhogcc (array-like) – Density in g/cc

• water (float) – Water density in g/cc

• glwd (float) – Ground Level/Water Depth in meters (negative for offshore)

Returns:

Arrays of integrho (Rho_a), integrhopsift, and ObgTppg

Return type:

tuple

Notes

• Inputs may be scalars (floats) or 1D arrays. Scalars are broadcast across arrays automatically.

• All array inputs must have the same length; mismatched lengths will raise a ValueError due to NumPy broadcasting rules.

stresslog.get_PP_grad_Zhang_gcc_vec(ObgTgcc, pn, b, tvdbgl, c, mudline, matrick, deltmu0, dalm, biot=1)

Calculate pressure gradient using Zhang’s method with vectorized inputs.

Parameters:

• ObgTgcc (array_like) – Overburden gradient in g/cc

• pn (array_like) – Normal (Hydrostatic) pressure gradient in g/cc

• b (float/array_like) – Compaction coefficient for unloading case

• tvdbgl (array_like) – True vertical depth below ground level in metres

• c (float/array_like) – Compaction coefficient for loading case

• mudline (float/array_like) – interval travel time at mudline (uspf)

• matrick (float/array_like) – interval travel time in matrix (0 porosity case) (uspf)

• deltmu0 (array_like) – Interval travel time at top of unloading condition in uspf

• dalm (array_like) – P-sonic log array in uspf

• biot (array_like, optional) – Biot coefficient, defaults to 1

Returns:

Pressure gradient calculated using Zhang’s method

Return type:

ndarray

Notes

This function applies Zhang’s method for pressure gradient calculation with support for vectorized operations. All inputs are broadcast to compatible shapes before calculation. Arrays must be of the same length if used.

stresslog.get_PPgrad_Dxc_gcc(ObgTgcc, pn, d, nde, tvdbgl, D0, Dxc, biot=1)

Calculate pressure gradient using d-exponent method.

Parameters:

• ObgTgcc (float) – Overburden gradient in g/cc

• pn (float) – Normal pressure in g/cc

• d (float) – d-exponent parameter

• nde (float) – d-exponent power

• tvdbgl (float) – True vertical depth below ground level

• D0 (float) – d-exponent value at surface

• Dxc (float) – Corrected d-exponent

• biot (float, optional) – Biot coefficient, defaults to 1

Returns:

Pressure gradient calculated using d-exponent method

Return type:

float

Notes

This is the scalar version of the d-exponent pressure gradient calculation. For vectorized operations, use get_PPgrad_Dxc_gcc_vec.

stresslog.get_PPgrad_Dxc_gcc_vec(ObgTgcc, pn, d, nde, tvdbgl, D0, Dxc, biot=1)

Calculate pressure gradient using d-exponent method with vectorized inputs.

Parameters:

• ObgTgcc (array_like) – Overburden gradient in g/cc

• pn (array_like) – Normal pressure in g/cc

• d (float/array_like) – d-exponent parameter

• nde (float/array_like) – d-exponent power

• tvdbgl (array_like) – True vertical depth below ground level

• D0 (float/array_like) – Reference d-exponent value

• Dxc (array_like) – Corrected d-exponent

• biot (float/array_like, optional) – Biot coefficient, defaults to 1

Returns:

Pressure gradient calculated using d-exponent method

Return type:

ndarray

Notes

Vectorized version of the d-exponent pressure gradient calculation. All inputs are broadcast to compatible shapes before calculation. Arrays must be of the same length if used.

stresslog.get_PPgrad_Eaton_gcc(ObgTgcc, pn, be, ne, tvdbgl, res0, resdeep, biot=1)

Calculate pressure gradient using Eaton’s method.

Parameters:

• ObgTgcc (float) – Overburden gradient in g/cc

• pn (float) – Normal (Hydrostatic) pressure gradient in g/cc

• be (float) – Eaton’s parameter b

• ne (float) – Eaton’s exponent

• tvdbgl (float) – True vertical depth below ground level

• res0 (float) – Resistivity at mudline

• resdeep (float) – Deep resistivity measurement of the given sample

• biot (float, optional) – Biot coefficient, defaults to 1

Returns:

Pressure gradient calculated using Eaton’s method

Return type:

float

Notes

This is the single-point version of the Eaton pressure gradient calculation. For vectorized operations, use get_PPgrad_Eaton_gcc_vec.

stresslog.get_PPgrad_Eaton_gcc_vec(ObgTgcc, pn, be, ne, tvdbgl, res0, resdeep, biot=1)

Calculate pressure gradient using Eaton’s method with vectorized inputs.

Parameters:

• ObgTgcc (array_like) – Overburden gradient in g/cc

• pn (array_like) – Normal (Hydrostatic) pressure gradient in g/cc

• be (float/array_like) – Eaton’s parameter b

• ne (float/array_like) – Eaton’s exponent

• tvdbgl (array_like) – True vertical depth below ground level in metres

• res0 (float/array_like) – Resistivity at mudline in ohm.m

• resdeep (array_like) – Deep resistivity measurements log in ohm.m

• biot (float/array_like, optional) – Biot coefficient, defaults to 1

Returns:

Pressure gradient calculated using Eaton’s method

Return type:

ndarray

Notes

Vectorized version of the Eaton pressure gradient calculation. All inputs are broadcast to compatible shapes before calculation. Arrays must be of the same length if used.

stresslog.get_PPgrad_Zhang_gcc(ObgTgcc, pn, b, tvdbgl, c, mudline, matrick, deltmu0, dalm, biot=1)

Calculate pore pressure gradient using Zhang’s method for a single point.

Parameters:

• ObgTgcc (float) – Overburden gradient in gcc units

• pn (float) – Normal (Hydrostatic) pressure gradient in g/cc

• b (float) – Compaction coefficient for unloading case

• tvdbgl (float) – True vertical depth below ground level

• c (float) – Compaction coefficient for loading case

• mudline (float) – interval travel time at mudline (uspf)

• matrick (float) – matrix interval travel time (uspf)

• deltmu0 (float) – interval travel time as recorded on P-sonic log at the depth considered to be the top of unloading condition

• dalm (float) – travel time as recorded on P-sonic log (uspf) for the given depth

• biot (float, optional) – Biot’s coefficient, by default 1

Returns:

Calculated pore pressure gradient in gcc units

Return type:

float

Notes

Implements Zhang’s method for calculating pore pressure gradient. The calculation varies based on the relationship between b and c coefficients.

stresslog.get_Shmin_grad_Daine_ppg(nu2, ObgTppg, biot, ppgZhang, tecB)

Scalar calculation of fracture gradient pressure for a single sample.

Parameters:

• nu2 (float) – Poisson’s ratio

• ObgTppg (float) – Overburden gradient in ppg

• biot (float) – Biot’s coefficient

• ppgZhang (float) – Zhang’s pore pressure in ppg

• tecB (float) – Tectonic factor

Returns:

Fracture gradient pressure in ppg

Return type:

float

stresslog.get_Shmin_grad_Daine_ppg_vec(nu2, ObgTppg, biot, ppgZhang, tecB)

Vectorized calculation of fracture gradient pressure.

Parameters:

• nu2 (array-like) – Poisson’s ratio

• ObgTppg (array-like) – Overburden gradient in ppg

• biot (array-like) – Biot’s coefficient

• ppgZhang (array-like) – Zhang’s pore pressure in ppg

• tecB (array-like) – Tectonic factor

Returns:

Fracture gradient pressure in ppg

Return type:

numpy.ndarray

Notes

• Inputs may be scalars (floats) or 1D arrays. Scalars are broadcast across arrays automatically.

• All array inputs must have the same length; mismatched lengths will raise a ValueError due to NumPy broadcasting rules.

stresslog.get_analog(well, current_forms, target_forms, kb, gl, dev=None, kop=0, ma=0, rob=0.1, azi=0, debug=False, td=5000)

Generate an analog well by transforming log data from an existing well according to specified formation depths and wellbore geometry parameters. This function creates a new well object with transformed log data that maintains the character of the original logs while honoring new formation tops and a new wellbore trajectory.

The function performs several key operations:

1. Converts MD (Measured Depth) formations to TVD (True Vertical Depth) if necessary

2. Creates a blank wellbore with specified geometry

3. Transforms the original well’s log data to match new formation depths

4. Generates a new well object with the transformed data

Parameters:

• well (welly.Well) – Source well object containing the original log data and wellbore information. Must contain basic log curves (e.g., GR, RHOB, etc.) and valid deviation data.

• current_forms (pandas.DataFrame) –

  DataFrame containing the current formation tops information. Must include columns for depth values and formation names. Depths can be in either MD or TVD (specified by column name). Example format:

  • TopMD Name

  • 1690 Alpha

  • 2380 Beta

  • … …

• target_forms (pandas.DataFrame) – DataFrame containing the target formation tops information for the analog well. Must follow the same format as current_forms. These depths represent where formations should appear in the analog well.

• kb (float) – Kelly Bushing elevation in meters for the analog well. Used as the reference point for depth measurements.

• gl (float) – Ground Level elevation in meters for the analog well. Must be less than or equal to kb if onshore and equal to negetive water depth if offshore

• dev (array-like, optional) – Custom deviation survey data for the analog well. If provided, overrides the kop, ma, rob, and azi parameters. Format should be compatible with welly.Well deviation data. Default is None.

• kop (float, optional) – Kick-Off Point depth in meters. Depth at which the wellbore begins to deviate from vertical. Must be >= 0. Default is 0.

• ma (float, optional) – Maximum angle (deviation) in degrees. The maximum inclination angle the wellbore will reach. Must be between 0 and 90. Default is 0 (vertical well).

• rob (float, optional) – Rate Of Build in degrees per meter. Rate at which the wellbore builds angle from the KOP. Typical values range from 0.1 to 3.0 degrees/meter. Default is 0.1.

• azi (float, optional) – Azimuth in degrees. The compass direction of the wellbore deviation. Must be between 0 and 360. Default is 0 (North).

• debug (bool, optional) –

  If True, enables debug mode which:

  • Prints intermediate dataframes

  • Generates diagnostic plots

  • Saves additional output files

  • Provides verbose console output

  Default is False.

Returns:

A tuple containing two elements:

• welly.Well : The created analog well object with transformed log data and new trajectory information

• io.StringIO : A StringIO object containing the LAS file representation of the analog well

Return type:

tuple

Notes

• The function uses fuzzy matching to find the formation names column in the dataframes, so the column name can be “Name”, “Formation_Name”, etc.

• Log data is resampled to maintain consistent spacing throughout the transformation

• The function preserves the character and relationships between different log curves while shifting them to new depths

• The transformation process interpolates depths linearly between formation tops, while preserving thickness below the deepest formation top

• Formation top names must be consistent between current_forms and target_forms

• If a formation has pinched out, it should still be included in both dataframes with its depth matching either the overlying or underlying formation based on geological interpretation

stresslog.get_dlis_data(path, aliases=None, depthunits='m', resample_interval=0.1, flatten=False, debug=False)

Extract data from a DLIS file with unit conversion and header processing.

Parameters:

• path (str) – Path to the DLIS file.

• aliases (dict or None) – Dictionary mapping alias names to lists of possible mnemonics. If None, all 1-dimensional curves present in the DLIS file will be extracted. Multi-dimensional curves will be flattened into individual sub-curves.

• depthunits (str, optional) – Desired depth units for output. Options are ‘m’ (meters) or ‘f’ (feet). Default is ‘m’.

Returns:

• combined_df (pandas.DataFrame) – Combined data from all frames with depth as index and specified curves as columns. When aliases is None, includes all 1-dimensional curves found in the DLIS file. Depth values are converted according to depthunits parameter.

• c_units (dict) – Dictionary mapping curve names to their units.

• header_df (pandas.DataFrame) – DataFrame containing header information.

• parameters (dict) – Dictionary containing raw parameter values from the DLIS file.

stresslog.get_dlis_header(path)

Extract header information from a DLIS file.

Parameters:

path (str) – Path to the DLIS file.

Returns:

A DataFrame containing two columns: - Mnemonic: Channel names from the DLIS file - Description: Long names/descriptions of the channels

Return type:

pandas.DataFrame

stresslog.get_las_from_dlis(path, aliases, depthunit='m', step=0.15, debug=False)

DEPRECATED in favor of get_well_from_dlis

stresslog.get_principal_stress(sx, sy, sz, dalpha=0, dbeta=0, dgamma=0)

Estimate the principal stresses (s1, s2, s3) such that their rotated stress tensor matches the given stresses in the geographic coordinate system.

Parameters:

• sx (float) – shmin in the geographic coordinate system.

• sy (float) – SHMAX in the geographic coordinate system.

• sz (float) – Vertical stress.

• dalpha (float, optional) – Euler angle alpha, in degrees. Default is 0

• dbeta (float, optional) – Euler angle beta, in degrees. Default is 0.

• dgamma (float, optional) – Euler angle gamma, in degrees. Default is 0.

Returns:

• s1 (float) – Optimized principal stress along the first principal direction.

• s2 (float) – Optimized principal stress along the second principal direction.

• s3 (float) – Optimized principal stress along the third principal direction.

Notes

The beta and gamma angles are used to provide info about the ‘tilt’ (non-verticality) of the stress state.

stresslog.getwelldev(string_las=None, wella=None, deva=None, kickoffpoint=None, final_angle=None, rateofbuild=None, azimuth=None, step=None)

Calculate well deviation data and update well object with TVD information.

Parameters:

• string_las (str, optional) – LAS file content as string

• wella (welly.Well, optional) – Well object to process

• deva (pandas.DataFrame, optional) – Existing deviation data with columns ‘MD’, ‘INC’, ‘AZIM’

• kickoffpoint (float, optional) – Depth at which well deviation begins

• final_angle (float, optional) – Target inclination angle in degrees

• rateofbuild (float, optional) – Rate of angle build in degrees per meter

• azimuth (float, optional) – Well azimuth in degrees

Returns:

Updated well object with deviation data and TVD calculations

Return type:

welly.Well

Notes

Either provide string_las or wella, and either deva or kickoffpoint+final_angle+rateofbuild+azimuth

stresslog.lade(sx, sy, sz, txy, tyz, tzx, phi, cohesion, pp)

Calculate the Lade failure criterion with numpy array support.

Parameters:

• sx (array_like) – Normal stress in x-direction

• sy (array_like) – Normal stress in y-direction

• sz (array_like) – Normal stress in z-direction

• txy (array_like) – Shear stress in xy-plane

• tyz (array_like) – Shear stress in yz-plane

• tzx (array_like) – Shear stress in zx-plane

• phi (array_like) – Internal friction angle in radians

• cohesion (array_like) – Rock cohesion strength

• pp (array_like) – Pore pressure

Returns:

Lade failure criterion value (F)

Return type:

array_like

stresslog.lade_failure(sx, sy, sz, txy, tyz, tzx, phi, cohesion, pp)

Calculate the Modified Lade failure criterion with pore pressure correction.

Parameters:

• sx (float or array_like) – Normal stress in x-direction

• sy (float or array_like) – Normal stress in y-direction

• sz (float or array_like) – Normal stress in z-direction

• txy (float or array_like) – Shear stress in xy-plane

• tyz (float or array_like) – Shear stress in yz-plane

• tzx (float or array_like) – Shear stress in zx-plane

• phi (float) – Internal friction angle in radians

• cohesion (float) – Rock cohesion strength

• pp (float) – Pore pressure

Returns:

Lade failure criterion value (F2)

Return type:

float or array_like

stresslog.mod_lad_cmw(sxx, syy, szz, txy, tyz, tzx, theta, phi, cohesion, pp)

Calculate the modified Lade critical mud weight with pore pressure correction in the wellbore coordinate system. The stress tensor should already have been rotated to be in the borehole coordinate system.

Parameters:

• sxx (float or array_like) – Normal stress component in x-direction

• syy (float or array_like) – Normal stress component in y-direction

• szz (float or array_like) – Normal stress component in z-direction

• txy (float or array_like) – Shear stress component in xy-plane

• tyz (float or array_like) – Shear stress component in yz-plane

• tzx (float or array_like) – Shear stress component in zx-plane

• theta (float) – Wellbore angle in degrees

• phi (float) – Internal friction angle in radians

• cohesion (float) – Rock cohesion strength

• pp (float) – Pore pressure

Returns:

Critical wellbore pressure (Pw)

Return type:

float or array_like

stresslog.mod_lad_cmw2(sxx, syy, szz, txy, tyz, tzx, theta, phi, cohesion, pp, nu)

Calculate modified Lade critical mud weight with pore pressure and Poisson’s ratio corrections. The stress tensor should already have been rotated to be in the borehole coordinate system

Parameters:

• sxx (float or array_like) – Normal stress component in x-direction

• syy (float or array_like) – Normal stress component in y-direction

• szz (float or array_like) – Normal stress component in z-direction

• txy (float or array_like) – Shear stress component in xy-plane

• tyz (float or array_like) – Shear stress component in yz-plane

• tzx (float or array_like) – Shear stress component in zx-plane

• theta (float) – Wellbore angle in degrees

• phi (float) – Internal friction angle in radians

• cohesion (float) – Rock cohesion strength

• pp (float) – Pore pressure

• nu (float) – Poisson’s ratio

Returns:

Critical wellbore pressure (Pw) with Poisson’s ratio correction

Return type:

float or array_like

stresslog.mogi(sx, sy, sz)

Calculate the Mogi failure criterion for stress components with numpy array support.

Parameters:

• sx (array_like) – Normal stress in x-direction

• sy (array_like) – Normal stress in y-direction

• sz (array_like) – Normal stress in z-direction

Returns:

Mogi failure criterion value (F)

Return type:

array_like

stresslog.mogi_failure(s1, s2, s3)

Calculate the Mogi failure criterion for principal stresses.

Parameters:

• s1 (float or array_like) – Maximum principal stress

• s2 (float or array_like) – Intermediate principal stress

• s3 (float or array_like) – Minimum principal stress

Returns:

Mogi failure criterion value (F)

Return type:

float or array_like

stresslog.mohr_failure(s1, s3, cohesion, phi)

Calculate the Mohr-Coulomb failure criterion.

Parameters:

• s1 (float or array_like) – Maximum principal stress

• s3 (float or array_like) – Minimum principal stress

• cohesion (float) – Rock cohesion strength

• phi (float) – Internal friction angle in radians

Returns:

Mohr-Coulomb failure criterion value (F)

Return type:

float or array_like

stresslog.plot_logs_labels(data, styles, points=None, pointstyles=None, y_min=None, y_max=None, width=15, height=10, label_height=20, dpi=100, output_dir=os.path.join(user_home, 'Stresslog_plots'), to_plotly=False, title=None, details=None, display=False)

Wrapper function that calls plot_logs three times to generate the main plot and the top/bottom label plots.

Parameters:

• data (pandas.DataFrame) – DataFrame where each column corresponds to a curve to be plotted.

• styles (dict) –

  Dictionary mapping column names from data to style attributes. Each value should be a dictionary containing keys such as color, linewidth, style, track, left, right, and type.

  Example

  {'lithology1': {"color": "green", "linewidth": 1.5, "style": '.', "track": 0, "left": 0, "right": 150, "type": 'linear'}}

• points (pandas.DataFrame, optional) – DataFrame where each column corresponds to sparse points to be plotted.

• pointstyles (dict, optional) –

  Dictionary mapping column names from points to style attributes. Each value should be a dictionary containing keys such as color, pointsize, symbol, track, left, right, type, and unit.

  Example

  {'ucs': {'color': 'blue', 'pointsize': 10, 'symbol': 'o', 'track': 4, 'left': 0, 'right': 100, 'type': 'linear', 'unit': 'MPa'}}

• y_min (float, optional) – Minimum value of the y-axis (depth).

• y_max (float, optional) – Maximum value of the y-axis (depth).

• width (float, default=15) – Width of the figure in inches.

• height (float, default=10) – Height of the main plot in inches.

• label_height (float, default=20) – Height scaling factor for label placement.

• dpi (int, default=100) – Dots per inch for saved figures.

• output_dir (str, default=os.path.join(user_home, "Stresslog_plots")) – Directory where plot files will be saved.

• to_plotly (bool, default=False) – If True, also generate a Plotly version of the figure.

• title (str, optional) – Wellbore title to annotate on the figure.

• details (dict, optional) – Metadata about depth and reference information. Expected keys: unit, type, reference, KB, GL. Defaults to {"unit":"metres","type":"TVD","reference":"KB/DF","KB":0,"GL":0}.

• display (bool, default=False) – If True, display the matplotlib figure interactively.

Returns:

• fig (matplotlib.figure.Figure) – The Matplotlib figure object of the main plot.

• axes (list of matplotlib.axes.Axes) – List of axes objects corresponding to each track in the main plot.

stresslog.plot_sanding(sigmamax, sigmamin, sigma_axial, pp, ucs, k0, nu, biot=1, path=None, display=False)

Create a sanding analysis plot comparing Zhang and Willson criteria.

Parameters:

• sigmamax (float) – Maximum principal stress

• sigmamin (float) – Minimum principal stress

• sigma_axial (float) – Axial stress

• pp (float) – Pore pressure

• ucs (float) – Unconfined compressive strength

• k0 (float) – Earth stress ratio

• nu (float) – Poisson’s ratio

• biot (float, optional) – Biot’s coefficient (default is 1)

• path (str, optional) – Path to save the plot (default is None)

Returns:

Plot object if path is None, otherwise saves plot to specified path

Return type:

matplotlib.pyplot

stresslog.plotfrac(data, path=None, dia=8.5, debug=False)

Generate detailed fracture morphology plot with depth calculations.

Parameters:

• data (tuple) –

  A tuple containing:

  • tvdfloat

    True vertical depth

  • frndarray

    Array of fracture indicators

  • anglesndarray

    Array of angles

  • minanglefloat

    Minimum angle value

  • maxanglefloat

    Maximum angle value

• path (str, optional) – File path to save the plot. If None, plot is not saved to file.

• dia (float, optional) – Hole Diameter in inches to be used for the calculation, in inches, 8.5 by default

Returns:

A tuple containing two ndarrays:

• cdepthsndarray

  Corrected fracture depths (likely fracture region).

• fdepthsndarray

  Final fracture depths (full fracture trend, including unlikely regions).

Return type:

tuple

stresslog.remove_curves(well, mnemonics_to_remove, debug=False)

Remove specified curves from a Welly Well object.

Parameters:

• well (welly.Well) – The Well object from which curves will be removed.

• mnemonics_to_remove (list of str) – List of curve mnemonics to remove from the well.

• debug (bool, optional) – If True, prints a message for each removed curve. Default is False.

Returns:

well – The Well object with the specified curves removed.

Return type:

welly.Well

Notes

If a mnemonic in mnemonics_to_remove does not exist in the well, it is ignored.

stresslog.willson_sanding_cwf(sigmamax, sigmamin, pp, ucs, nu, biot=1)

Calculate the Willson critical wellbore flowing pressure for sanding prediction.

Parameters:

• sigmamax (float or array_like) – Maximum principal stress

• sigmamin (float or array_like) – Minimum principal stress

• pp (float or array_like) – Pore pressure

• ucs (float) – Unconfined compressive strength

• nu (float) – Poisson’s ratio

• biot (float, optional) – Biot’s coefficient (default is 1)

Returns:

Critical wellbore flowing pressure

Return type:

float or array_like

stresslog.zhang_sanding_cwf(sigmamax, sigmamin, pp, ucs, k0, nu, biot=1)

Calculate the Zhang critical wellbore flowing pressure for sanding prediction.

Parameters:

• sigmamax (float or array_like) – Maximum principal stress

• sigmamin (float or array_like) – Minimum principal stress

• pp (float or array_like) – Pore pressure

• ucs (float) – Unconfined compressive strength

• k0 (float) – Earth stress ratio

• nu (float) – Poisson’s ratio

• biot (float, optional) – Biot’s coefficient (default is 1)

Returns:

Critical wellbore flowing pressure

Return type:

float or array_like