API Reference

This is the private internal documentation of the Atlans API.

Modules

Types

# Atlans.AdaptiveCellsize — Type.

AdaptiveCellsize(Δzmax::Float, split_tolerance::Float)

Logic for splitting cells in a column to accomodate for a moving phreatic level in combination with organic matter stores. Handles how the thickness of thick voxels (>Δzmax) should be discretized and determines when splitting occurs. If the thickness of a cell above, or below, the groundwater table is lower than the tolerance, no splitting occurs.

# Atlans.Clock — Type.

Clock(time::Vector{DateTime}, iteration::int, stop_time::DateTime)

Object to keep track of the stress periods, number of iterations and stop time of an Atlantis Simulation.

# Atlans.ExponentialTimeStepper — Type.

ExponentialTimestepper(start::Float, multiplier::T)

Struct to discretize time steps (in days) within each stress period.

# Atlans.Model — Method.

Model(
    groundwater::Type,
    consolidation::Type,
    oxidation::Type,
    preconsolidation::Type,
    shrinkage::Type,
    adaptive_cellsize,
    timestepper,
    path_subsoil,
    path_lookup
)

Initialize a model with specified groundwater, consolidation, oxidation and shrinkage processes from a netCDF file and CSV lookup table describing the subsurface parameters, appropriate for the chosen processes.

# Atlans.ShrinkageColumn — Type.

ShrinkageColumn{S}(cells, z, Δz, result, Hv0)

Collection of SimpleShrinkage cells to compute shrinkage for.

Arguments:

  • cells::Vector{S}: Collection of cells containing the shrinkage process.
  • z::Vector{Float}: Depth of the cells.
  • Δz::Vector{Float}: Thickness of the cells.
  • result::Vector{Float}: Computed shrinkage of each cell.
  • Hv0::Float: Absolute depth above phreatic level to compute shrinkage for in cells.

# Atlans.SimpleShrinkage — Type.

SimpleShrinkage(Δz, n, τ, r, shrinkage)

Simple voxel with attributes to compute shrinkage for.

#Arguments

  • Δz::Float: Thickness of the voxel. [m]
  • n::Float: Shrinkage factor of the voxel. [-]
  • L::Float: Mass fraction of lutum.
  • H::Float: Mass fraction of organic.
  • τ::Float: Time dependent factor for shrinkage process. [days]
  • r::Float: Direction of shrinkage, r is 3 indicates isoptropic. [-]
  • sf::Float: TODO: look-up in document [-]
  • shrinkage::Float: Computed shrinkage or elevation change over time. [m]

# Atlans.Simulation — Method.

Simulation(model, path_output, stop_time, forcings, additional_times)

Setup a simulation from an initialized model.

# Atlans.SoilColumn — Type.

x, y, z are all midpoints.

# Atlans.VerticalDomain — Type.

Temporary structure used to create SoilColumns.

Functions

# Atlans.Qcreep_derivative — Method.

Derivative of Qcreep with respect to head.

# Atlans.U — Method.

Terzaghi, degree of consolidation

# Atlans.add_time — Method.

Add a new time to the unlimited time dimension, and return the index

# Atlans.advance! — Method.

Advances the clock by one iteration.

# Atlans.advance_forcingperiod! — Method.

Advance a single stress period for all columns.

Timesteps are determined by the total duration and the chosen timestepper.

# Atlans.advance_forcingperiod! — Method.

Advance the simulation by a single forcing period. Reads new input, computes, writes output.

# Atlans.advance_forcingperiod! — Method.

advance_forcingperiod!(column, timesteps)

Advances a prepared column by a number of timesteps.

Note, the correct order of execution is:

  • prepare a forcing period: compute pre-load stress
  • apply forcing: change load
  • advance forcing period

# Atlans.advance_timestep! — Method.

advance_timestep!(column, Δt)

Advance a single timestep.

During a timestep the following states are computed:

* head
* pore pressure
* total stress
* effective stress

Then, consolidation and oxidation are computed.

Finally, thickness and elevation are updated.

# Atlans.cellsplit! — Method.

For CarbonStore, organic and mineral mass should be split according to cell height (Δz).

# Atlans.cellsplit! — Method.

