pycsamt.metadata.geology#

Geological formation catalog for MT / AMT / TEM modelling.

The catalog centralises the GEOLOGY_PRIORS that used to live in forward/synthetic.py and extends it with a richer set of geological scenarios. Every scenario is described by:

resistivity range (Ω·m),
depth range (m),
n_layers hint for layered-Earth generation,
free-text description and associated rock types.

Quick start#

from pycsamt.metadata.geology import CATALOG, Formation

# Access a named scenario
f = CATALOG.get("sedimentary")
print(f.rho_mid)         # geometric-mean resistivity
print(f.to_prior())      # dict compatible with LayeredModel.from_geology()

# Fuzzy look-up by resistivity
matches = CATALOG.lookup_by_resistivity(100.0, n=3)

# All names
print(CATALOG.names())

# Add a custom formation
CATALOG.add(Formation(
    name="custom_ore",
    resistivity_range=(0.01, 10.0),
    depth_range=(100, 500),
    n_layers_range=(2, 4),
    description="Massive sulphide ore body",
    rock_types=["massive sulphide", "graphite"],
))

Compatibility with forward.synthetic#

geology_prior() returns a dict in the exact format expected by LayeredModel.from_geology(name):

from pycsamt.metadata.geology import geology_prior
prior = geology_prior("sedimentary")   # → used by LayeredModel

Functions

geology_prior(name)

Return a GEOLOGY_PRIORS-compatible dict for name.

Classes

`Formation`(name, resistivity_range, ...[, ...])	A named geological scenario for layered-Earth modelling.
`GeologyCatalog`([formations])	Registry of geological formations for layered-Earth modelling.

class pycsamt.metadata.geology.Formation(name, resistivity_range, depth_range, n_layers_range, description='', rock_types=<factory>, extra=<factory>)[source]#

Bases: object

A named geological scenario for layered-Earth modelling.

Parameters:

name (str) – Unique identifier (lower-case, e.g. "sedimentary").
resistivity_range (tuple[float, float]) – Expected resistivity interval (Ω·m) as (rho_min, rho_max).
depth_range (tuple[float, float]) – Typical investigation depth range (m) as (depth_min, depth_max).
n_layers_range (tuple[int, int]) – Plausible number of layers for synthetic generation, (n_min, n_max).
description (str) – Free-text geological description.
rock_types (list[str]) – Rock type names that correspond to entries in GEO_ROCK_RESISTIVITY.
extra (dict) – Arbitrary additional parameters preserved on round-trips.

Examples

f = Formation(
    name="hydrothermal",
    resistivity_range=(1.0, 1e3),
    depth_range=(200, 3000),
    n_layers_range=(3, 6),
    description="Hydrothermal alteration zone",
)
print(f.rho_mid, f.log_rho_range)

name: str#

resistivity_range: tuple[float, float]#

depth_range: tuple[float, float]#

n_layers_range: tuple[int, int]#

description: str = ''#

rock_types: list[str]#

extra: dict[str, Any]#

property log_rho_range: tuple[float, float][source]#: Log10-resistivity interval (log_rho_min, log_rho_max).

property rho_mid: float[source]#: Geometric-mean resistivity (Ω·m).

property depth_mid: float[source]#: Arithmetic-mean depth (m).

property n_layers_mid: int[source]#: Midpoint of the n_layers range, rounded.

to_prior()[source]#

Return a dict compatible with LayeredModel.from_geology(name).

The returned dict has keys n_layers, log_rho_range, depth_max_range, and description — exactly the format expected by GEOLOGY_PRIORS in forward/synthetic.py.

Return type:: dict[str, Any]

to_dict()[source]#

Return type:: dict[str, Any]

classmethod from_dict(d)[source]#

Parameters:: d (dict[str, Any])
Return type:: Formation

classmethod from_prior(name, prior)[source]#

Build a Formation from a GEOLOGY_PRIORS entry.

Parameters:

name (str)
prior (dict[str, Any])

Return type:

Formation

class pycsamt.metadata.geology.GeologyCatalog(formations=None)[source]#

Bases: object

Registry of geological formations for layered-Earth modelling.

Parameters:: formations (list of Formation, optional) – Initial formations. When omitted the built-in catalog is loaded.

Examples

from pycsamt.metadata.geology import CATALOG

# list all names
print(CATALOG.names())

# look up by name
f = CATALOG.get("sedimentary")

# find closest by resistivity
matches = CATALOG.lookup_by_resistivity(50.0, n=3)

# add a custom formation
CATALOG.add(Formation(
    name="custom",
    resistivity_range=(5.0, 200.0),
    depth_range=(100, 500),
    n_layers_range=(3, 5),
))

# export to a pandas DataFrame
df = CATALOG.to_dataframe()

add(formation)[source]#

Register formation, overwriting any existing entry with the same name.

Parameters:: formation (Formation)
Return type:: None

remove(name)[source]#

Remove formation by name (raises KeyError when absent).

Parameters:: name (str)
Return type:: None

reset()[source]#

Restore the built-in catalog, discarding custom additions.

Return type:: None

get(name)[source]#

Return the Formation for name.

Raises:: KeyError – When name is not in the catalog.
Parameters:: name (str)
Return type:: Formation

names()[source]#

Return a sorted list of all registered formation names.

Return type:: list[str]

lookup_by_resistivity(rho, n=3)[source]#

Return the n formations whose resistivity range best covers rho.

Matching priority:

Formations whose interval contains rho (sorted by narrowest range).
Formations nearest to rho in log10 space.

Parameters:

rho (float) – Query resistivity in Ω·m.
n (int) – Maximum number of results to return.

Return type:

list[Formation]

lookup_by_depth(depth_m, n=3)[source]#

Return formations whose depth range contains depth_m (metres).

Parameters:

depth_m (float)
n (int)

Return type:

list[Formation]

lookup_by_rock_type(rock_type)[source]#

Return formations that list rock_type in their rock_types.

Parameters:: rock_type (str)
Return type:: list[Formation]

all_scenarios()[source]#

Return a copy of the internal store (name → Formation).

Return type:: dict[str, Formation]

to_prior(name)[source]#

Return a GEOLOGY_PRIORS-compatible dict for name.

This is the adapter used by from_geology().

Parameters:: name (str)
Return type:: dict[str, Any]

to_dataframe(*, api=None)[source]#

Return a pandas.DataFrame with one row per formation.

Parameters:: api (bool | None)
Return type:: Any

pycsamt.metadata.geology.geology_prior(name)[source]#

Return a GEOLOGY_PRIORS-compatible dict for name.

This is a drop-in replacement for direct access to the old GEOLOGY_PRIORS dict in forward/synthetic.py.

Parameters:: name (str) – Formation name (case-insensitive).
Returns:: Keys: n_layers, log_rho_range, depth_max_range, description.
Return type:: dict