# lsdtools.models reference
URL: https://lsd.tools/docs/sdk-lsdtools-models
Updated: 2026-09-09

SDK distribution **1.0.0**; API contract **1.0**; generator **1.0.0**.

Product source digest: `4ea39055732e8883c03ccfecf12af6ccebd2041a12ce1b843e4a769e200f5ef9`.

Generated from declared public exports and source syntax. Signatures and annotations are declaration spellings; decorators, factories and annotations are never executed. Class members below are declared members; base classes remain explicit. Source docstrings describe their owning implementation; they do not grant app permissions.

```text
Lazy public access to LSD's SDF, block-model, and field-model services.

Domain packages should import this module through ``from lsdtools import models``
instead of naming product service distributions directly.  The bridge is deliberately
lazy: importing :mod:`lsdtools` or :mod:`lsdtools.models` does not import NumPy,
PyArrow, or any model service.

The services meet at one backend-neutral regional contract::

    from lsdtools import models

    candidate = models.oriented_box(
        center=(1000, 2000, -300),
        half_size=(15, 30, 4),
        axes=((1, 0, 0), (0, 0, 1), (0, -1, 0)),
    )
    query = models.regional_query(
        query_id="trial-17",
        region_id="study-worker-0",
        sdf=candidate,
        value_field="nsr_per_m3",
    )
    result = models.evaluate_region(backend, query)

Scalar service objects and result records are returned unchanged.  Batched
evaluation is normalized into :class:`RegionalBatchEvaluation`, so optimizers
can use native page-major block-model execution or an ordered scalar fallback
without importing either implementation package.  Optional services remain lazy
and missing or incompatible installations are mapped to
:class:`ModelServiceUnavailable`.

Structural discovery is normalized too: :func:`source_fields` returns typed
numeric field metadata without exposing Arrow, while
:func:`source_support_region` returns one validated physical-support frame.
```


## `lsdtools.models.BlockCellPageV1`

Kind: class. Source: `sdk/src/lsdtools/models.py:470`.

Source docstring:

```text
One immutable bounded page in canonical source order.

Array values are NumPy arrays only after this lazy API is called; importing
:mod:`lsdtools.models` itself remains free of NumPy and PyArrow.
```


### `lsdtools.models.BlockCellPageV1.topology`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:477`.

```python
topology: BlockCellTopologyV1
```


### `lsdtools.models.BlockCellPageV1.page_index`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:478`.

```python
page_index: int
```


### `lsdtools.models.BlockCellPageV1.row_offset`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:479`.

```python
row_offset: int
```


### `lsdtools.models.BlockCellPageV1.centers`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:480`.

```python
centers: Any
```


### `lsdtools.models.BlockCellPageV1.edge_lengths`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:481`.

```python
edge_lengths: Any
```


### `lsdtools.models.BlockCellPageV1.parent_ids`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:482`.

```python
parent_ids: Any
```


### `lsdtools.models.BlockCellPageV1.subblock_ids`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:483`.

```python
subblock_ids: Any
```


### `lsdtools.models.BlockCellPageV1.cell_ids`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:484`.

```python
cell_ids: Any
```


### `lsdtools.models.BlockCellPageV1.field_names`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:485`.

```python
field_names: tuple[str, ...]
```


### `lsdtools.models.BlockCellPageV1.fields`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:486`.

```python
fields: tuple[Any, ...]
```


### `lsdtools.models.BlockCellPageV1.field_presence`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:487`.

```python
field_presence: tuple[Any | None, ...]
```


### `lsdtools.models.BlockCellPageV1.accounted_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:488`.

```python
accounted_bytes: int
```


### `lsdtools.models.BlockCellPageV1.field`

Kind: method. Source: `sdk/src/lsdtools/models.py:586`.

```python
field(self, name: str) -> tuple[Any, Any | None]
```


```python
name: str
self: (unannotated)
```


Source docstring:

```text
Return one field and its optional present-row mask.
```


### `lsdtools.models.BlockCellPageV1.world_edge_vectors`

Kind: method. Source: `sdk/src/lsdtools/models.py:595`.

```python
world_edge_vectors(self) -> Any
```


```python
self: (unannotated)
```


Source docstring:

```text
Return ``(row, u/v/w, world-x/y/z)`` oriented edge vectors.
```


## `lsdtools.models.BlockCellSourceV1`

Kind: class. Source: `sdk/src/lsdtools/models.py:607`.

Source docstring:

```text
Reusable public stream plan that hides its product-service source.
```


### `lsdtools.models.BlockCellSourceV1.topology`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:610`.

```python
topology: BlockCellTopologyV1
```


### `lsdtools.models.BlockCellSourceV1.iter_pages`

Kind: method. Source: `sdk/src/lsdtools/models.py:619`.

```python
iter_pages(self) -> Iterator[BlockCellPageV1]
```


```python
self: (unannotated)
```


Source docstring:

```text
Yield a fresh validated pass over the source.
```


## `lsdtools.models.BlockCellTopologyError`

Kind: class. Source: `sdk/src/lsdtools/models.py:168`.

Source docstring:

```text
A source cannot satisfy the canonical block-cell topology contract.
```


Declared bases: `ValueError`.

## `lsdtools.models.BlockCellTopologyV1`

Kind: class. Source: `sdk/src/lsdtools/models.py:338`.

Source docstring:

```text
Immutable, service-neutral topology for canonical block-cell pages.

Orientation axes are rows in world XYZ coordinates.  Both right- and
left-handed bases are valid and retained exactly; consumers must not
replace them with a cross-product-derived right-handed frame.
```


### `lsdtools.models.BlockCellTopologyV1.contract_version`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:346`.

```python
contract_version: Literal['lsd-block-cell-topology-v1']
```


### `lsdtools.models.BlockCellTopologyV1.geometry_kind`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:347`.

```python
geometry_kind: Literal['regular', 'tensor', 'regular-subblock', 'octree-subblock', 'arbitrary-subblock', 'explicit-cells']
```


### `lsdtools.models.BlockCellTopologyV1.geometry_exactness`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:355`.

```python
geometry_exactness: str
```


### `lsdtools.models.BlockCellTopologyV1.origin`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:356`.

```python
origin: tuple[float, float, float] | None
```


### `lsdtools.models.BlockCellTopologyV1.orientation_axes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:357`.

```python
orientation_axes: tuple[tuple[float, float, float], ...]
```


### `lsdtools.models.BlockCellTopologyV1.handedness`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:358`.

```python
handedness: Literal['left', 'right']
```


### `lsdtools.models.BlockCellTopologyV1.ordering`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:359`.

```python
ordering: str
```


### `lsdtools.models.BlockCellTopologyV1.cell_count`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:360`.

```python
cell_count: int | None
```


### `lsdtools.models.BlockCellTopologyV1.parent_cell_count`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:361`.

```python
parent_cell_count: int | None
```


### `lsdtools.models.BlockCellTopologyV1.active_parent_count`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:362`.

```python
active_parent_count: int | None
```


### `lsdtools.models.BlockCellTopologyV1.field_names`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:363`.

```python
field_names: tuple[str, ...]
```


### `lsdtools.models.BlockCellTopologyV1.cell_id_semantics`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:364`.

```python
cell_id_semantics: str
```


### `lsdtools.models.BlockCellTopologyV1.parent_id_semantics`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:365`.

```python
parent_id_semantics: str
```


### `lsdtools.models.BlockCellTopologyV1.subblock_id_semantics`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:366`.

```python
subblock_id_semantics: str
```


### `lsdtools.models.BlockCellTopologyV1.source_fingerprint`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:367`.

```python
source_fingerprint: str
```


### `lsdtools.models.BlockCellTopologyV1.source_fingerprint_semantics`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:368`.

```python
source_fingerprint_semantics: str
```


### `lsdtools.models.BlockCellTopologyV1.storage_fingerprint`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:369`.

```python
storage_fingerprint: str | None
```


```python
storage_fingerprint = None
```


### `lsdtools.models.BlockCellTopologyV1.storage_fingerprint_semantics`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:370`.

```python
storage_fingerprint_semantics: str | None
```


```python
storage_fingerprint_semantics = None
```


## `lsdtools.models.CancellationSignal`

Kind: class. Source: `sdk/src/lsdtools/models.py:136`.

Source docstring:

```text
Cooperative cancellation accepted by regional batch evaluation.

:class:`threading.Event` satisfies this protocol.  A zero-argument callable
is accepted by :func:`evaluate_regions` as a convenience and is adapted to
this protocol before a native backend sees it.
```


Declared bases: `Protocol`.

### `lsdtools.models.CancellationSignal.is_set`

Kind: method. Source: `sdk/src/lsdtools/models.py:144`.

```python
is_set(self) -> bool
```


```python
self: (unannotated)
```


## `lsdtools.models.ModelBatchPlanningCapabilities`

Kind: class. Source: `sdk/src/lsdtools/models.py:703`.

Source docstring:

```text
Optional backend-neutral hints for optimizer batch partitioning.

``accelerator_available=None`` means the caller chose side-effect-free
discovery and no runtime accelerator probe was made.  These are planning
hints, not a promise that an individual query batch will select a given
execution backend after its full compatibility and memory preflight.
```


### `lsdtools.models.ModelBatchPlanningCapabilities.configured_compute_backend`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:712`.

```python
configured_compute_backend: str | None
```


### `lsdtools.models.ModelBatchPlanningCapabilities.accelerator`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:713`.

```python
accelerator: str | None
```


### `lsdtools.models.ModelBatchPlanningCapabilities.accelerator_available`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:714`.

```python
accelerator_available: bool | None
```


### `lsdtools.models.ModelBatchPlanningCapabilities.recommended_policy`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:715`.

```python
recommended_policy: str | None
```


### `lsdtools.models.ModelBatchPlanningCapabilities.recommended_max_queries`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:716`.

```python
recommended_max_queries: int | None
```


## `lsdtools.models.ModelEvaluationCancelled`

Kind: class. Source: `sdk/src/lsdtools/models.py:147`.

Source docstring:

```text
A model operation was cancelled before any result was published.
```


Declared bases: `RuntimeError`.

## `lsdtools.models.ModelEvaluationCapabilities`

Kind: class. Source: `sdk/src/lsdtools/models.py:720`.

Source docstring:

```text
Backend-neutral discovery for scalar and native batch execution.

``supported_evaluation_options`` is the union accepted somewhere on this
opened backend. ``scalar_options`` and ``native_batch_options`` are the
dispatch-specific truth and should drive higher-level option forwarding.
Resource controls are native-only; scalar cancellation means one long
scalar evaluation, not merely cancellation checks between queries.
```


### `lsdtools.models.ModelEvaluationCapabilities.backend_name`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:730`.

```python
backend_name: str
```


### `lsdtools.models.ModelEvaluationCapabilities.backend_version`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:731`.

```python
backend_version: str | None
```


### `lsdtools.models.ModelEvaluationCapabilities.scalar`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:732`.

```python
scalar: bool
```


### `lsdtools.models.ModelEvaluationCapabilities.native_batch`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:733`.

```python
native_batch: bool
```


### `lsdtools.models.ModelEvaluationCapabilities.native_batch_min_queries`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:734`.

```python
native_batch_min_queries: int | None
```


### `lsdtools.models.ModelEvaluationCapabilities.scalar_cancellation`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:735`.

```python
scalar_cancellation: bool
```


### `lsdtools.models.ModelEvaluationCapabilities.evaluation_stats`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:736`.

```python
evaluation_stats: bool
```


### `lsdtools.models.ModelEvaluationCapabilities.cache_telemetry`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:737`.

```python
cache_telemetry: bool
```


### `lsdtools.models.ModelEvaluationCapabilities.new_worker`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:738`.

```python
new_worker: bool
```


### `lsdtools.models.ModelEvaluationCapabilities.supported_evaluation_options`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:739`.

```python
supported_evaluation_options: frozenset[str]
```


### `lsdtools.models.ModelEvaluationCapabilities.scalar_options`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:740`.

```python
scalar_options: frozenset[str]
```


### `lsdtools.models.ModelEvaluationCapabilities.native_batch_options`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:741`.

```python
native_batch_options: frozenset[str]
```


### `lsdtools.models.ModelEvaluationCapabilities.batch_planning`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:742`.

```python
batch_planning: ModelBatchPlanningCapabilities | None
```


```python
batch_planning = None
```


## `lsdtools.models.ModelFieldInfo`

Kind: class. Source: `sdk/src/lsdtools/models.py:264`.

Source docstring:

```text
One numeric model source field without a backend schema dependency.
```


### `lsdtools.models.ModelFieldInfo.name`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:267`.

```python
name: str
```


### `lsdtools.models.ModelFieldInfo.scalar_kind`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:268`.

```python
scalar_kind: Literal['integer', 'floating']
```


### `lsdtools.models.ModelFieldInfo.nullable`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:269`.

```python
nullable: bool
```


### `lsdtools.models.ModelFieldInfo.role`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:270`.

```python
role: Literal['coordinate', 'dimension', 'volume', 'attribute']
```


## `lsdtools.models.ModelQueryLimitError`

Kind: class. Source: `sdk/src/lsdtools/models.py:164`.

Source docstring:

```text
A query iterable exceeded the caller's explicit ingestion bound.
```


Declared bases: `ValueError`.

## `lsdtools.models.ModelRegionFamilyCapabilities`

Kind: class. Source: `sdk/src/lsdtools/models.py:746`.

Source docstring:

```text
Backend-neutral discovery for immutable prepared region families.

An empty ``supported_family_kinds`` set with ``candidate_mode='none'`` is
the ordinary answer for a backend without this optional optimization.
Capability discovery never infers support from similarly named methods:
the backend must advertise the exact family kind before preparation can
start. ``available`` is specific to the opened backend's configured
compute mode; ``backend_reason`` explains that selection or why an
otherwise supported family cannot run in that configuration.
```


### `lsdtools.models.ModelRegionFamilyCapabilities.backend_name`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:758`.

```python
backend_name: str
```


### `lsdtools.models.ModelRegionFamilyCapabilities.backend_version`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:759`.

```python
backend_version: str | None
```


### `lsdtools.models.ModelRegionFamilyCapabilities.supported_family_kinds`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:760`.

```python
supported_family_kinds: frozenset[str]
```


### `lsdtools.models.ModelRegionFamilyCapabilities.exact_metrics`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:761`.

```python
exact_metrics: frozenset[str]
```


### `lsdtools.models.ModelRegionFamilyCapabilities.candidate_mode`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:762`.

```python
candidate_mode: Literal['online', 'finite_batch', 'none']
```


### `lsdtools.models.ModelRegionFamilyCapabilities.compute_backends`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:763`.

```python
compute_backends: frozenset[str]
```


### `lsdtools.models.ModelRegionFamilyCapabilities.exact_geometry`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:764`.

```python
exact_geometry: bool
```


### `lsdtools.models.ModelRegionFamilyCapabilities.available`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:765`.

```python
available: bool
```


```python
available = True
```


### `lsdtools.models.ModelRegionFamilyCapabilities.backend_reason`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:766`.

```python
backend_reason: str | None
```


```python
backend_reason = None
```


## `lsdtools.models.ModelServiceUnavailable`

Kind: class. Source: `sdk/src/lsdtools/models.py:124`.

```python
ModelServiceUnavailable(self, service: str, detail: str | None=None) -> None
```


Source docstring:

```text
A requested model-query service is absent or incompatible with LSD.
```


Declared bases: `RuntimeError`.

### `lsdtools.models.ModelServiceUnavailable.__init__`

Kind: method. Source: `sdk/src/lsdtools/models.py:127`.

```python
__init__(self, service: str, detail: str | None=None) -> None
```


```python
detail: str | None
self: (unannotated)
service: str
```


### `lsdtools.models.ModelServiceUnavailable.service`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:128`.

```python
service: str
```


```python
service = service
```


## `lsdtools.models.ModelSpatialRegion`

Kind: class. Source: `sdk/src/lsdtools/models.py:626`.

Source docstring:

```text
Backend-neutral minimum bounding box of physical source support.

``axes`` contains the ordered local box X/Y/Z unit axes as rows in world
coordinates, using the same row-basis convention accepted by
:func:`oriented_box`.  These are source/support-box axes, not a mining
method's U/V/W remapping.  The v1 backends return the world XYZ frame,
while retaining the explicit frame fields avoids a future contract change
when exact oriented support becomes available.
```


