API Reference

Model

class warmth.model.Model

Main model class

property parameters: Parameters

Model parameters

Returns:

Model parameters

Return type:

Parameters

property builder: Builder

Model builder

Returns:

Model builder

Return type:

Builder

property simulator: Simulator

Model simulator

Returns:

Model simulator

Return type:

Simulator

load(path: Path | str)

Load model and override current model

Parameters:

path (Path | str) – path to model data

Model builder

class warmth.build.single_node

Properties of 1D location for forward model

hc

Initial crustal thickness (m)

Type:

float

hLith

Initial depth of base lithosphere (Thermal Lithosphere-Asthenosphere boundary) (m)

Type:

float

kCrust

Reference conductivity of crust at 20C (W/K.m^2)

Type:

float

kLith

Reference conductivity of lithospheric mantle at 20C (W/K.m^2)

Type:

float

kAsth

Reference conductivity of asthenosphere at 20C (W/K.m^2)

Type:

float

rhp

Radiogenic heat production of the crust (W/m^3)

Type:

float

crustsolid

Density of the crust

Type:

float

lithsolid

Density of the lithospheric mantle

Type:

float

asthsolid

Density of th asthenosphere

Type:

float

T0

Seabed temperature (C)

Type:

float

Tm

Temperature at the Lithosphere-Asthenosphere boundary (LAB) (m)

Type:

float

qbase

Heat flow at the base of the crust (Moho) (W/m^2)

Type:

float

sediments_inputs

Present-day sediments. See Builder.single_node_sediments_inputs_template

Type:

pd.DataFrame

X

X location of the node

Type:

float

Y

Y location of the node

Type:

float

paleoWD

Paleo-water depth for multi-rift

Type:

np.ndarray[np.float64]

rift

Rifting episodes

Type:

List[List[int]]

water_depth_difference

Difference between forward model and observed present-day water depth

Type:

float

sediment_fill_margin

Maximum difference between modelled and observed present-day water depth when a fit is considered achieved

Type:

int

total_beta_tested

Total number of beta factors tested in forward model

Type:

int

error

Error from forward model

Type:

str | None

simulated_at

Timestamp when forward model is finished

Type:

str | None

property result: Results | None

Results of 1D simulation

Returns:

None if not simulated

Return type:

Results|None

clear_unused_data()

Removes most arrays of detailed input and output that are not needed by warmth3D, in order to save memory.

compute_derived_arrays()

Computes depths of seabed, top crust, top lithosphere and top aestenosphere, and stores them with the node. This allows the depth and temperature arrays to be discarded to save memory.

property fitting: bool

Whether a beta factor is found

Returns:

True if the modelled water depth difference is smaller than the acceptable difference

Return type:

bool

property sediments: DataFrame

Cleaned-up sediments for the 1D location

Returns:

Sediment input

Return type:

pd.DataFrame

class warmth.build.Grid(origin_x: float, origin_y: float, num_nodes_x: int, num_nodes_y: int, step_x: float, step_y: float)

Defines geometry of a 3D model

property location_grid: ndarray

Locations of all 1D nodes

Returns:

A 2D array of locations of all nodes

Return type:

np.ndarray

make_grid_arr() → List[List]

list of list defining model geometry

Returns:

Template geometry to store 1D node object

Return type:

List[List]

property indexing_arr: ndarray

Array of indices of all 1D node object

Returns:

Arry of indices

Return type:

np.ndarray

dump(filepath: Path)

Save the object

Parameters:

filepath (Path) – File path to save

class warmth.build.Builder(parameters: Parameters)

Utilities to build a model

Parameters:

parameters (Parameters) – Model parameters

property single_node_sediments_inputs_template

Template for creating sediment for single node

Returns:

Single node sediment template

Return type:

pd.Dataframe

property input_horizons_template: DataFrame

Template dataframe for model input using maps

Returns:

Emtpy dataframe for appending input data

Return type:

pd.DataFrame

extract_nodes(thread: int, path: Path, formatfile: str = 'irap_binary', facies_dict: dict | None = None)

Extract model nodes from input data

Parameters:

  • thread (int) – Number of concurrent process

  • path (Path) – Path to map directory

  • formatfile (str, optional) – Map format supported by xtgeo, by default “irap_binary”

  • facies_dict (dict | None, optional) – Lithology value mapping with facies map, by default None

Raises:

  • ValueError – Invalid input table. Check self.input_horizons

  • ValueError – self.input_horizons not sorted with ascending age

define_geometry(path: Path, xinc: float | None = None, yinc: float | None = None, fformat='irap_binary')

Define geometry of a 3D model by using a map

Parameters:

  • path (Path) – Path to the map used in defining model geometry

  • xinc (float, optional) – Overwrite node distance in x direction from input map, by default None

  • yinc (float, optional) – Overwrite node distance in y direction from input map, by default None

  • fformat (str, optional) – Map format supported by xtgeo, by default “irap_binary”

