malenov

Files (1)

• SKILL.md

SKILL.md (first lines)

# MalenoV Repository Analysis

## Purpose

MalenoV (**MA**chine **LE**ar**N**ing **O**f **V**oxels) is a Python library and runnable script for seismic facies classification using deep 3D convolutional neural networks.

Given one or more standard 3D SEGY seismic cubes and a set of user-annotated training-point files (one file per facies class), MalenoV:

1. Reads the SEGY volumes into memory as numpy arrays.
2. Extracts 3D mini-cubes ("voxelets") centred on each annotated training location.
3. Trains a 5-layer 3D CNN (Keras/TensorFlow) to distinguish the provided facies classes.
4. Classifies the entire seismic cube (or a user-defined sub-section) voxel-by-voxel.
5. Writes the resulting facies prediction back out as a SEGY cube (plus `.npy` and `.ixz` CSV files).

The tool was created by Charles Rutherford Ildstad at ConocoPhillips (2017) and supports an unlimited number of simultaneous input seismic volumes (offset stacks, 4D data, attributes, etc.), with memory and time scaling linearly with the number of channels.

---


## Boglodite MCP execution

For routine F3 facies prediction, prefer the project MCP tool `run_malenov(inline)` rather than editing the repository or predictor configuration manually. The MCP tool delegates to the validated Boglodite adapter in `sandbox/MalenoV/predict_only_facies_stable.py`. Use direct repository execution for training, research inspection, or unsupported custom workflows.

## Verified Repository Summary

| Item | Detail |
|---|---|
| Language | Python (no `.py` extension on the source file) |
| Single source file | `MalenoV Code 5 layer CNN 65x65x65 voxels` |
| License | GNU LGPL v3.0 |
| Key dependencies | `segyio`, `keras` (TF1-era API), `numpy`, `matplotlib` |
| No packaging files | No `requirements.txt`, `setup.py`, or `pyproject.toml` present |
| CNN architecture | 5 × `Conv3D` → 2 × `Dense` → softmax |
| Default voxelet size | 65 × 65 × 65 (controlled by `cube_incr=32`) |
| Training annotation format | Plain-text `.pts` files: one row per point, columns = inline, xline, time |

---

## Repository Walkthrough

The entire codebase lives in one script file. It is organised into five conceptual sections, each introduced by a block comment:

1. **Input data (SEGY) formatting and reading** — `segy_decomp`, `segy_adder`, `csv_struct`
2. **Data augmentation** — `randomRotationXY`, `randomRotationZ`, `randomStretch`, `randomFlip` (stub, not wired into training)
3. **Training** — `convert`, `ex_create`, `adaptive_lr`, `train_model`
4. **Prediction** — `cube_parse`, `makeIntermediate`, `predicting`
5. **Visualisation** — `plotNNpred`, `visualization`, `show_details`
6. **Master / main** — `master`, and a concrete run example at the bottom of the file

---

### `segy_decomp(segy_file, plot_data, read_direc, inp_res)` — SEGY → numpy

**Role:** Opens a SEGY file with `segyio`, memory-maps it, reads the full cube line by line, normalises amplitude values to the range −127…+127, and returns a `segyio.spec` object whose `.data` attribute is the 3-D numpy array `(xlines, inlines, samples)`.

**Key parameters:**
- `read_direc`: `'inline'` | `'xline'` | `'full'` — controls the fast read direction.
- `inp_res`: numpy dtype for the output array (e.g. `np.float32`, `np.int8`).

**Side effects:** Prints progress messages. Optionally plots xline 100 with matplotlib.

**Returns:** A `segyio.spec` object augmented with `.inl_start/end/step`, `.xl_start/end/step`, `.t_start/end/step`, and `.data`.

---

### `segy_adder(segy_file, inp_cube, read_direc, inp_res)` — add a channel

**Role:** Reads a second (or Nth) SEGY cube, normalises it the same way as `segy_decomp`, and returns the plain numpy array (not a spec object). Called by `master` when the input is a list of SEGY filenames.

---

### `csv_struct(inp_numpy, spec_obj, section, inp_res, save, savename)` — numpy → IXZ CSV

**Role:** Iterates through the inline × xline × time dimensions of a prediction numpy array and builds a 4-column array of `[inline, xline, time, value]` rows. Optionally saves to disk as `.ixz` (a space-delimited text file). Used by `predicting` to export results in a format suitable for loading into Petrel.

---

### Data augmentation stubs (`randomRotationXY`, `randomRotationZ`, `randomStretch`, `randomFlip`)

These four functions accept TensorFlow tensors and apply random rotations, stretches, or flips. They reference `tf` directly (not imported) and are **not connected to the training loop** — the `data_augmentation=True` branch in `train_model` uses Keras `ImageDataGenerator` instead, which is also noted as broken. These functions are present for future development.

---

### `convert(file_list, save, savename, ex_adjust)` — class address list builder

**Role:** Reads one or more `.pts` annotation files (inline, xline, time rows), appends a class-index column to each, concatenates them into a single `(N, 4)` integer array, and optionally equalises class sizes by oversampling minority classes.

**Input:** List of file paths, one per facies class.  
**Output:** A numpy array `(N, 4)` — columns: inline, xline, time, class_index.

---

### `ex_create(adr_arr, seis_arr, seis_spec, num_examp, cube_incr, ...)` — mini-cube sampler

**Role:** Randomly draws `num_examp` rows from the address array, converts each (inline, xline, time) coordinate to array indices, and slices a `(cube_size, cube_size, cube_size, num_channels)` voxelet from the seismic data. Illegal addresses (too close to cube edge) are replaced with fresh random draws up to 50 attempts.

**Output:** Tuple `(examples, labels)` where `examples` has shape `(N, cube_size, cube_size, cube_size, num_channels)` and `labels` has shape `(N,)`.

---

### `adaptive_lr(input_int)` — learning rate schedule

**Role:** Returns `0.1 ** epoch`. Passed to Keras `LearningRateScheduler` callback.

---

### `train_model(segy_obj, class_array, num_classes, cube_incr, ...)` — CNN builder and trainer

**Role:** The core training function. Builds or accepts a Keras Sequential model, then runs a double loop: an outer loop over `num_bunch` batches (each batch draws a fresh `num_examples` training voxelets) and an inner Keras `model.fit` over `num_epochs` epochs.

**CNN architecture (when building fresh):**

```
Input: (cube_size, cube_size, cube_size, num_channels)
  Conv3D(50, 5×5×5, stride 4, padding=same)  ← conv_layer1
  BatchNorm → ReLU
  Conv3D(50, 3×3×3, stride 2, padding=same)  ← conv_layer2
  Dropout(0.2) → BatchNorm → ReLU
  Conv3D(50, 3×3×3, stride 2)                ← conv_layer3

From yohanesnuwara/boglodite, MIT.

More from yohanesnuwara/boglodite