### `lsdtools.models.ModelSpatialRegion.center_world`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:637`.

```python
center_world: tuple[float, float, float]
```


### `lsdtools.models.ModelSpatialRegion.half_size`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:638`.

```python
half_size: tuple[float, float, float]
```


### `lsdtools.models.ModelSpatialRegion.axes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:639`.

```python
axes: tuple[tuple[float, float, float], ...]
```


### `lsdtools.models.ModelSpatialRegion.world_aabb_lower`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:640`.

```python
world_aabb_lower: tuple[float, float, float]
```


### `lsdtools.models.ModelSpatialRegion.world_aabb_upper`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:641`.

```python
world_aabb_upper: tuple[float, float, float]
```


### `lsdtools.models.ModelSpatialRegion.support_kind`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:642`.

```python
support_kind: Literal['occupied_block_cells']
```


### `lsdtools.models.ModelSpatialRegion.source_count`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:643`.

```python
source_count: int
```


### `lsdtools.models.ModelSpatialRegion.transform_fingerprint`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:644`.

```python
transform_fingerprint: str
```


### `lsdtools.models.ModelSpatialRegion.semantics`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:645`.

```python
semantics: Literal['minimum_axes_aligned_bounding_box_of_physical_support']
```


```python
semantics = _MODEL_SPATIAL_REGION_SEMANTICS
```


## `lsdtools.models.OrientedPointSdfBuildV1`

Kind: class. Source: `sdk/src/lsdtools/models.py:1027`.

Source docstring:

```text
One qualified immutable SDF, canonical artifact, and audit envelope.

``sdf`` is the one intentionally opaque service value: pass it unchanged
to ``lsd_geometry.build_sdf_surface`` or the other structural SDF consumers.
The SDF remains the geometry authority; any extracted mesh is derivative.
All other returned records are SDK-owned primitives or immutable bytes, so
packages never need to import ``lsd_sdf`` types.
```


### `lsdtools.models.OrientedPointSdfBuildV1.sdf`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1037`.

```python
sdf: Any
```


### `lsdtools.models.OrientedPointSdfBuildV1.artifact`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1038`.

```python
artifact: bytes
```


### `lsdtools.models.OrientedPointSdfBuildV1.receipt`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1039`.

```python
receipt: bytes
```


### `lsdtools.models.OrientedPointSdfBuildV1.diagnostics`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1040`.

```python
diagnostics: bytes
```


### `lsdtools.models.OrientedPointSdfBuildV1.resources`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1041`.

```python
resources: OrientedPointSdfResourceUsageV1
```


### `lsdtools.models.OrientedPointSdfBuildV1.point_set_fingerprint`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1042`.

```python
point_set_fingerprint: str
```


### `lsdtools.models.OrientedPointSdfBuildV1.artifact_digest`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1043`.

```python
artifact_digest: str
```


### `lsdtools.models.OrientedPointSdfBuildV1.behavior_fingerprint`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1044`.

```python
behavior_fingerprint: str
```


### `lsdtools.models.OrientedPointSdfBuildV1.method`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1045`.

```python
method: str
```


### `lsdtools.models.OrientedPointSdfBuildV1.backend`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1046`.

```python
backend: str
```


## `lsdtools.models.OrientedPointSdfConfigV1`

Kind: class. Source: `sdk/src/lsdtools/models.py:904`.

Source docstring:

```text
Every physical and scientific choice for one deterministic v1 build.

No scientific defaults are supplied. ``outward_normals`` passed to
:func:`build_oriented_point_sdf` must be unit vectors pointing from the
desired negative-inside region toward the positive outside. The six face
policies are ordered by the SDF service's reconstruction-grid convention.

This configuration does not infer survey topology, line discretization,
units, CRS, normal polarity, multi-unit precedence, or whether the solid
represents rock, void, or ore. Those decisions remain with the domain
package. ``base_sdf`` remains an explicit build argument because it is the
caller-approved closed far-field topology, not a tuning option.

This is an import-light immutable transport. The numerical service remains
the single authority for FP64 and cross-field validation when the build is
requested; the SDK deliberately does not duplicate those scientific rules.
```


### `lsdtools.models.OrientedPointSdfConfigV1.grid_origin`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:923`.

```python
grid_origin: tuple[float, float, float]
```


### `lsdtools.models.OrientedPointSdfConfigV1.grid_spacing`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:924`.

```python
grid_spacing: tuple[float, float, float]
```


### `lsdtools.models.OrientedPointSdfConfigV1.grid_cell_shape`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:925`.

```python
grid_cell_shape: tuple[int, int, int]
```


### `lsdtools.models.OrientedPointSdfConfigV1.support_radius`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:926`.

```python
support_radius: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.core_radius`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:927`.

```python
core_radius: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.transition_radius`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:928`.

```python
transition_radius: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.normal_cosine_minimum`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:929`.

```python
normal_cosine_minimum: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.minimum_compatible_neighbors`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:930`.

```python
minimum_compatible_neighbors: int
```


### `lsdtools.models.OrientedPointSdfConfigV1.minimum_weight_sum`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:931`.

```python
minimum_weight_sum: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.maximum_incompatible_weight_fraction`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:932`.

```python
maximum_incompatible_weight_fraction: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.saturation_distance`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:933`.

```python
saturation_distance: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.normal_probe_distance`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:934`.

```python
normal_probe_distance: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.minimum_gradient_norm`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:935`.

```python
minimum_gradient_norm: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.gradient_normal_cosine_minimum`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:936`.

```python
gradient_normal_cosine_minimum: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.roi_clearance`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:937`.

```python
roi_clearance: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.point_residual_tolerance`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:938`.

```python
point_residual_tolerance: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.signed_probe_margin`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:939`.

```python
signed_probe_margin: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.face_positive_margin`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:940`.

```python
face_positive_margin: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.base_transition_diagnostic_margin`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:941`.

```python
base_transition_diagnostic_margin: float
```


### `lsdtools.models.OrientedPointSdfConfigV1.roi_face_policies`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:942`.

```python
roi_face_policies: tuple[Literal['cap_v1', 'reject_contact_v1'], ...]
```


### `lsdtools.models.OrientedPointSdfConfigV1.brick_cells`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:945`.

```python
brick_cells: int
```


## `lsdtools.models.OrientedPointSdfQualificationError`

Kind: class. Source: `sdk/src/lsdtools/models.py:1049`.

```python
OrientedPointSdfQualificationError(self, failed_gates: object, diagnostics: bytes) -> None
```


Source docstring:

```text
A deterministic build failed its scientific gates and published no SDF.
```


Declared bases: `RuntimeError`.

### `lsdtools.models.OrientedPointSdfQualificationError.__init__`

Kind: method. Source: `sdk/src/lsdtools/models.py:1052`.

```python
__init__(self, failed_gates: object, diagnostics: bytes) -> None
```


```python
diagnostics: bytes
failed_gates: object
self: (unannotated)
```


### `lsdtools.models.OrientedPointSdfQualificationError.failed_gates`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1060`.

```python
failed_gates: (unannotated)
```


```python
failed_gates = gates
```


### `lsdtools.models.OrientedPointSdfQualificationError.diagnostics`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1061`.

```python
diagnostics: bytes
```


```python
diagnostics = diagnostics
```


## `lsdtools.models.OrientedPointSdfResourceLimitError`

Kind: class. Source: `sdk/src/lsdtools/models.py:1067`.

```python
OrientedPointSdfResourceLimitError(self, resource: str, required: int, limit: int) -> None
```


Source docstring:

```text
One oriented-point build requirement exceeded a caller-owned budget.
```


Declared bases: `RuntimeError`.

### `lsdtools.models.OrientedPointSdfResourceLimitError.__init__`

Kind: method. Source: `sdk/src/lsdtools/models.py:1070`.

```python
__init__(self, resource: str, required: int, limit: int) -> None
```


```python
limit: int
required: int
resource: str
self: (unannotated)
```


### `lsdtools.models.OrientedPointSdfResourceLimitError.resource`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1077`.

```python
resource: str
```


```python
resource = resource
```


### `lsdtools.models.OrientedPointSdfResourceLimitError.required`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1078`.

```python
required: int
```


```python
required = required
```


### `lsdtools.models.OrientedPointSdfResourceLimitError.limit`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1079`.

```python
limit: int
```