cellsplit!(column, _, newlength, _, _,)

Logic for cellsplit! if one of the processes is ignored (e.g. NullConsolidation).

# Atlans.compress_γ_dry — Method.

Consolidation reduces pore space, pushes out the air.

# Atlans.compress_γ_wet — Method.

Consolidation reduces pore space, pushes out the water.

# Atlans.consolidate — Method.

consolidate(abc::DrainingAbcIsotache, σ′, Δt)

Compute consolidation for a single cell.

The cell contains a state U for Terzaghi’s degree of consolidation. This state is updated every consolidate step. During every Δt, a new U is computed. The increase in U can be directly related to the pore pressure, and so the increase in effective stress is equal to the effective stress prior to loading (abc.σ′) and the new effective stress (σ′) reached when U becomes 1.0.

The degree of consolidation plays only one role: it distributes the load (final σ′ - initial σ′) over time and as the column might be submerging, the increase in σ′ may become lower, providing a negative feedback mechanism.

# Atlans.create_timesteps — Method.

Based on the duration and the timestepper, create the required timesteps.

# Atlans.currenttime — Method.

Return current time.

# Atlans.discretize — Method.

In how many equal parts should a thick cell be divided?

# Atlans.draining_abc_isotache_column — Method.

Turn a collection of vectors into a collection of DrainingAbcIsotache cells.

# Atlans.effective_stress! — Method.

Compute effective stress for entire column

# Atlans.formulate — Method.

First term of Taylor expansion

f(x) ~= f(a) + f′(a) * (x - a)

# Atlans.initialize — Method.

initialize(::Type{CarbonStore}, domain, subsoil, I)

Initialize a OxidationColumn for a domain at location I based subsurface input.

# Atlans.initialize — Method.

initialize(::Type{CarbonStore}, domain::VerticalDomain, lookup_table::Dict)

Initialize a OxidationSurcharge column that can be added to an OxidationColumn when Surcharge is applied as a forcing during a forcingperiod.

# Atlans.initialize — Method.

initialize(::Type{DrainingAbcIsotache}, domain, subsoil, I)

Initialize a ConsolidationColumn for a domain at location I based subsurface input.

# Atlans.initialize — Method.

initialize(
    ::Type{DrainingAbcIsotache},
    preconsolidation::Type,
    domain::VerticalDomain,
    lookup_table::Dict
)

Initialize a ConsolidationSurcharge column that can be added to a ConsolidationColumn when Surcharge is applied as a forcing during a forcingperiod.

# Atlans.initialize — Method.

initialize(::Type{HydrostaticGroundwater}, phreatic::Phreatic, domain::VerticalDomain)

Initialize a GroundwaterSurcharge column that can be added to a HydrostaticGroundwater column when Surcharge is applied as a forcing during a forcingperiod.

# Atlans.initialize — Method.

initialize(::Type{NullConsolidation}, preconsolidation::Type, domain, _)

Initialize an empty ConsolidationSurcharge column when the consolidation process is ignored.

# Atlans.initialize — Method.

initialize(::Type{NullConsolidation}, domain, subsoil, I)

Initialize an empty ConsolidationColumn (i.e. consolidation is ignored) at location I.

# Atlans.initialize — Method.

initialize(::Type{SimpleShrinkage}, domain, subsoil, I)

Initialize an empty OxidationColumn (i.e. oxidation is ignored) at location I.

# Atlans.initialize — Method.

initialize(::Type{NullOxidation}, domain, _)

Initialize an empty OxidationSurcharge column when the oxidation process is ignored.

# Atlans.initialize — Method.

initialize(::Type{SimpleShrinkage}, domain, subsoil, I)

Initialize an empty ShrinkageColumn (i.e. shrinkage is ignored) at location I.

# Atlans.initialize — Method.

initialize(::Type{NullShrinkage}, domain, _)

Initialize an empty ShrinkageSurcharge column when the shrinkage process is ignored.

# Atlans.initialize — Method.

initialize(::Type{SimpleShrinkage}, domain, subsoil, I)

Initialize a ShrinkageColumn for a domain at location I based subsurface input.

# Atlans.initialize — Method.

