VerticalWell

class petres.models.VerticalWell

Bases: object

Store a vertical well with tops and property samples.

A well holds horizon tops and arbitrary property samples. Property samples are tracked per property name in one of two mutually exclusive modes: scalar mode (depth is None) or depth-indexed mode (depth provided). Mixing these modes for the same property is not allowed.

Parameters:

• name (str) – Well identifier.

• x (float) – Well-head x coordinate.

• y (float) – Well-head y coordinate.

• tops (dict[str, float], optional) – Mapping of horizon name to measured top depth.

• samples (dict[str, dict[float | None, float]], optional) – Property samples; keys are property names, values are depth→value maps.

• _sample_modes (dict[str, Literal['scalar', 'depth']], optional) – Internal map tracking whether samples for a property are scalar or depth-indexed.

name: str

x: float

y: float

tops: dict[str, float]

samples: dict[str, dict[float | None, float]]

__post_init__()

Validate and normalize the initialized well state.

property xy: tuple[float, float]

Return well-head coordinates.

Returns:

Two-element tuple (x, y).

Return type:

tuple[float, float]

add_top(horizon, depth)

Add a new horizon top depth.

Parameters:

• horizon (str) – Horizon name to add.

• depth (float) – Measured top depth.

Raises:

ValueError – If the horizon name/depth is invalid or the horizon already exists.

get_top(horizon)

Return the top depth for a horizon.

Parameters:

horizon (str) – Horizon name to query.

Returns:

Stored depth for horizon.

Return type:

float

Raises:

KeyError – If horizon is not present in this well.

remove_top(horizon)

Remove an existing horizon top depth.

Parameters:

horizon (str) – Horizon name to remove.

Raises:

KeyError – If horizon is not present.

add_sample(name, value, depth=None)

Add a property sample in scalar or depth-indexed mode.

For one property name, all samples must use the same storage mode: scalar (depth=None) or depth-indexed (depth provided).

Parameters:

• name (str) – Property name.

• value (float) – Sample value.

• depth (float or None, default=None) – Depth for depth-indexed mode. Use None for scalar mode.

Raises:

ValueError – If values are invalid, a mode conflict occurs, or a duplicate sample key exists.

Examples

>>> well = VerticalWell(name="W1", x=100.0, y=200.0)
>>> well.add_sample(name="poro", value=0.18)
>>> well.add_sample(name="perm", value=120.0, depth=2500.0)

get_sampling_mode(name)

Return the storage mode for samples of a property.

Parameters:

name (str) – Property name.

Returns:

Storage mode for samples of this property.

Return type:

‘scalar’ or ‘depth’

Raises:

• ValueError – If name is not a non-empty string.

• KeyError – If no samples exist for name.

get_sample(name, depth=None)

Return one sample or all samples for a property.

Parameters:

• name (str) – Property name.

• depth (float or None, default=None) – For depth-indexed properties, provide a depth to return one value. If None, returns all depth-indexed samples as a shallow copy. Scalar properties always return their scalar value.

Returns:

For depth-indexed properties: - depth provided: sample value at that depth. - depth omitted: shallow copy of depth→value mapping. For scalar properties: scalar sample value.

Return type:

dict[float, float] or float

Raises:

• ValueError – If name is not a non-empty string, depth is non-finite, or a depth is provided for a scalar property.

• KeyError – If no samples exist for name or no sample exists at depth.

remove_sample(name, depth=None)

Remove a stored sample and clean empty internal state.

Parameters:

• name (str) – Property name.

• depth (float or None, default=None) – Depth key used for removal. Use None for scalar samples.

Raises:

• ValueError – If name is not a non-empty string or depth is non-finite when provided.

• KeyError – If no sample exists for (name, depth).

__init__(name, x, y, tops=<factory>, samples=<factory>, _sample_modes=<factory>)