```python
limit = limit
```


## `lsdtools.models.OrientedPointSdfResourceLimitsV1`

Kind: class. Source: `sdk/src/lsdtools/models.py:948`.

Source docstring:

```text
Finite caller-owned admission budgets for preparation and compilation.

These are limits, not scientific parameters and not hidden SDK defaults.
Preparation and compilation have separate retained/transient byte ceilings
because no service-owned native limit type crosses this facade. Admission
and relationships between budgets remain validated by the SDF service.
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_points`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:957`.

```python
max_points: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_input_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:958`.

```python
max_input_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.preparation_max_retained_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:959`.

```python
preparation_max_retained_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.preparation_max_transient_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:960`.

```python
preparation_max_transient_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.preparation_batch_rows`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:961`.

```python
preparation_batch_rows: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_logical_cells`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:962`.

```python
max_logical_cells: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_logical_vertices`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:963`.

```python
max_logical_vertices: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_depth`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:964`.

```python
max_depth: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_active_vertices`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:965`.

```python
max_active_vertices: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_neighbor_contributions`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:966`.

```python
max_neighbor_contributions: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_point_index_nodes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:967`.

```python
max_point_index_nodes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_tree_nodes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:968`.

```python
max_tree_nodes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_bricks`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:969`.

```python
max_bricks: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.compilation_max_retained_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:970`.

```python
compilation_max_retained_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.compilation_max_transient_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:971`.

```python
compilation_max_transient_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_qualification_work`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:972`.

```python
max_qualification_work: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_hash_work`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:973`.

```python
max_hash_work: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_codec_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:974`.

```python
max_codec_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.max_codec_hash_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:975`.

```python
max_codec_hash_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.compilation_batch_rows`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:976`.

```python
compilation_batch_rows: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.base_max_operations`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:977`.

```python
base_max_operations: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.base_max_program_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:978`.

```python
base_max_program_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.base_max_transient_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:979`.

```python
base_max_transient_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.base_max_translation_depth`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:980`.

```python
base_max_translation_depth: int
```


### `lsdtools.models.OrientedPointSdfResourceLimitsV1.base_max_value_stack_depth`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:981`.

```python
base_max_value_stack_depth: int
```


## `lsdtools.models.OrientedPointSdfResourceUsageV1`

Kind: class. Source: `sdk/src/lsdtools/models.py:1005`.

Source docstring:

```text
Service-neutral immutable resource telemetry for one accepted build.
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.input_points`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1008`.

```python
input_points: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.input_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1009`.

```python
input_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.logical_cells`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1010`.

```python
logical_cells: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.logical_vertices`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1011`.

```python
logical_vertices: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.active_vertices`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1012`.

```python
active_vertices: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.neighbor_contributions`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1013`.

```python
neighbor_contributions: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.point_index_nodes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1014`.

```python
point_index_nodes: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.tree_nodes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1015`.

```python
tree_nodes: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.constant_terminals`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1016`.

```python
constant_terminals: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.bricks`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1017`.

```python
bricks: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.retained_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1018`.

```python
retained_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.peak_transient_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1019`.

```python
peak_transient_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.qualification_work`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1020`.

```python
qualification_work: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.hash_work`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1021`.

```python
hash_work: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.codec_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1022`.

```python
codec_bytes: int
```


### `lsdtools.models.OrientedPointSdfResourceUsageV1.codec_hash_bytes`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:1023`.

```python
codec_hash_bytes: int
```


## `lsdtools.models.PreparedRegionFamily`

Kind: class. Source: `sdk/src/lsdtools/models.py:2662`.

```python
PreparedRegionFamily(self, *, backend: Any, native_handle: Any, family: Any, filters: tuple[Any, ...], field_program: Any | None, info: PreparedRegionFamilyInfo, preparation_stats: RegionalFamilyPreparationStats, evaluate_hook: Callable[..., Any], materialize_hook: Callable[..., Any], close_hook: Callable[..., Any]) -> None
```


Source docstring:

```text
Public lifecycle wrapper around one opaque backend-owned family index.

The wrapper retains its backend strongly, supports exactly one active
operation, and never exposes the native handle.  Parallel optimizers use
one prepared handle per backend worker.  Closing is idempotent after a
successful or failed native close; a possibly half-closed native handle is
never made usable again.
```


### `lsdtools.models.PreparedRegionFamily.__init__`

Kind: method. Source: `sdk/src/lsdtools/models.py:2688`.

```python
__init__(self, *, backend: Any, native_handle: Any, family: Any, filters: tuple[Any, ...], field_program: Any | None, info: PreparedRegionFamilyInfo, preparation_stats: RegionalFamilyPreparationStats, evaluate_hook: Callable[..., Any], materialize_hook: Callable[..., Any], close_hook: Callable[..., Any]) -> None
```


```python
backend: Any
close_hook: Callable[..., Any]
evaluate_hook: Callable[..., Any]
family: Any
field_program: Any | None
filters: tuple[Any, ...]
info: PreparedRegionFamilyInfo
materialize_hook: Callable[..., Any]
native_handle: Any
preparation_stats: RegionalFamilyPreparationStats
self: (unannotated)
```


### `lsdtools.models.PreparedRegionFamily.info`

Kind: method. Source: `sdk/src/lsdtools/models.py:2717`.

```python
info(self) -> PreparedRegionFamilyInfo
```


```python
self: (unannotated)
```


### `lsdtools.models.PreparedRegionFamily.preparation_stats`

Kind: method. Source: `sdk/src/lsdtools/models.py:2721`.

```python
preparation_stats(self) -> RegionalFamilyPreparationStats
```


```python
self: (unannotated)
```


### `lsdtools.models.PreparedRegionFamily.closed`

Kind: method. Source: `sdk/src/lsdtools/models.py:2725`.

```python
closed(self) -> bool
```


```python
self: (unannotated)
```


### `lsdtools.models.PreparedRegionFamily.evaluate`

Kind: method. Source: `sdk/src/lsdtools/models.py:2745`.

```python
evaluate(self, candidates: Iterable[Any], /, *, cancel: CancellationSignal | Callable[[], object] | None=None, max_candidates: int=65536, max_workspace_bytes: int=64 * 1024 * 1024) -> RegionalFamilyEvaluation
```


```python
cancel: CancellationSignal | Callable[[], object] | None
candidates: Iterable[Any]
max_candidates: int
max_workspace_bytes: int
self: (unannotated)
```


### `lsdtools.models.PreparedRegionFamily.materialize_query`

Kind: method. Source: `sdk/src/lsdtools/models.py:2762`.

```python
materialize_query(self, candidate: Any, /) -> Any
```


```python
candidate: Any
self: (unannotated)
```


### `lsdtools.models.PreparedRegionFamily.close`

Kind: method. Source: `sdk/src/lsdtools/models.py:2765`.

```python
close(self) -> None
```


```python
self: (unannotated)
```


### `lsdtools.models.PreparedRegionFamily.__enter__`

Kind: method. Source: `sdk/src/lsdtools/models.py:2768`.

```python
__enter__(self) -> PreparedRegionFamily
```


```python
self: (unannotated)
```


### `lsdtools.models.PreparedRegionFamily.__exit__`

Kind: method. Source: `sdk/src/lsdtools/models.py:2774`.

```python
__exit__(self, exc_type: Any, exc_value: Any, traceback: Any) -> bool
```


```python
exc_type: Any
exc_value: Any
self: (unannotated)
traceback: Any
```


## `lsdtools.models.PreparedRegionFamilyInfo`

Kind: class. Source: `sdk/src/lsdtools/models.py:770`.

Source docstring:

```text
Stable identity visible from one backend-owned prepared handle.
```


### `lsdtools.models.PreparedRegionFamilyInfo.backend_name`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:773`.

```python
backend_name: str
```


### `lsdtools.models.PreparedRegionFamilyInfo.backend_version`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:774`.

```python
backend_version: str | None
```


### `lsdtools.models.PreparedRegionFamilyInfo.family_kind`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:775`.

```python
family_kind: str
```


### `lsdtools.models.PreparedRegionFamilyInfo.family_fingerprint`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:776`.

```python
family_fingerprint: str
```


### `lsdtools.models.PreparedRegionFamilyInfo.region_id`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:777`.

```python
region_id: str
```


### `lsdtools.models.PreparedRegionFamilyInfo.value_field`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:778`.

