pycsamt.format.borehole.schema

In-memory schema and semantic validation for PCBH 0.1.

PCBH represents one or more boreholes independently of an inversion model. This module contains no JSON, CSV, LAS, trajectory-desurvey, CRS-transform, PCSF, or rendering code. Those responsibilities are intentionally deferred to later implementation phases.

Classes

Collar(x, y, z[, longitude, latitude, ...])	Borehole reference/origin position in the document CRS.
CoordinateReferenceSystem(horizontal[, ...])	Document-wide horizontal and vertical coordinate references.
LogInterval(from_md, to_md[, code, label, ...])	One measured-depth interval in a named log family.
PCBHBorehole(id, name, kind, status, collar, ...)	One borehole and its trajectory, logs, and structures.
PCBHDocument(document_id, created_at, ...[, ...])	Root PCBH document containing one or more boreholes.
StructureObservation(kind[, at_md, from_md, ...])	Point or interval structural observation along a borehole.
SurveyStation(md, azimuth_deg, inclination_deg)	One measured-depth orientation station.
Trajectory([method, north_reference, ...])	Vertical shorthand or measured survey for a borehole path.
UnitSystem([depth, diameter, angle, resistivity])	Units shared by all boreholes in one PCBH 0.1 document.
ValidationIssue(severity, code, message[, ...])	One machine-readable PCBH validation finding.
VocabularyEntry(code, name[, color, ...])	Self-contained geological or domain vocabulary entry.

Exceptions

PCBHValidationError(issues)

Raised when error-severity issues remain after validation.

class pycsamt.format.borehole.schema.ValidationIssue(severity, code, message, path='', source=<factory>)

Bases: PyCSAMTObject

One machine-readable PCBH validation finding.

Parameters:

• severity (str)

• code (str)

• message (str)

• path (str)

• source (dict[str, Any])

severity: str

code: str

message: str

path: str = ''

source: dict[str, Any]

exception pycsamt.format.borehole.schema.PCBHValidationError(issues)

Bases: ValueError

Raised when error-severity issues remain after validation.

Parameters:

issues (Iterable[ValidationIssue])

class pycsamt.format.borehole.schema.CoordinateReferenceSystem(horizontal, vertical='unknown', axis_order='xy', coordinate_unit='m')

Bases: _Validatable, PyCSAMTObject

Document-wide horizontal and vertical coordinate references.

Parameters:

• horizontal (str)

• vertical (str)

• axis_order (str)

• coordinate_unit (str)

horizontal: str

vertical: str = 'unknown'

axis_order: str = 'xy'

coordinate_unit: str = 'm'

collect_issues(path='crs')

Parameters:

path (str)

Return type:

list[ValidationIssue]

class pycsamt.format.borehole.schema.UnitSystem(depth='m', diameter='m', angle='deg', resistivity='ohm.m')

Bases: _Validatable, PyCSAMTObject

Units shared by all boreholes in one PCBH 0.1 document.

Parameters:

• depth (str)

• diameter (str)

• angle (str)

• resistivity (str)

depth: str = 'm'

diameter: str = 'm'

angle: str = 'deg'

resistivity: str = 'ohm.m'

collect_issues(path='units')

Parameters:

path (str)

Return type:

list[ValidationIssue]

class pycsamt.format.borehole.schema.Collar(x, y, z, longitude=None, latitude=None, position_uncertainty_m=None)

Bases: _Validatable, PyCSAMTObject

Borehole reference/origin position in the document CRS.

Parameters:

• x (float)

• y (float)

• z (float)

• longitude (float | None)

• latitude (float | None)

• position_uncertainty_m (float | None)

x: float

y: float

z: float

longitude: float | None = None

latitude: float | None = None

position_uncertainty_m: float | None = None

collect_issues(path='collar')

Parameters:

path (str)

Return type:

list[ValidationIssue]

class pycsamt.format.borehole.schema.VocabularyEntry(code, name, color=None, description='', external_ids=<factory>, properties=<factory>)

Bases: _Validatable, PyCSAMTObject

Self-contained geological or domain vocabulary entry.

Parameters:

• code (str)

• name (str)

• color (str | None)

• description (str)

• external_ids (dict[str, str])

• properties (dict[str, Any])

code: str

name: str

color: str | None = None

description: str = ''

external_ids: dict[str, str]

properties: dict[str, Any]

collect_issues(path='vocabulary')

Parameters:

path (str)

Return type:

list[ValidationIssue]

class pycsamt.format.borehole.schema.SurveyStation(md, azimuth_deg, inclination_deg)

Bases: _Validatable, PyCSAMTObject

One measured-depth orientation station.

Parameters:

• md (float)

• azimuth_deg (float)

• inclination_deg (float)

md: float

azimuth_deg: float

inclination_deg: float

collect_issues(path='survey_station')

Parameters:

path (str)

Return type:

list[ValidationIssue]

class pycsamt.format.borehole.schema.Trajectory(method='vertical', north_reference='unknown', desurvey_method='minimum_curvature', stations=<factory>)

Bases: _Validatable, PyCSAMTObject

Vertical shorthand or measured survey for a borehole path.

Parameters:

• method (str)

• north_reference (str)

• desurvey_method (str)

• stations (list[SurveyStation])

method: str = 'vertical'

north_reference: str = 'unknown'

