parq_blockmodel.utils.demo_block_model.create_demo_blockmodel

parq_blockmodel.utils.demo_block_model.create_demo_blockmodel(shape=(3, 3, 3), block_size=(1.0, 1.0, 1.0), corner=(0.0, 0.0, 0.0), azimuth=0.0, dip=0.0, plunge=0.0, parquet_filepath=None, index_type='block_index')

Create a synthetic block model DataFrame or Parquet file.

This function generates a rectilinear block model defined in logical index space (i, j, k), together with world–space centroids and optional rotation. The function is intended for testing, exploration, and examples.

───────────────────────────────────────────────────────────────────────────── BLOCK MODEL INDEXING :rtype: DataFrame | Path

───────────────────────────────────────────────────────────────────────────── Logical indices:

• (i, j, k) represent block indices along the x, y, and z axes.

• Sorting by (i, j, k) gives the canonical logical block‑model order:

  i varies slowest j varies next k varies fastest

This ordering is purely logical and independent of how NumPy stores the data in memory.

Canonical block id:

• block_id:

  Canonical linear id obtained by flattening logical (i,j,k) coordinates in NumPy C-order. This is frame-invariant and remains stable regardless of world-space rotation.

───────────────────────────────────────────────────────────────────────────── WORLD COORDINATES ───────────────────────────────────────────────────────────────────────────── World centroids are computed using:

x = corner_x + (i + 0.5) * dx y = corner_y + (j + 0.5) * dy z = corner_z + (k + 0.5) * dz

If azimuth, dip, or plunge are non‑zero, the world positions are rotated about the origin after centroid generation.

───────────────────────────────────────────────────────────────────────────── DEPTH INFORMATION ───────────────────────────────────────────────────────────────────────────── - depth:

Computed as (maximum z centroid + dz/2) − z.

• depth_category:

  Categorical split into ‘shallow’ and ‘deep’.

───────────────────────────────────────────────────────────────────────────── DATAFRAME INDEXING OPTION ───────────────────────────────────────────────────────────────────────────── index_type:

• “block_index”: the DataFrame is indexed by (i, j, k).

• “world_centroids”: indexed by (x, y, z).

• “block_id”: indexed by canonical block_id.

───────────────────────────────────────────────────────────────────────────── ATTRIBUTES ───────────────────────────────────────────────────────────────────────────── The DataFrame is assigned lightweight geometry metadata under:

df.attrs[“geometry”] = {

“shape”: (nx, ny, nz), “block_size”: (dx, dy, dz), “corner”: (corner_x, corner_y, corner_z), “rotation”: { “azimuth”: …, “dip”: …, “plunge”: … }, “geometry_type”: “rectilinear_blockmodel”, “canonical_identity”: “block_id”, “index_type”: index_type

}

These attrs are intentionally simpler than the full “parq‑blockmodel” production schema, but pseudo‑compatible and useful for testing.

───────────────────────────────────────────────────────────────────────────── PARAMETERS ───────────────────────────────────────────────────────────────────────────── shape : tuple[int, int, int]

Logical block model size (nx, ny, nz).

block_sizetuple[float, float, float]

Block dimensions (dx, dy, dz).

cornertuple[float, float, float]

World‑space minimum corner of the unrotated model.

azimuth, dip, plungefloat

Rotation angles applied to world centroids.

parquet_filepathPath | None

If supplied, the DataFrame is written to Parquet.

index_type{“block_index”, “world_centroids”, “block_id”}

Specifies which index is assigned to the returned DataFrame.

───────────────────────────────────────────────────────────────────────────── RETURNS ───────────────────────────────────────────────────────────────────────────── DataFrame or Path

The block model DataFrame, or the Parquet path if saved.