```python
value_field: str
```


### `lsdtools.models.PreparedRegionFamilyInfo.weight_field`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:779`.

```python
weight_field: str | None
```


### `lsdtools.models.PreparedRegionFamilyInfo.requested_metrics`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:780`.

```python
requested_metrics: tuple[str, ...]
```


### `lsdtools.models.PreparedRegionFamilyInfo.candidate_mode`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:781`.

```python
candidate_mode: Literal['online', 'finite_batch']
```


### `lsdtools.models.PreparedRegionFamilyInfo.exact_geometry`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:782`.

```python
exact_geometry: bool
```


### `lsdtools.models.PreparedRegionFamilyInfo.preparation_fingerprint`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:783`.

```python
preparation_fingerprint: str | None
```


```python
preparation_fingerprint = None
```


### `lsdtools.models.PreparedRegionFamilyInfo.source_fingerprint`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:784`.

```python
source_fingerprint: str | None
```


```python
source_fingerprint = None
```


### `lsdtools.models.PreparedRegionFamilyInfo.transform_fingerprint`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:785`.

```python
transform_fingerprint: str | None
```


```python
transform_fingerprint = None
```


### `lsdtools.models.PreparedRegionFamilyInfo.selected_compute_backend`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:786`.

```python
selected_compute_backend: str | None
```


```python
selected_compute_backend = None
```


### `lsdtools.models.PreparedRegionFamilyInfo.native_info`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:787`.

```python
native_info: object | None
```


```python
native_info = None
```


## `lsdtools.models.RegionalBatchEvaluation`

Kind: class. Source: `sdk/src/lsdtools/models.py:858`.

Source docstring:

```text
Complete ordered results plus backend-neutral shared execution facts.
```


### `lsdtools.models.RegionalBatchEvaluation.results`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:861`.

```python
results: tuple[Any, ...]
```


### `lsdtools.models.RegionalBatchEvaluation.stats`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:862`.

```python
stats: RegionalBatchExecutionStats
```


## `lsdtools.models.RegionalBatchExecutionStats`

Kind: class. Source: `sdk/src/lsdtools/models.py:830`.

Source docstring:

```text
Stable dispatch facts for one complete regional evaluation request.

``native_stats`` retains a native backend's rich measured statistics
without making that service-specific DTO part of the lsdtools contract.
``evaluation_stats`` is populated only when callers opt into scalar
telemetry. ``cache_telemetry`` is one optional post-request residency
snapshot. Atomicity applies to the returned result tuple: scalar
evaluations can warm or replace worker-local caches before a later query
or telemetry snapshot fails, and those cache effects are deliberately not
rolled back.
```


### `lsdtools.models.RegionalBatchExecutionStats.dispatch`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:843`.

```python
dispatch: str
```


### `lsdtools.models.RegionalBatchExecutionStats.backend_name`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:844`.

```python
backend_name: str
```


### `lsdtools.models.RegionalBatchExecutionStats.backend_version`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:845`.

```python
backend_version: str | None
```


### `lsdtools.models.RegionalBatchExecutionStats.elapsed_seconds`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:846`.

```python
elapsed_seconds: float
```


### `lsdtools.models.RegionalBatchExecutionStats.query_count`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:847`.

```python
query_count: int
```


### `lsdtools.models.RegionalBatchExecutionStats.native_batch`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:848`.

```python
native_batch: bool
```


### `lsdtools.models.RegionalBatchExecutionStats.atomic_results`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:849`.

```python
atomic_results: bool
```


### `lsdtools.models.RegionalBatchExecutionStats.cache_effects_rolled_back`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:850`.

```python
cache_effects_rolled_back: bool
```


### `lsdtools.models.RegionalBatchExecutionStats.cancellation_checks`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:851`.

```python
cancellation_checks: int
```


### `lsdtools.models.RegionalBatchExecutionStats.native_stats`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:852`.

```python
native_stats: object | None
```


```python
native_stats = None
```


### `lsdtools.models.RegionalBatchExecutionStats.evaluation_stats`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:853`.

```python
evaluation_stats: tuple[object | None, ...]
```


```python
evaluation_stats = ()
```


### `lsdtools.models.RegionalBatchExecutionStats.cache_telemetry`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:854`.

```python
cache_telemetry: object | None
```


```python
cache_telemetry = None
```


## `lsdtools.models.RegionalFamilyEvaluation`

Kind: class. Source: `sdk/src/lsdtools/models.py:822`.

Source docstring:

```text
Ordered ordinary regional results plus prepared-family telemetry.
```


### `lsdtools.models.RegionalFamilyEvaluation.results`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:825`.

```python
results: tuple[Any, ...]
```


### `lsdtools.models.RegionalFamilyEvaluation.stats`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:826`.

```python
stats: RegionalFamilyExecutionStats
```


## `lsdtools.models.RegionalFamilyExecutionStats`

Kind: class. Source: `sdk/src/lsdtools/models.py:805`.

Source docstring:

```text
Stable execution facts for one complete prepared-family request.
```


### `lsdtools.models.RegionalFamilyExecutionStats.dispatch`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:808`.

```python
dispatch: str
```


### `lsdtools.models.RegionalFamilyExecutionStats.backend_name`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:809`.

```python
backend_name: str
```


### `lsdtools.models.RegionalFamilyExecutionStats.backend_version`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:810`.

```python
backend_version: str | None
```


### `lsdtools.models.RegionalFamilyExecutionStats.elapsed_seconds`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:811`.

```python
elapsed_seconds: float
```


### `lsdtools.models.RegionalFamilyExecutionStats.candidate_count`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:812`.

```python
candidate_count: int
```


### `lsdtools.models.RegionalFamilyExecutionStats.unique_candidate_count`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:813`.

```python
unique_candidate_count: int
```


### `lsdtools.models.RegionalFamilyExecutionStats.native_prepared`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:814`.

```python
native_prepared: bool
```


### `lsdtools.models.RegionalFamilyExecutionStats.atomic_results`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:815`.

```python
atomic_results: bool
```


### `lsdtools.models.RegionalFamilyExecutionStats.cache_effects_rolled_back`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:816`.

```python
cache_effects_rolled_back: bool
```


### `lsdtools.models.RegionalFamilyExecutionStats.cancellation_checks`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:817`.

```python
cancellation_checks: int
```


### `lsdtools.models.RegionalFamilyExecutionStats.native_stats`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:818`.

```python
native_stats: object | None
```


```python
native_stats = None
```


## `lsdtools.models.RegionalFamilyPreparationStats`

Kind: class. Source: `sdk/src/lsdtools/models.py:791`.

Source docstring:

```text
Facade and native telemetry for an atomically prepared family.
```


### `lsdtools.models.RegionalFamilyPreparationStats.backend_name`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:794`.

```python
backend_name: str
```


### `lsdtools.models.RegionalFamilyPreparationStats.backend_version`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:795`.

```python
backend_version: str | None
```


### `lsdtools.models.RegionalFamilyPreparationStats.elapsed_seconds`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:796`.

```python
elapsed_seconds: float
```


### `lsdtools.models.RegionalFamilyPreparationStats.family_kind`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:797`.

```python
family_kind: str
```


### `lsdtools.models.RegionalFamilyPreparationStats.family_fingerprint`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:798`.

```python
family_fingerprint: str
```


### `lsdtools.models.RegionalFamilyPreparationStats.atomic_handle`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:799`.

```python
atomic_handle: bool
```


### `lsdtools.models.RegionalFamilyPreparationStats.cancellation_checks`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:800`.

```python
cancellation_checks: int
```


### `lsdtools.models.RegionalFamilyPreparationStats.native_stats`

Kind: attribute. Source: `sdk/src/lsdtools/models.py:801`.

```python
native_stats: object | None
```


```python
native_stats = None
```


## `lsdtools.models.UnsupportedModelEvaluationOption`

Kind: class. Source: `sdk/src/lsdtools/models.py:151`.

Source docstring:

```text
An explicitly requested control is not implemented by this backend/dispatch.
```


Declared bases: `ValueError`.

## `lsdtools.models.UnsupportedModelRegionFamily`

Kind: class. Source: `sdk/src/lsdtools/models.py:155`.

Source docstring:

```text
A backend does not advertise the requested immutable region family.

This is a pre-dispatch capability failure.  Callers may explicitly fall
back to ordinary :func:`evaluate_regions` without risking a duplicate
model scan or partially published prepared result.
```


Declared bases: `ValueError`.

## `lsdtools.models.affine_box`

Kind: function. Source: `sdk/src/lsdtools/models.py:1386`.

```python
affine_box(*, center: Any=(0.0, 0.0, 0.0), half_size: Any=(1.0, 1.0, 1.0), normals: Any=((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))) -> Any
```


```python
center: Any
half_size: Any
normals: Any
```


Source docstring:

```text
Return a box defined by nonsingular unit normal/covector rows.

The service maps ``world`` to slab coordinates with
``(world - center) @ normals.T``. Unlike :func:`oriented_box`, the unit
rows may be non-orthogonal, allowing general parallelepipeds.
```


## `lsdtools.models.affine_slab_candidate`

Kind: function. Source: `sdk/src/lsdtools/models.py:1428`.

```python
affine_slab_candidate(*, query_id: str, slab_center: float, slab_half_size: float) -> Any
```


```python
query_id: str
slab_center: float
slab_half_size: float
```


Source docstring:

```text
Return one immutable parameter row for an affine slab family.
```


## `lsdtools.models.affine_slab_family`

Kind: function. Source: `sdk/src/lsdtools/models.py:1404`.

```python
affine_slab_family(*, normals: Any, intervals: Any, slab_center_bounds: tuple[float, float], slab_half_size_bounds: tuple[float, float]) -> Any
```


```python
intervals: Any
normals: Any
slab_center_bounds: tuple[float, float]
slab_half_size_bounds: tuple[float, float]
```


Source docstring:

```text
Return an immutable fixed-affine family with one moving slab axis.

``intervals`` contains exactly two fixed ``(lower, upper)`` intervals and
one ``None`` entry.  Candidates vary only the center and half-size of that
missing interval.  Validation, canonical fingerprints, and the envelope
SDF are owned by the shared SDF service; this helper keeps that optional
dependency lazy for package imports.
```


## `lsdtools.models.block_cell_topology`

Kind: function. Source: `sdk/src/lsdtools/models.py:3618`.

```python
block_cell_topology(source: Any, **options: Any) -> BlockCellTopologyV1
```


```python
options: Any
source: Any
```


Source docstring:

```text
Return canonical topology metadata without exposing a native service.
```


## `lsdtools.models.boolean`

Kind: function. Source: `sdk/src/lsdtools/models.py:1475`.

```python
boolean(operation: str, left: Any, right: Any, *others: Any) -> Any
```


```python
left: Any
operation: str
others: Any
right: Any
```


Source docstring:

```text
Apply ``union``, ``intersection``, or ``difference`` by name.
```


## `lsdtools.models.box`

Kind: function. Source: `sdk/src/lsdtools/models.py:1352`.

```python
box(lower: Any | None=None, upper: Any | None=None, *, center: Any | None=None, half_size: Any | None=None) -> Any
```


```python
center: Any | None
half_size: Any | None
lower: Any | None
upper: Any | None
```


Source docstring:

```text
Return an axis-aligned box from ``lower``/``upper`` or center/half-size.
```


## `lsdtools.models.build_oriented_point_sdf`

Kind: function. Source: `sdk/src/lsdtools/models.py:1147`.

```python
build_oriented_point_sdf(points: Any, outward_normals: Any, /, *, base_sdf: Any, config: OrientedPointSdfConfigV1, limits: OrientedPointSdfResourceLimitsV1, cancel: CancellationSignal | None=None) -> OrientedPointSdfBuildV1
```


```python
base_sdf: Any
cancel: CancellationSignal | None
config: OrientedPointSdfConfigV1
limits: OrientedPointSdfResourceLimitsV1
outward_normals: Any
points: Any
```


Source docstring:

```text
Prepare, qualify, compile, and encode one authoritative binary SDF.

The operation is atomic at the facade boundary: it returns only after the
source rows pass canonical preparation, all scientific qualification gates
pass, and the canonical sparse-grid artifact is encoded. A qualification,
resource, or cancellation failure publishes no result.

``points`` and ``outward_normals`` are passed to the numerical service
unchanged, so its strict FP64 shape, finiteness, uniqueness, and unit-normal
rules remain authoritative. The returned ``build.sdf`` can be handed to
``lsd_geometry.build_sdf_surface``. Persist ``build.artifact``, ``receipt``,
and ``diagnostics`` as opaque bytes; do not persist a mesh in their place.

This deterministic binary field does not estimate uncertainty, infer
geological contacts/topology, discretize lines, choose Boolean composition
between lithologies, certify continuous cut-cell volume, or prove that the
caller's chosen normal polarity matches the intended geology.
```


## `lsdtools.models.close_model`

Kind: function. Source: `sdk/src/lsdtools/models.py:3231`.

```python
close_model(backend: Any, /) -> None
```


```python
backend: Any
```


Source docstring:

```text
Release resources owned by an opened model backend.

A backend that owns compiled evidence or memory maps exposes an idempotent
``close()`` method.  Streamed block-model
backends currently own no separately closeable resource, so the absence
of ``close`` is a documented no-op.  A present non-callable ``close``
attribute is rejected instead of being silently ignored.

Cleanup failures propagate to the caller; suppressing one could leave a
backend only partially released and make later reuse unsafe.
```


## `lsdtools.models.close_region_family`

Kind: function. Source: `sdk/src/lsdtools/models.py:3208`.

```python
close_region_family(prepared: PreparedRegionFamily, /) -> None
```


```python
prepared: PreparedRegionFamily
```


Source docstring:

```text
Release a prepared handle; repeated calls after the first are no-ops.
```


## `lsdtools.models.derived_field`

Kind: function. Source: `sdk/src/lsdtools/models.py:1530`.

```python
derived_field(name: str) -> Any
```


```python
name: str
```


Source docstring:

```text
Reference an earlier named output in the same field program.
```


## `lsdtools.models.difference`

Kind: function. Source: `sdk/src/lsdtools/models.py:1469`.

```python
difference(left: Any, right: Any) -> Any
```


```python
left: Any
right: Any
```


Source docstring:

```text
Subtract ``right`` from ``left``.
```


## `lsdtools.models.evaluate_region`

Kind: function. Source: `sdk/src/lsdtools/models.py:1639`.

```python
evaluate_region(backend: Any, query: Any | None=None, /, **query_parameters: Any) -> Any
```


```python
backend: Any
query: Any | None
query_parameters: Any
```


Source docstring:

```text
Evaluate an existing query, or construct one from keyword parameters.
```


## `lsdtools.models.evaluate_region_family`

Kind: function. Source: `sdk/src/lsdtools/models.py:3043`.

```python
evaluate_region_family(prepared: PreparedRegionFamily, candidates: Iterable[Any], /, *, cancel: CancellationSignal | Callable[[], object] | None=None, max_candidates: int=65536, max_workspace_bytes: int=64 * 1024 * 1024) -> RegionalFamilyEvaluation
```


```python
cancel: CancellationSignal | Callable[[], object] | None
candidates: Iterable[Any]
max_candidates: int
max_workspace_bytes: int
prepared: PreparedRegionFamily
```


Source docstring:

```text
Evaluate a bounded candidate iterable through one prepared handle.

The complete input and output iterables are privately materialized and
validated.  A native call is made at most once and is never retried through
the ordinary regional evaluator after it starts.
```


## `lsdtools.models.evaluate_regions`

Kind: function. Source: `sdk/src/lsdtools/models.py:2209`.

```python
evaluate_regions(backend: Any, queries: Iterable[Any], /, *, cancel: CancellationSignal | Callable[[], object] | None=None, max_queries: int=65536, max_host_bytes: int | None=None, max_device_bytes: int | None=None, candidate_tile_size: int | None=None, include_evaluation_stats: bool=False, include_cache_telemetry: bool=False) -> RegionalBatchEvaluation
```


```python
backend: Any
cancel: CancellationSignal | Callable[[], object] | None
candidate_tile_size: int | None
include_cache_telemetry: bool
include_evaluation_stats: bool
max_device_bytes: int | None
max_host_bytes: int | None
max_queries: int
queries: Iterable[Any]
```


Source docstring:

```text
Evaluate an ordered, bounded regional query batch atomically.

Query references are ingested once up to ``max_queries`` with cancellation
checks and deterministic iterator cleanup before model work begins.  Two or
more queries use a backend's native page-major implementation when
advertised by :func:`evaluation_capabilities`.  Otherwise queries are
evaluated serially and held privately until every evaluation succeeds.
Empty and singleton requests never start the native batch machinery.

``max_host_bytes``, ``max_device_bytes``, and ``candidate_tile_size`` are
forwarded only when explicitly supplied *and* advertised by the opened
backend's ``native_batch_options`` capability. Unsupported explicit
controls raise before model work; they are never silently ignored. A
native invocation is never retried as scalar after it starts.

The result tuple is all-or-nothing.  Scalar fallback does not imply
transactional cache rollback: successful earlier evaluations may warm or
replace the backend's worker-local region cache before a later query raises.
``include_evaluation_stats`` retains per-query scalar service telemetry;
``include_cache_telemetry`` takes one post-request cache-residency snapshot.
A requested telemetry failure also prevents envelope publication and, like
an evaluation failure, does not roll back caches already warmed by the call.
```


## `lsdtools.models.evaluation_capabilities`

Kind: function. Source: `sdk/src/lsdtools/models.py:1908`.

```python
evaluation_capabilities(backend: Any, *, probe_accelerator: bool=False) -> ModelEvaluationCapabilities
```


```python
backend: Any
probe_accelerator: bool
```


Source docstring:

```text
Report whether one opened backend supports native regional batches.

Capability discovery is structural and side-effect free.  Native batch
execution is worthwhile for two or more queries; :func:`evaluate_regions`
deliberately retains the scalar path for a singleton.  When
``probe_accelerator=True``, an optional backend planning provider may
initialize and cache its compute runtime, but it must not scan model rows.
```


## `lsdtools.models.field_absolute`

Kind: function. Source: `sdk/src/lsdtools/models.py:1542`.

```python
field_absolute(value: Any) -> Any
```


```python
value: Any
```


Source docstring:

```text
Return the symbolic absolute value of a field expression.
```


## `lsdtools.models.field_clamp`

Kind: function. Source: `sdk/src/lsdtools/models.py:1566`.

```python
field_clamp(value: Any, lower: Any, upper: Any) -> Any
```


```python
lower: Any
upper: Any
value: Any
```


Source docstring:

```text
Clamp an expression to finite constant bounds.
```


## `lsdtools.models.field_coalesce`

Kind: function. Source: `sdk/src/lsdtools/models.py:1560`.

```python
field_coalesce(value: Any, fallback: Any) -> Any
```


```python
fallback: Any
value: Any
```


Source docstring:

```text
Replace invalid expression values with a fallback expression.
```


## `lsdtools.models.field_constant`

Kind: function. Source: `sdk/src/lsdtools/models.py:1536`.

```python
field_constant(value: Any) -> Any
```


```python
value: Any
```


Source docstring:

```text
Create a finite scalar field-expression constant.
```


## `lsdtools.models.field_maximum`

Kind: function. Source: `sdk/src/lsdtools/models.py:1554`.

```python
field_maximum(left: Any, right: Any) -> Any
```


```python
left: Any
right: Any
```


Source docstring:

```text
Return the symbolic elementwise maximum of two expressions.
```


## `lsdtools.models.field_minimum`

Kind: function. Source: `sdk/src/lsdtools/models.py:1548`.

```python
field_minimum(left: Any, right: Any) -> Any
```


```python
left: Any
right: Any
```


Source docstring:

```text
Return the symbolic elementwise minimum of two expressions.
```


## `lsdtools.models.field_program`

Kind: function. Source: `sdk/src/lsdtools/models.py:1572`.

```python
field_program(outputs: Mapping[str, Any] | Iterable[Any], *, invalid_policy: str='exclude') -> Any
```


```python
invalid_policy: str
outputs: Mapping[str, Any] | Iterable[Any]
```


Source docstring:

```text
Build the shared serializable FP64 field-program contract.

``outputs`` may be a mapping from output name to expression, an iterable
of ``(name, expression)`` pairs, or service-created ``DerivedField``
records.  The service validates cycles, depth, names, and invalid-value
policy; lsdtools only owns the lazy construction boundary.
```


## `lsdtools.models.grid_transform`

Kind: function. Source: `sdk/src/lsdtools/models.py:1490`.

```python
grid_transform(*, origin: Any=(0.0, 0.0, 0.0), spacing: Any=(1.0, 1.0, 1.0)) -> Any
```


```python
origin: Any
spacing: Any
```


Source docstring:

```text
Return the shared world placement of integer analysis-cell centers.
```


## `lsdtools.models.intersection`

Kind: function. Source: `sdk/src/lsdtools/models.py:1461`.

```python
intersection(left: Any, right: Any, *others: Any) -> Any
```


```python
left: Any
others: Any
right: Any
```


Source docstring:

```text
Return the intersection of two or more SDFs.
```


## `lsdtools.models.iter_block_cell_pages`

Kind: function. Source: `sdk/src/lsdtools/models.py:3625`.

```python
iter_block_cell_pages(source: Any, **options: Any) -> Iterator[BlockCellPageV1]
```


```python
options: Any
source: Any
```


Source docstring:

```text
Yield canonical immutable pages from OMF, Arrow, Table, or Parquet.
```


## `lsdtools.models.materialize_region_family_query`

Kind: function. Source: `sdk/src/lsdtools/models.py:3152`.

```python
materialize_region_family_query(prepared: PreparedRegionFamily, candidate: Any, /) -> Any
```


```python
candidate: Any
prepared: PreparedRegionFamily
```


Source docstring:

```text
Materialize the canonical ordinary query for finalist verification.
```


## `lsdtools.models.model_capabilities`

Kind: function. Source: `sdk/src/lsdtools/models.py:3751`.

```python
model_capabilities() -> dict[str, dict[str, Any]]
```


Source docstring:

```text
Describe installed model-query services without opening model data.

This call imports the service facades, but never constructs a model and therefore
does not load a scientific estimator engine.
```


## `lsdtools.models.offset`

Kind: function. Source: `sdk/src/lsdtools/models.py:1443`.

```python
offset(sdf: Any, distance: float) -> Any
```


```python
distance: float
sdf: Any
```


Source docstring:

```text
Offset an SDF; positive distance expands and negative distance erodes.
```


## `lsdtools.models.open_block_cells`

Kind: function. Source: `sdk/src/lsdtools/models.py:3511`.

```python
open_block_cells(source: Any, *, batch_size: int=65536, batch_readahead: int=1, fragment_readahead: int=1, use_threads: bool=True, attribute_names: Iterable[str] | None=None, x: str='x', y: str='y', z: str='z', size_columns: tuple[str, str, str] | None=('dx', 'dy', 'dz'), fixed_block_size: tuple[float, float, float] | None=None, cell_id: str='cell_id', parent_id: str='parent_id', subblock_id: str='subblock_id', overlap_policy: Literal['allow', 'error']='error', hole_policy: Literal['allow', 'error']='allow', coverage_tolerance: float=1e-12, filesystem: Any=None, partitioning: Any=None, trusted_source_fingerprint: str | None=None) -> BlockCellSourceV1
```


```python
attribute_names: Iterable[str] | None
batch_readahead: int
batch_size: int
cell_id: str
coverage_tolerance: float
filesystem: Any
fixed_block_size: tuple[float, float, float] | None
fragment_readahead: int
hole_policy: Literal['allow', 'error']
overlap_policy: Literal['allow', 'error']
parent_id: str
partitioning: Any
size_columns: tuple[str, str, str] | None
source: Any
subblock_id: str
trusted_source_fingerprint: str | None
use_threads: bool
x: str
y: str
z: str
```


Source docstring:

```text
Open OMF or canonical Arrow/Parquet cells through the public facade.

``lsdtools.Table`` is accepted directly.  Parquet inputs remain bounded
Arrow dataset scans; this operation never calls ``pyarrow.parquet.read_table``.
Returned pages own or reference read-only arrays and carry no native
adapter/model object.
```


## `lsdtools.models.open_block_model`

Kind: function. Source: `sdk/src/lsdtools/models.py:3634`.

