Evo blockmodels - Evo Python SDK

GitHub source

## evo.blockmodels.client.BlockModelAPIClient

### __init__

    __init__(environment: Environment, connector: APIConnector, cache: ICache | None = None) -> None

Constructor for the Block Model Service client.

Some methods need a cache to store temporary files. If you want to use these methods, you must provide a cache.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`environment` | `Environment` | The environment object. | required
`connector` | `APIConnector` | The connector object. | required
`cache` | `ICache | None` | The cache to use for storing temporary files. | `None`

### from_context `classmethod`

    from_context(context: IContext) -> BlockModelAPIClient

Create a BlockModelAPIClient from the given context.

The context must have a hub_url, org_id, and workspace_id set.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`context` | `IContext` | The context to create the client from. | required

Returns:

Type | Description
--- | ---
`BlockModelAPIClient` | A BlockModelAPIClient instance.

### get_service_health `async`

    get_service_health(check_type: HealthCheckType = HealthCheckType.FULL) -> ServiceHealth

Get the health of the service.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`check_type` | `HealthCheckType` | The type of health check to perform. | `FULL`

Returns:

Type | Description
--- | ---
`ServiceHealth` | A ServiceHealth object.

Raises:

Type | Description
--- | ---
`EvoAPIException` | If the API returns an unexpected status code.
`ClientValueError` | If the response is not a valid service health check response.

### list_block_models `async`

    list_block_models() -> list[BlockModel]

List block models in the current workspace.

Returns a list of `BlockModel`s for the workspace referenced by the client's `Environment`. Limited to the first 100 results.

### list_all_block_models `async`

    list_all_block_models(page_limit: int | None = 100) -> list[BlockModel]

Return all block models for the current workspace, following paginated responses.

This method will page through the `list_block_models` endpoint using `offset` and `limit` until all entries are retrieved. The `page_limit` is clamped to the service maximum (100).

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`page_limit` | `int | None` | Maximum items to request per page (1..100). Defaults to 100. | `100`

Returns:

Type | Description
--- | ---
`list[BlockModel]` | A list of `BlockModel` dataclasses for the workspace.

### list_versions `async`

    list_versions(bm_id: UUID) -> list[Version]

List versions of a block model.

Returns a list of `Version`s for the block model referenced by `bm_id`, limited to the first 100 results (or the service maximum).

Versions are ordered from newest to oldest.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`bm_id` | `UUID` | The ID of the block model. | required

Returns:

Type | Description
--- | ---
`list[Version]` | A list of `Version` dataclasses for the block model, ordered newest to oldest.

### list_all_versions `async`

    list_all_versions(bm_id: UUID, page_limit: int | None = 100) -> list[Version]

Return all versions of a block model, following paginated responses.

This method will page through the `list_block_model_versions` endpoint using `offset` and `limit` until all entries are retrieved. The `page_limit` is clamped to the service maximum (100).

Versions are ordered from newest to oldest.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`bm_id` | `UUID` | The ID of the block model. | required
`page_limit` | `int | None` | Maximum items to request per page (1..100). Defaults to 100. | `100`

Returns:

Type | Description
--- | ---
`list[Version]` | A list of `Version` dataclasses for the block model, ordered newest to oldest.

### create_block_model `async`

    create_block_model(
        name: str,
        grid_definition: BaseGridDefinition,
        description: str | None = None,
        object_path: str | None = None,
        coordinate_reference_system: str | None = None,
        size_unit_id: str | None = None,
        initial_data: Table | None = None,
        units: dict[str, str] | None = None,
    ) -> tuple[BlockModel, Version]

Create a block model.

Optionally, takes initial data to populate the block model with. Units for the columns within the initial data can be provided in the `units` dictionary. This requires the `pyarrow` package to be installed, and the 'cache' parameter to be set in the constructor.

If `initial_data` is provided, this method will wait for the initial data to be successfully uploaded and processed before returning. This then returns both the block model and the version created from the initial data update.