desurvey_method: str = 'minimum_curvature'

stations: list[SurveyStation]

collect_issues(path='trajectory')

Parameters:

path (str)

Return type:

list[ValidationIssue]

class pycsamt.format.borehole.schema.LogInterval(from_md, to_md, code=None, label=None, description='', resistivity_ohm_m=None, data_nature='unknown', confidence=None, properties=<factory>)

Bases: _Validatable, PyCSAMTObject

One measured-depth interval in a named log family.

Parameters:

• from_md (float)

• to_md (float)

• code (str | None)

• label (str | None)

• description (str)

• resistivity_ohm_m (float | None)

• data_nature (str)

• confidence (float | None)

• properties (dict[str, Any])

from_md: float

to_md: float

code: str | None = None

label: str | None = None

description: str = ''

resistivity_ohm_m: float | None = None

data_nature: str = 'unknown'

confidence: float | None = None

properties: dict[str, Any]

collect_issues(path='interval')

Parameters:

path (str)

Return type:

list[ValidationIssue]

class pycsamt.format.borehole.schema.StructureObservation(kind, at_md=None, from_md=None, to_md=None, orientation_representation='none', strike_deg=None, dip_deg=None, dip_direction_deg=None, trend_deg=None, plunge_deg=None, alpha_deg=None, beta_deg=None, aperture_m=None, fill=None, data_nature='unknown', confidence=None)

Bases: _Validatable, PyCSAMTObject

Point or interval structural observation along a borehole.

Parameters:

• kind (str)

• at_md (float | None)

• from_md (float | None)

• to_md (float | None)

• orientation_representation (str)

• strike_deg (float | None)

• dip_deg (float | None)

• dip_direction_deg (float | None)

• trend_deg (float | None)

• plunge_deg (float | None)

• alpha_deg (float | None)

• beta_deg (float | None)

• aperture_m (float | None)

• fill (str | None)

• data_nature (str)

• confidence (float | None)

kind: str

at_md: float | None = None

from_md: float | None = None

to_md: float | None = None

orientation_representation: str = 'none'

strike_deg: float | None = None

dip_deg: float | None = None

dip_direction_deg: float | None = None

trend_deg: float | None = None

plunge_deg: float | None = None

alpha_deg: float | None = None

beta_deg: float | None = None

aperture_m: float | None = None

fill: str | None = None

data_nature: str = 'unknown'

confidence: float | None = None

collect_issues(path='structure')

Parameters:

path (str)

Return type:

list[ValidationIssue]

class pycsamt.format.borehole.schema.PCBHBorehole(id, name, kind, status, collar, total_depth_md, trajectory=<factory>, diameter=None, interval_logs=<factory>, structures=<factory>, aliases=<factory>, metadata=<factory>, extensions=<factory>)

Bases: _Validatable, PyCSAMTObject, MetadataMixin

One borehole and its trajectory, logs, and structures.

Parameters:

• id (str)

• name (str)

• kind (str)

• status (str)

• collar (Collar)

• total_depth_md (float)

• trajectory (Trajectory)

• diameter (float | None)

• interval_logs (dict[str, list[LogInterval]])

• structures (list[StructureObservation])

• aliases (list[str])

• metadata (dict[str, Any])

• extensions (dict[str, Any])

id: str

name: str

kind: str

status: str

collar: Collar

total_depth_md: float

trajectory: Trajectory

diameter: float | None = None

interval_logs: dict[str, list[LogInterval]]

structures: list[StructureObservation]

aliases: list[str]

metadata: dict[str, Any]

extensions: dict[str, Any]

collect_issues(path='borehole')

Parameters:

path (str)

Return type:

list[ValidationIssue]

class pycsamt.format.borehole.schema.PCBHDocument(document_id, created_at, created_by, crs, boreholes, units=<factory>, title='', description='', lithologies=<factory>, formations=<factory>, pcbh_version='0.1.0', azimuth_direction='clockwise', inclination_reference='vertical_down', depth_reference='collar', z_positive='up', metadata=<factory>, extensions=<factory>)

Bases: _Validatable, PyCSAMTObject, MetadataMixin

Root PCBH document containing one or more boreholes.

Parameters:

• document_id (str)

• created_at (str)

• created_by (str)

• crs (CoordinateReferenceSystem)

• boreholes (list[PCBHBorehole])

• units (UnitSystem)

• title (str)

• description (str)

• lithologies (list[VocabularyEntry])

• formations (list[VocabularyEntry])

• pcbh_version (str)

• azimuth_direction (str)

• inclination_reference (str)

• depth_reference (str)

• z_positive (str)

• metadata (dict[str, Any])

• extensions (dict[str, Any])

document_id: str

created_at: str

created_by: str

crs: CoordinateReferenceSystem

boreholes: list[PCBHBorehole]

units: UnitSystem

title: str = ''

description: str = ''

lithologies: list[VocabularyEntry]

formations: list[VocabularyEntry]

pcbh_version: str = '0.1.0'

azimuth_direction: str = 'clockwise'

inclination_reference: str = 'vertical_down'

depth_reference: str = 'collar'

z_positive: str = 'up'

metadata: dict[str, Any]

extensions: dict[str, Any]

collect_issues(path='$')

Parameters:

path (str)

Return type:

list[ValidationIssue]