```python
open_block_model(source: Any, *, x: str='x', y: str='y', z: str='z', size_columns: tuple[str, str, str] | None=('dx', 'dy', 'dz'), volume_column: str | None=None, fixed_block_size: tuple[float, float, float] | None=None, batch_size: int=65536, batch_readahead: int=1, fragment_readahead: int=1, use_threads: bool=True, compute_backend: str='auto', filesystem: Any=None, partitioning: Any=None, trusted_source_fingerprint: str | None=None) -> Any
```


```python
batch_readahead: int
batch_size: int
compute_backend: str
filesystem: Any
fixed_block_size: tuple[float, float, float] | None
fragment_readahead: int
partitioning: Any
size_columns: tuple[str, str, str] | None
source: Any
trusted_source_fingerprint: str | None
use_threads: bool
volume_column: str | None
x: str
y: str
z: str
```


Source docstring:

```text
Open a regional block backend from Parquet, Arrow, or ``lsdtools.Table``.

Path and Arrow Dataset sources retain the service's bounded scanning behavior.
An Arrow table (including ``lsdtools.Table.arrow``) remains in memory and is
passed directly to the service without a temporary file.
```


## `lsdtools.models.open_field_model`

Kind: function. Source: `sdk/src/lsdtools/models.py:3713`.

```python
open_field_model(coordinates: Any, values: Any, *, profile: str='askey', length_scales: Any | None=None, noise_variance: float | None=None) -> Any
```


```python
coordinates: Any
length_scales: Any | None
noise_variance: float | None
profile: str
values: Any
```


Source docstring:

```text
Fit a stationary Gaussian field to observations and return the fitted model.

The returned object answers ``predict_points``, ``predict_grid``, ``simulate_grid``
and ``sample_grid``, and every answer carries a receipt naming the method used and
the exactness of each quantity it reports. ``prepare()`` returns a model that has
factored the observed system once, which is worth doing whenever more than one
question will be asked of a fit; it also carries ``predict_supports`` — block
averages, line integrals, any weighted set of locations, conditioned at the
observations' own coordinates.

``noise_variance`` is the variance of the measurement error. Pass it when you know
it: it is only identifiable from samples close enough together to disagree, so on a
design without close pairs the fit will drive it to a bound and refuse itself rather
than invent a value.

Fitting and point prediction are dense, which bounds them in the low thousands of
observations; the grid route scales much further but is two-dimensional. See the
service's ``docs/CAPABILITIES.md`` for the full scope table.
```


## `lsdtools.models.oriented_box`

Kind: function. Source: `sdk/src/lsdtools/models.py:1369`.

```python
oriented_box(*, center: Any=(0.0, 0.0, 0.0), half_size: Any=(1.0, 1.0, 1.0), axes: Any=((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))) -> Any
```


```python
axes: Any
center: Any
half_size: Any
```


Source docstring:

```text
Return an oriented box whose right-handed world-space axes are rows.

Consequently ``(world - center) @ axes.T`` maps world coordinates to local
box coordinates.  For stopes, pass the local U/V/W unit axes in that order.
```


## `lsdtools.models.prepare_region_family`

Kind: function. Source: `sdk/src/lsdtools/models.py:2803`.

```python
prepare_region_family(backend: Any, family: Any, /, *, region_id: str, value_field: str, filters: Iterable[Any]=(), weight_field: str | None=None, requested_metrics: Iterable[str]=_DEFAULT_REGION_FAMILY_METRICS, field_program: Any | None=None, max_host_bytes: int=256 * 1024 * 1024, max_device_bytes: int=512 * 1024 * 1024, max_index_rows: int=5000000, cancel: CancellationSignal | Callable[[], object] | None=None) -> PreparedRegionFamily
```


```python
backend: Any
cancel: CancellationSignal | Callable[[], object] | None
family: Any
field_program: Any | None
filters: Iterable[Any]
max_device_bytes: int
max_host_bytes: int
max_index_rows: int
region_id: str
requested_metrics: Iterable[str]
value_field: str
weight_field: str | None
```


Source docstring:

```text
Prepare one advertised immutable geometry family atomically.

Input iterables, resource limits, capability support, and the complete
native lifecycle surface are validated before the backend hook starts.
There is deliberately no scalar fallback: callers can safely select the
ordinary regional path after :class:`UnsupportedModelRegionFamily`.
```


## `lsdtools.models.region_family_capabilities`

Kind: function. Source: `sdk/src/lsdtools/models.py:2488`.

```python
region_family_capabilities(backend: Any, /, *, probe_accelerator: bool=False) -> ModelRegionFamilyCapabilities
```


```python
backend: Any
probe_accelerator: bool
```


Source docstring:

```text
Return explicit support for immutable prepared geometry families.

Absence of the optional provider is represented by an empty, typed
capability record.  Merely defining preparation-like methods is not
sufficient: this prevents package code from starting model work against
an old or partially installed service.
```


## `lsdtools.models.regional_query`

Kind: function. Source: `sdk/src/lsdtools/models.py:1610`.

```python
regional_query(*, query_id: str, region_id: str, sdf: Any, value_field: str, filters: Iterable[Any]=(), weight_field: str | None=None, requested_metrics: Iterable[str] | None=None, field_program: Any | None=None) -> Any
```


```python
field_program: Any | None
filters: Iterable[Any]
query_id: str
region_id: str
requested_metrics: Iterable[str] | None
sdf: Any
value_field: str
weight_field: str | None
```


Source docstring:

```text
Build the query record accepted by regional model backends.
```


## `lsdtools.models.source_field`

Kind: function. Source: `sdk/src/lsdtools/models.py:1524`.

```python
source_field(name: str) -> Any
```


```python
name: str
```


Source docstring:

```text
Reference one physical/modelled scalar in a safe field expression.
```


## `lsdtools.models.source_fields`

Kind: function. Source: `sdk/src/lsdtools/models.py:1668`.

```python
source_fields(backend: Any) -> tuple[ModelFieldInfo, ...]
```


```python
backend: Any
```


Source docstring:

```text
Return schema-ordered numeric source fields without backend imports.

Geometry roles are assigned by the native backend from its configured
layout.  Consumers normally present records whose ``role`` is
``"attribute"`` as candidate value/filter fields.  Discovery is metadata
only and must not scan source rows.
```


## `lsdtools.models.source_support_region`

Kind: function. Source: `sdk/src/lsdtools/models.py:1724`.

```python
source_support_region(backend: Any, *, filters: Iterable[Any]=(), cancel: CancellationSignal | Callable[[], object] | None=None) -> ModelSpatialRegion
```


```python
backend: Any
cancel: CancellationSignal | Callable[[], object] | None
filters: Iterable[Any]
```


Source docstring:

```text
Return an exact, normalized physical-support region for one model.

Block-model backends may apply raw :class:`ValueFilter` values while
streaming cell geometry.  A backend whose support is sparse evidence rather
than occupied cells may reject non-empty filters instead, because this
capability describes where a source has support, not a value selection.
Native service records are copied into this import-light DTO so package
code never imports a product service module.
```


## `lsdtools.models.sphere`

Kind: function. Source: `sdk/src/lsdtools/models.py:1344`.

```python
sphere(*, center: Any=(0.0, 0.0, 0.0), radius: float=1.0) -> Any
```


```python
center: Any
radius: float
```


Source docstring:

```text
Return a bounded spherical SDF.
```


## `lsdtools.models.translate`

Kind: function. Source: `sdk/src/lsdtools/models.py:1449`.

```python
translate(sdf: Any, displacement: Any) -> Any
```


```python
displacement: Any
sdf: Any
```


Source docstring:

```text
Translate an SDF by a world-space displacement vector.
```


## `lsdtools.models.union`

Kind: function. Source: `sdk/src/lsdtools/models.py:1455`.

```python
union(left: Any, right: Any, *others: Any) -> Any
```


```python
left: Any
others: Any
right: Any
```


Source docstring:

```text
Return the union of two or more SDFs.
```


## `lsdtools.models.value_filter`

Kind: function. Source: `sdk/src/lsdtools/models.py:1502`.

```python
value_filter(field: str, *, minimum: float | None=None, maximum: float | None=None, include_minimum: bool=True, include_maximum: bool=True) -> Any
```


```python
field: str
include_maximum: bool
include_minimum: bool
maximum: float | None
minimum: float | None
```


Source docstring:

```text
Create a backend-neutral deterministic scalar filter.
```