property locations: ndarray

Locations of all 1D nodes

Returns:

A 2D array of locations of all nodes

Return type:

np.ndarray

iter_node() → Iterator[single_node]

Iterate all 1D nodes

Yields:

Iterator[single_node] – 1D node

set_eustatic_sea_level(sealevel: dict | None = None)

Set eustatic sea level correction for subsidence modelling

Parameters:

sealevel (dict | None, optional) – Eustatic sea level data, by default None

Parameters

class warmth.parameters.Parameters

Parameters of the model

property initial_hLith_max

Maximum allowed lithosphere thickness for crustal thickness calibration

property initial_hLith_min

Minimum allowed lithosphere thickness for crustal thickness calibration

property time_start

Start age of the model in Ma

Returns:

Start age of model

Return type:

int

property time_end

End age of the model in Ma

Returns:

End age of model

Return type:

int

property positive_down

Depth values are positive downwards

Returns:

True if positve downwards

Return type:

bool

property time_step_Ma

Time step to solve

Returns:

Time step

Return type:

-1

Forward model

class warmth.forward_modelling.Forward_model(parameters: Parameters, current_node: single_node)

1D simulation

simulate_single_node()

Start simulating self.current_node

sediment_density(mean_porosity: ndarray[float64], density: ndarray[float64]) → ndarray[float64]

Effective density of sediment cells taking into account of water density in pores

Parameters:

  • mean_porosity (np.ndarray[np.float64]) – Porosity of the sediments

  • density (np.ndarray[np.float64]) – Density of sediment

Returns:

mean_sediments_density – Effective density of sediment cells

Return type:

np.ndarray[np.float64]

simulate_continental()

Run forward model for single or multi rift

static compaction(top_m: float, base_m: float, phi0: float, phi_decay: float, base_maximum_burial_depth_m: float = 0) → float

Compact sediment at depth

Parameters:

  • top_m (float) – Top of sediment (m)

  • base_m (float) – Base of sediment (m)

  • phi0 (float) – Porosity at surface (fraction)

  • phi_decay (float) – Exponential decay of porosity with depth (fraction)

  • base_maximum_burial_depth_m (float, optional) – Maximum burial depth of sediment (To make sure compaction is irreversable), by default 0

Returns:

base_result – Depth of sediment base (m)

Return type:

float

static decompaction(top_m: float, base_m: float, phi0: float, phi_decay: float) → float

Thickness of sediment without pore space. For calculating deposition rate

Parameters:

  • top_m (float) – Top of sediment (m)

  • base_m (float) – Base of sediment (m)

  • phi0 (float) – Porosity at surface (fraction)

  • phi_decay (float) – Exponential decay of porosity with depth (fraction)

Returns:

grain_thickness – Thickness of sediment without pore space (m)

Return type:

float

add_sediments(sedrate: ndarray[float64], sed: ndarray[float64], xsed_old: ndarray[float64], Tsed_old: ndarray[float64], HPsed_old: ndarray[float64], idsed_old: ndarray[int32]) → Tuple[bool, ndarray[float64], ndarray[float64], ndarray[float64], ndarray[int32]]

Take care of sedimentation at this time step

Parameters:

  • sedrate (np.ndarray[np.float64]) – Sedimentation rate at current time steps (m/Ma)

  • sed (np.ndarray[np.float64]) – Top and base of all sediment unit at current time step referenced to seabed at 0 m (m)

  • xsed_old (np.ndarray[np.float64]) – Top and base of sedimentary column at current time step referenced to seabed at 0 m (m)

  • Tsed_old (np.ndarray[np.float64]) – Temperature of sediments at xsed (C)

  • HPsed_old (np.ndarray[np.float64]) – Radiogenic heat production between xsed (W/m3)

  • idsed_old (np.ndarray[np.int32]) – Sediment ids between xsed

Returns:

  • sedflag (bool) – True if sedimentation exists at current time step

  • xsed (np.ndarray[np.float64]) – Top and base of sedimentary column at current time step referenced to seabed at 0 m (m)

  • Tsed (np.ndarray[np.float64]) – Temperature of sediments at xsed (C)

  • HPsed (np.ndarray[np.float64]) – Radiogenic heat production between xsed (W/m3)

  • idsed (np.ndarray[np.int32]) – Sediment ids between xsed

calculate_new_temperature(sedflag: bool, coord_crust_lith: ndarray[float64], t_old: ndarray[float64], HP: ndarray[float64], xsed: ndarray[float64], hc: float, hLith: float, Tsed: ndarray[float64], HPsed: ndarray[float64], idsed: ndarray[int32]) → tuple[ndarray[float64], ndarray[float64], ndarray[float64], ndarray[float64]]

Calculate new temperature profile in new time step