initialize(::Type{SimpleShrinkage}, domain::VerticalDomain, lookup_table::Dict)

Initialize a ShrinkageSurcharge column that can be added to an ShrinkageColumn when Surcharge is applied as a forcing during a forcingperiod.

# Atlans.parse_loglevel — Method.

parse_loglevel(input_level::AbstractString)::LogLevel
parse_loglevel(input_level::Integer)::LogLevel

Parse a log level from either an integer or string.

Examples

parse_loglevel("info") -> Logging.Info
parse_loglevel(0) -> LogLevel(0) (== Logging.Info)

# Atlans.periodduration — Method.

Compute duration of forcing period from current time.

# Atlans.pow — Method.

Faster method for exponentiation

# Atlans.prepare_domain — Method.

Temporary structure used to create SoilColumns.

# Atlans.prepare_forcingperiod! — Function.

prepare_forcingperiod!(column, split_tolerance)

Prepare a single forcing period.

This:

* splits the soil column at maximum oxidation depth (if necessary)
* computes pore pressure, total stress, effective stress prior to this stress periods loading
* sets the effective stress in every consolidation cell
* Reset U and t for DrainingConsolidation processes.

Note that splitting requires knowing where the phreatic level ends up after applying all forcings. This means that changes to phreatic level and deep subsidence must be accounted for. Furthermore, the split must be applied before applying the changes to compute the pre-loading effective stress.

# Atlans.prepare_forcingperiod! — Method.

Reset degree of consolidation and time.

# Atlans.prepare_surcharge_column — Method.

prepare_surcharge_column(sur::Surcharge, column::SoilColumn, I::CartesianIndex)

Create a SurchargeColumn with correct groundwater, consolidation, oxidation and shrinkage Surcharge columns. The correct Atlantis processes (e.g. DrainingAbcIsotache) that each of the Surcharge columns are built-up from, are derived from the input SoilColumn. The CartesianIndex reads to lithology and thickness to build the Surcharge column from at the correct location in the Surcharge forcing input.

# Atlans.prepare_timestep! — Method.

prepare_timestep!(column)

Prepare a single timestep. This updates stresses in the column and accounts for e.g. drowning of the column.

This computes:

* Pore pressure
* Total stress
* Effective stress

# Atlans.prepare_timestep! — Method.

prepare_timestep!(column::SurchargeColumn, Δt)

Set the initial stresses for a SurchargeColumn.

# Atlans.relative_oxidation_rate — Function.

relative_oxidation_rate(T::Float)

Empirical relation between the decay rate of organic soils and air temperature in Celsius from Hendriks and Vermeulen (1997). Relation is valid between 0° and 19.5° Celsius.

# Atlans.repeat_elements — Method.

Repeat function not in base / stdlib

# Atlans.run! — Method.

Run all forcing periods of the simulation.

# Atlans.set_periods! — Method.

Collect the period boundaries from the forcing input.

# Atlans.set_surcharge! — Method.

set_surcharge!(column::SoilColumn, surcharge::SurchargeColumn)

Combine a SoilColumn and SurchargeColumn when Surcharge is added as a forcing during a forcingperiod.

# Atlans.shrink — Method.

shrink(voxel, Δt)

Shrink a voxel for given time interval.

#Arguments

  • voxel::SimpleShrinkage: Voxel to shrink.
  • Δt::Float: Time interval. [days]

# Atlans.subside! — Method.

subside!(column)

Apply consolidation, oxidation and shrinkage to thickness

# Atlans.total_stress! — Method.

Compute total stress for entire column

# Atlans.transfer_stress! — Method.

Transfer computed stress to the cells of the ConsolidationColumn.

# Atlans.update_alpha — Method.

update_alpha(cell::CarbonStore, T::Float)

Return a new CarbonStore cell with an oxidation rate (α) that is corrected for air temperature.

# Atlans.update_z! — Method.

function update_z!(column)

Compute new midpoints and surface level.

# Atlans.volume_organic — Method.

Empirical equation to compute specific volume of organic material.

As the organic matter in a soil breaks down, density increases. The “airiest” parts are the first to go.

# Atlans.weight — Method.

Weight of (part of) a single cell

Constants

Macros

Index