Otherwise, if `initial_data` is not provided, this waits for the block model creation job to complete before returning. This then returns both the block model and the initial block model version.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`name` | `str` | Name of the block model. This may not contain `/` nor `\`. | required
`grid_definition` | `BaseGridDefinition` | Definition of the block model grid. | required
`description` | `str | None` | Description of the block model. | `None`
`object_path` | `str | None` | Path of the folder in Geoscience Object Service to create the reference object in. | `None`
`coordinate_reference_system` | `str | None` | Coordinate reference system used in the block model. | `None`
`size_unit_id` | `str | None` | Unit ID denoting the length unit used for the block model's blocks. | `None`
`initial_data` | `Table | None` | The initial data to populate the block model with. | `None`
`units` | `dict[str, str] | None` | A dictionary mapping column names within `initial_data` to units. | `None`

Returns:

Type | Description
--- | ---
`tuple[BlockModel, Version]` | A tuple containing the created block model and the version of the block model.

### add_new_subblocked_columns `async`

    add_new_subblocked_columns(bm_id: UUID, data: Table, units: dict[str, str] | None = None)

Add new columns to an existing sub-blocked block model. This will not change the sub-blocking structure, thus the provided data must match existing sub-blocks in the model.

Units for the columns can be provided in the `units` dictionary.

This method requires the `pyarrow` package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`bm_id` | `UUID` | The ID of the block model to add columns to. | required
`data` | `Table` | The data containing the new columns to add. | required
`units` | `dict[str, str] | None` | A dictionary mapping column names within `data` to units. | `None`

Returns:

Type | Description
--- | ---
| The new version of the block model with the added columns.

Raises:

Type | Description
--- | ---
`CacheNotConfiguredException` | If the cache is not configured.

### add_new_columns `async`

    add_new_columns(bm_id: UUID, data: Table, units: dict[str, str] | None = None)

Add new columns to an existing regular block model.

Units for the columns can be provided in the `units` dictionary.

This method requires the `pyarrow` package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`bm_id` | `UUID` | The ID of the block model to add columns to. | required
`data` | `Table` | The data containing the new columns to add. | required
`units` | `dict[str, str] | None` | A dictionary mapping column names within `data` to units. | `None`

Returns:

Type | Description
--- | ---
| The new version of the block model with the added columns.

Raises:

Type | Description
--- | ---
`CacheNotConfiguredException` | If the cache is not configured.

### update_block_model_columns `async`

    update_block_model_columns(
        bm_id: UUID,
        data: Table,
        new_columns: list[str],
        update_columns: set[str] | None = None,
        delete_columns: set[str] | None = None,
        units: dict[str, str] | None = None,
    ) -> Version

Add, update, or delete regular block model columns.

Units for the columns can be provided in the `units` dictionary.

This method requires the `pyarrow` package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`bm_id` | `UUID` | The ID of the block model to add columns to. | required
`data` | `Table` | The data containing the new columns to add. | required
`new_columns` | `list[str]` | A list of new column names to add to the block model. | required
`update_columns` | `set[str] | None` | A set of column names to update in the block model. | `None`
`delete_columns` | `set[str] | None` | A set of column names to delete from the block model. | `None`
`units` | `dict[str, str] | None` | A dictionary mapping column names within `data` to units. | `None`

Returns:

Type | Description
--- | ---
`Version` | The new version of the block model with the added columns.

Raises:

Type | Description
--- | ---
`CacheNotConfiguredException` | If the cache is not configured.

### update_subblocked_columns `async`

    update_subblocked_columns(
        bm_id: UUID,
        data: Table,
        new_columns: list[str],
        update_columns: set[str] | None = None,
        delete_columns: set[str] | None = None,
        units: dict[str, str] | None = None,
        geometry_change: bool = False,
    ) -> Version

Add, update, or delete sub-blocked block model columns.

Whether the sub-blocking structure changes can be specified with the `geometry_change` parameter.

If `True`, the geometry of the sub-blocked model changes, but all existing sub-blocks columns must either be updated or deleted. If `False`, the geometry of the sub-blocked model does not change, but the provided data must match existing sub-blocks in the model.

Units for the columns can be provided in the `units` dictionary.

This method requires the `pyarrow` package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`bm_id` | `UUID` | The ID of the block model to add columns to. | required
`data` | `Table` | The data containing the new columns to add. | required
`new_columns` | `list[str]` | A list of new column names to add to the block model. | required
`update_columns` | `set[str] | None` | A set of column names to update in the block model. | `None`
`delete_columns` | `set[str] | None` | A set of column names to delete from the block model. | `None`
`units` | `dict[str, str] | None` | A dictionary mapping column names within `data` to units. | `None`
`geometry_change` | `bool` | Whether the geometry of the sub-blocked model changes. | `False`

### update_column_metadata `async`

    update_column_metadata(bm_id: UUID, column_updates: dict[str, str | None], comment: str | None = None) -> Version

Update metadata (e.g., units) for existing block model columns.

This method updates column properties without requiring data upload or cache configuration.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`bm_id` | `UUID` | The ID of the block model to update. | required
`column_updates` | `dict[str, str | None]` | A dictionary mapping column titles to their new unit IDs. Set the unit ID to None to remove the unit. Example: {"Cu": "%[mass]", "Au": None} | required
`comment` | `str | None` | An optional comment describing the metadata changes. This is max 250 characters. | `None`

Returns:

Type | Description
--- | ---
`Version` | The new version of the block model with updated metadata.

### rename_block_model_columns `async`

    rename_block_model_columns(bm_id: UUID, column_renames: dict[str, str], comment: str | None = None) -> Version

Rename existing block model columns.

This method renames columns without requiring data upload or cache configuration.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`bm_id` | `UUID` | The ID of the block model to update. | required
`column_renames` | `dict[str, str]` | A dictionary mapping current column titles to their new titles. Example: {"Cu": "Copper", "Au": "Gold"} | required
`comment` | `str | None` | An optional comment describing the rename operation. This is max 250 characters. | `None`

Returns:

Type | Description
--- | ---
`Version` | The new version of the block model with renamed columns.

### delete_block_model_columns `async`

    delete_block_model_columns(bm_id: UUID, column_titles: list[str], comment: str | None = None) -> Version

Delete existing columns from a block model.

This method deletes columns without requiring data upload or cache configuration.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`bm_id` | `UUID` | The ID of the block model to update. | required
`column_titles` | `list[str]` | The titles of the columns to delete. | required
`comment` | `str | None` | An optional comment describing the rename operation. This is max 250 characters. | `None`

Returns:

Type | Description
--- | ---
`Version` | The new version of the block model with renamed columns.

### query_block_model_as_table `async`

    query_block_model_as_table(
        bm_id: UUID,
        columns: list[str | UUID],
        bbox: BBox | BBoxXYZ | None = None,
        version_uuid: UUID | None = None,
        geometry_columns: GeometryColumns = GeometryColumns.coordinates,
        column_headers: ColumnHeaderType = ColumnHeaderType.id,
        exclude_null_rows: bool = True,
    ) -> Table

Query a block model and return the result as a PyArrow Table.

This requires the `pyarrow` package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`bm_id` | `UUID` | The ID of the block model to query. | required
`columns` | `list[str | UUID]` | The columns to query, can either be the title or the ID of the column. | required
`bbox` | `BBox | BBoxXYZ | None` | The bounding box to query, if None (the default) the entire block model is queried. | `None`
`version_uuid` | `UUID | None` | The version UUID to query, if None (the default) the latest version is queried. | `None`
`geometry_columns` | `GeometryColumns` | Whether rows in the returned table should include coordinates, or block indices of the block, that the row belongs to. | `coordinates`
`column_headers` | `ColumnHeaderType` | Whether the names of the columns in the returned column should be the title or the ID of the block model column. | `id`
`exclude_null_rows` | `bool` | Whether to exclude rows where all values are null within the queried columns. | `True`

Returns:

Type | Description
--- | ---
`Table` | The result as a PyArrow Table.

Raises:

Type | Description
--- | ---
`JobFailedException` | If the job failed.

#### Keyboard Shortcuts

Keys | Action
--- | ---
`?` | Open this help
`n` | Next page
`p` | Previous page
`s` | Search