Parameters:

  • sedflag (bool) – If sediments exists

  • coord (np.ndarray[np.float64]) – 1D vertical mesh of crust, lithosphere and asthenosphere

  • t_old (np.ndarray[np.float64]) – Temperature profile of crust, lithosphere and asthenosphere at previous time step

  • HP (np.ndarray[np.float64]) – RHP of crust, lithosphere and asthenosphere at this new time step

  • xsed (np.ndarray[np.float64]) – 1D vertical mesh of sedimentary column

  • hc (float) – Depth of base crust

  • hLith (float) – Depth of base lithosphere

  • Tsed (np.ndarray[np.float64]) – Temperature profile of sediments at previous time step

  • HPsed (np.ndarray[np.float64]) – RHP of sediments at this new time step

  • idsed (np.ndarray[np.int32]) – ID of sediments

Returns:

_description_

Return type:

tuple[np.ndarray[np.float64],np.ndarray[np.float64],np.ndarray[np.float64],np.ndarray[np.float64]]

implicit_euler_solve(T_start: ndarray[float64], coord_all: ndarray[float64], density_all: ndarray[float64], conductivity_packed: ndarray[float64], source: ndarray[float64], k_last_node: float, HP_last_node: float, T_base: float) → tuple[ndarray[float64], ndarray[float64]]

Solve heat equation using backward Euler scheme

Parameters:

  • T_start (np.ndarray[np.float64]) – Temperature profile of starting condition

  • coord_all (np.ndarray[np.float64]) – 1D vertical mesh of whole model

  • density_all (np.ndarray[np.float64]) – Density of whole model

  • conductivity (np.ndarray[np.float64]) – Conductivity of whole model

  • source (np.ndarray[np.float64]) – Heat source term

  • k_last_node (float) – Conductivity at the base of model

  • HP_last_node (float) – RHP at the base of model

Returns:

_description_

Return type:

tuple[np.ndarray[np.float64],np.ndarray[np.float64]]

Simulator

class warmth.simulator.Simulator(builder: Builder)

Solving model

Utilities for simulating nodes

Parameters:

builder (Builder) – model builder

Results

class warmth.postprocessing.Results(depth: ndarray, temperature: ndarray, sediments_ids: ndarray, sediment_input: DataFrame, k_crust: float, k_lith: float, k_asth: float)

Simulation results

typeddict resultValues

typing.TypedDict.

Required Keys:

  • depth (ndarray[float64])

  • layerId (ndarray[int32])

top_crust(age: int) → float

Depth of crust

Parameters:

age (int) – Geological age

Returns:

Depth of crust from sea level (m)

Return type:

float

top_lithosphere(age: int) → float

Depth of lithospheric mantle

Parameters:

age (int) – Geological age

Returns:

Depth of lithospheric mantle / Moho from sea level (m)

Return type:

float

top_asthenosphere(age: int) → float

Depth of Asthenosphere

Parameters:

age (int) – Geological age

Returns:

Depth of Asthenosphere from sea level (m)

Return type:

float

crust_thickness(age: int) → float

Thickness of crust

Parameters:

age (int) – Geological age

Returns:

Thickness of crust (m)

Return type:

float

lithosphere_thickness(age: int) → float

Thickness of lithospheric mantle

Parameters:

age (int) – Geological age

Returns:

Thickness of lithospheric mantle (m)

Return type:

float

depth(age: int) → ndarray[float64]

Depth reference for results

Parameters:

age (int) – Geological age

Returns:

Top and base of all cells

Return type:

np.ndarray

temperature(age: int, sediment_id: int | None = None) → resultValues

Temperature at top and base of cells

Parameters:

  • age (int) – Geological age

  • sediment_id (int | None, optional) – Optional filter using id of layer by default None

Returns:

Temperature at top and base of cells

Return type:

np.ndarray

sediment_ids(age: int) → ndarray[int32]

Layer ids at the centre of cells

Parameters:

age (int) – Geological age

Returns:

Layer ids at the center of cells

Return type:

np.ndarray

sediment_porosity(age: int, sediment_id: int | None = None) → resultValues

Porosity at the centre of cells

Parameters:

  • age (int) – Geological age

  • sediment_id (int | None, optional) – Optional filter using id of layer by default None

Returns:

Porosity at centre of cells

Return type:

dict

effective_conductivity(age: int, sediment_id: int | None = None) → resultValues

Effective conductivity at the centre of cells

Parameters:

  • age (int) – Geological age

  • sediment_id (int | None, optional) – Optional filter using id of layer by default None

Returns:

Effective conductivity at centre of cells (W/K.m^2)

Return type:

resultValues

heatflow(age: int, sediment_id: int | None = None) → resultValues

Heat flow at the centre of cells

Parameters:

  • age (int) – Geological age

  • sediment_id (int | None, optional) – Optional filter using id of layer by default None

Returns:

Heat flow at centre of cells

Return type:

dict

basement_heatflow(age: int) → float

Heat flow from the crust to the base of sediments

Parameters:

age (int) – Geological age

Returns:

Basement heat flow (W/m3)

Return type:

float