### Use a Gempy Model as a Starting Template

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/examples-API.md

Loads a complex 'COMBINATION' example model, prints its structural groups and elements, and saves it to a zip file. It then demonstrates loading this saved template, renaming it, and computing it. This workflow is ideal for creating reusable model templates.

```python
import gempy as gp
from gempy.core.data.enumerators import ExampleModel

# Start with complex example
base_model = gp.generate_example_model(ExampleModel.COMBINATION)

# Extract and understand structure
print(f"Starting model: {base_model.meta.name}")
print(f"Groups:")
for group in base_model.structural_frame.structural_groups:
    print(f"  {group.name}:")
    for element in group.elements:
        print(f"    - {element.name}")

# Save for later use
gp.save_model(base_model, './my_starting_template.zip')

# Load template and modify
template = gp.load_model('./my_starting_template.zip')
template.meta.name = 'MyModifiedModel'

# Continue with modifications...
gp.compute_model(template)
```

--------------------------------

### Install GemPy Manually from Source

Source: https://github.com/gempy-project/gempy/blob/main/docs/source/installation.md

After cloning the repository, navigate to the root directory and install GemPy using pip in editable mode.

```bash
$ pip install -e .
```

--------------------------------

### Install GemPy Viewer

Source: https://github.com/gempy-project/gempy/blob/main/docs/source/installation.md

Install the gempy-viewer package for 2-D and 3-D visualization. Note that pyvista needs to be installed separately.

```bash
$ pip install gempy-viewer
```

--------------------------------

### Install Core GemPy Package

Source: https://github.com/gempy-project/gempy/blob/main/docs/source/installation.md

Use this command to install the basic GemPy package with minimal dependencies.

```bash
$ pip install gempy
```

--------------------------------

### generate_example_model

Source: https://github.com/gempy-project/gempy/blob/main/docs/source/api_reference.md

Generates an example model.

```APIDOC
## generate_example_model(example_model[, ...])

### Description
Generates an example model.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
None

### Endpoint
None

### Request Example
None

### Response
None
```

--------------------------------

### create_geomodel - Minimal Setup with Default Structure

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/initialization-API.md

Initializes a GemPy model with a minimal setup using default structural parameters. This is a common starting point for new projects.

```APIDOC
## create_geomodel(project_name, extent, resolution)

### Description
Initializes a GemPy geological model with a minimal setup and default structural parameters.

### Usage
```python
import gempy as gp

model = gp.create_geomodel(
    project_name='SimpleModel',
    extent=[0, 1000, 0, 1000, -500, 0],
    resolution=[30, 30, 30]
)

# Now add data to the model
gp.add_surface_points(
    geo_model=model,
    x=[100, 500, 900],
    y=[100, 500, 900],
    z=[-100, -250, -400],
    elements_names=['Layer1', 'Layer1', 'Layer1']
)
```
```

--------------------------------

### Create GeoModelMeta Instance

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/types.md

Example of instantiating the GeoModelMeta dataclass with model details.

```python
meta = GeoModelMeta(
    name='MyModel',
    creation_date='2024-01-15',
    last_modification_date='2024-01-16',
    owner='GeologistName'
)
```

--------------------------------

### Initialize Empty Grid

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/Grid.md

Creates a new, empty Grid instance. Useful for starting with a default configuration.

```python
grid = Grid()
```

--------------------------------

### Generate GemPy Example Model

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/README.md

Creates a model instance using a predefined example template, such as 'ONE_FAULT'. This is useful for quick testing or as a starting point for customization.

```python
from gempy.core.data.enumerators import ExampleModel

model = gp.generate_example_model(ExampleModel.ONE_FAULT)
# Customize and extend...
```

--------------------------------

### Install GemPy with Development Dependencies

Source: https://github.com/gempy-project/gempy/blob/main/docs/source/installation.md

Install GemPy with development dependencies, including testing tools, for development purposes.

```bash
$ pip install gempy[dev]
```

--------------------------------

### Generate Example Models

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/examples-API.md

Generates pre-configured geological models. You can choose to compute the model immediately or modify it before computation.

```python
import gempy as gp
from gempy.core.data.enumerators import ExampleModel

# Generate simple example
model = gp.generate_example_model(ExampleModel.HORIZONTAL_STRAT)

# Generate without computation
model = gp.generate_example_model(
    ExampleModel.ONE_FAULT,
    compute_model=False
)
# Can modify before computing
gp.compute_model(model)
```

--------------------------------

### Gempy Testing Workflow with Refinements

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/examples-API.md

Uses a simple horizontal stratigraphy example model to test computations at different refinement levels (2, 3, 4). It configures the model's refinement option, computes the model, and stores the resulting octree shape. This demonstrates a basic testing setup for performance or accuracy checks.

```python
import gempy as gp
from gempy.core.data.enumerators import ExampleModel
import numpy as np

# Use simple example for testing
test_model = gp.generate_example_model(ExampleModel.HORIZONTAL_STRAT)

# Run test computations
results = []
for refinement in [2, 3, 4]:
    test_model.interpolation_options.refinement = refinement
    sol = gp.compute_model(test_model)
    results.append({
        'refinement': refinement,
        'shape': sol.raw_arrays.octree.shape if hasattr(sol.raw_arrays, 'octree') else None
    })
    print(f"Refinement {refinement}: OK")

print(f"\nTesting complete - {len(results)} configurations tested")
```

--------------------------------

### Install GemPy with Optional Dependencies

Source: https://github.com/gempy-project/gempy/blob/main/docs/source/installation.md

Install GemPy with optional dependencies to enable features like data download support.

```bash
$ pip install gempy[opt]
```

--------------------------------

### Minimal GemPy Model Setup

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/initialization-API.md

Initializes a GemPy model with default settings and adds surface points for a simple geological layer.

```python
import gempy as gp

model = gp.create_geomodel(
    project_name='SimpleModel',
    extent=[0, 1000, 0, 1000, -500, 0],
    resolution=[30, 30, 30]
)

# Now add data to the model
gp.add_surface_points(
    geo_model=model,
    x=[100, 500, 900],
    y=[100, 500, 900],
    z=[-100, -250, -400],
    elements_names=['Layer1', 'Layer1', 'Layer1']
)
```

--------------------------------

### Inspect a Gempy Example Model

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/examples-API.md

Loads a predefined horizontal stratigraphy example model and prints its metadata, grid extent, resolution, and structural element details. Useful for understanding the structure of an existing model.

```python
import gempy as gp
from gempy.core.data.enumerators import ExampleModel

# Load example
model = gp.generate_example_model(ExampleModel.HORIZONTAL_STRAT)

# Examine structure
print(f"Name: {model.meta.name}")
print(f"Owner: {model.meta.owner}")
print(f"Extent: {model.grid.regular_grid.extent}")
print(f"Resolution: {model.grid.regular_grid.resolution}")

# Examine elements
for element in model.structural_frame.structural_elements:
    print(f"\n{element.name}:")
    print(f"  Points: {element.number_of_points}")
    print(f"  Orientations: {element.number_of_orientations}")
    print(f"  Color: {element.color}")

# Examine solutions
if model.solutions:
    print(f"\nSolutions available: {model.solutions.raw_arrays.octree.shape}")
```

--------------------------------

### Example Function

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/INDEX.md

Function for generating an example geological model.

```APIDOC
## Example Function

### Description
Function for generating an example geological model.

### Function
- `generate_example_model()`: Generates a sample GeoModel for demonstration purposes.
```

--------------------------------

### Compare Different Gempy Example Models

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/examples-API.md

Generates and iterates through several predefined example models (horizontal stratigraphy, one fault, anticline, graben). For each, it prints summary statistics like extent, number of elements, and total points. This is useful for understanding the variety of models available.

```python
import gempy as gp
from gempy.core.data.enumerators import ExampleModel
import matplotlib.pyplot as plt

# Generate multiple examples
examples = [
    ExampleModel.HORIZONTAL_STRAT,
    ExampleModel.ONE_FAULT,
    ExampleModel.ANTICLINE,
    ExampleModel.GRABEN
]

for example_type in examples:
    model = gp.generate_example_model(example_type)
    
    print(f"\n{example_type.name}:")
    print(f"  Extent: {model.grid.regular_grid.extent}")
    print(f"  Elements: {len(model.structural_frame.structural_elements)}")
    print(f"  Total Points: {len(model.surface_points_copy)}")
    
    if model.solutions:
        block = model.solutions.raw_arrays.octree
        print(f"  Block Model: {block.shape}")
```

--------------------------------

### Create a new GeoModel instance

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/GeoModel.md

This example demonstrates how to create a new GeoModel instance using the `create_geomodel` function. It initializes the project name, spatial extent, resolution, and a default structural frame.

```python
import gempy as gp

geo_model = gp.create_geomodel(
    project_name='MyGeoModel',
    extent=[0, 1000, 0, 1000, -1000, 0],
    resolution=[50, 50, 50],
    structural_frame=gp.data.StructuralFrame.initialize_default_structure()
)
```

--------------------------------

### Modify and Recompute an Example Model

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/examples-API.md

Loads a single fault example model without computing it initially. It then adds surface points and orientations, and finally computes the modified model. Use this to see how to alter a model's geometry and re-run computations.

```python
import gempy as gp
from gempy.core.data.enumerators import ExampleModel
import numpy as np

# Load example
model = gp.generate_example_model(
    ExampleModel.ONE_FAULT,
    compute_model=False  # Don't compute yet
)

# Add more surface points
gp.add_surface_points(
    geo_model=model,
    x=[400, 600],
    y=[400, 600],
    z=[-200, -400],
    elements_names=['Layer1', 'Layer1']
)

# Add orientations
gp.add_orientations(
    geo_model=model,
    x=[500],
    y=[500],
    z=[-300],
    elements_names=['Layer1'],
    pole_vector=[[0, 0, 1]]
)

# Compute modified model
solutions = gp.compute_model(model)
print(f"Solutions computed: {solutions.raw_arrays.octree is not None}")
```

--------------------------------

### Python Function Documentation Example

Source: https://github.com/gempy-project/gempy/blob/main/CONTRIBUTING.md

Example of a well-documented Python function following PEP 257 and Google Style Guidelines. Use this format for all modules, functions, classes, and methods.

```python
def func(arg1: int, arg2: float) -> int:
    """A concise one line summary of the function. 
    
    Additional information and description of the function, if necessary. This
    can be as long and verbose as you think is necessary for other users and 
    developers to understand your functionality. 
    
    Args:
        arg1 (int): Description of the first argument.
        arg2 (float): Description of the second argument. Please use hanging 
            indentation for multi-line argument descriptions.
    
    Returns:
        (int) Description of the return value(s)
    """
    return 42
```

--------------------------------

### Install GemPy with Base Dependencies

Source: https://github.com/gempy-project/gempy/blob/main/README.md

Install the latest release version of GemPy using pip. This command includes the base dependencies required for core functionality.

```bash
$ pip install gempy[base]
```

--------------------------------

### Define Example Geological Models

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/types.md

Use ExampleModel to select predefined geological models for testing or tutorials. Import it from gempy.core.data.enumerators.

```python
class ExampleModel(Enum):
    TWO_AND_A_HALF_D = auto()
    HORIZONTAL_STRAT = auto()
    ANTICLINE = auto()
    ONE_FAULT = auto()
    COMBINATION = auto()
    ONE_FAULT_GRAVITY = auto()
    GRABEN = auto()
    GREENSTONE = auto()
    FAULT_RELATION = auto()
```

```python
from gempy.core.data.enumerators import ExampleModel
model = gp.generate_example_model(ExampleModel.ONE_FAULT)
```

--------------------------------

### Create Geomodel with Dense Grid Options

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/configuration.md

Example of creating a geomodel using dense grid interpolation options.

```python
import gempy as gp

# Dense grid options
model = gp.create_geomodel(
    project_name='Dense',
    extent=[0, 1000, 0, 1000, -1000, 0],
    resolution=[50, 50, 50],
    intpolation_options_tye=gp.core.data.options.InterpolationOptionsType.DENSE_GRID
)
```

--------------------------------

### Create Geomodel with Octree Options

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/configuration.md

Example of creating a geomodel using octree interpolation options with a specified refinement level.

```python
import gempy as gp

# Octree options with refinement
model = gp.create_geomodel(
    project_name='Octree',
    extent=[0, 1000, 0, 1000, -1000, 0],
    refinement=4,
    intpolation_options_tye=gp.core.data.options.InterpolationOptionsType.OCTREE
)
```

--------------------------------

### generate_example_model()

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/examples-API.md

Generates a pre-configured example geological model. This function takes an `ExampleModel` enum to specify which model to generate and an optional boolean to control whether the model is computed upon creation.

```APIDOC
## generate_example_model()

### Description
Generates a pre-configured example geological model. This function allows users to select from various predefined geological structures for testing, learning, or demonstration purposes.

### Method
```python
def generate_example_model(
    example_model: ExampleModel,
    compute_model: bool = True
) -> GeoModel
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **example_model** (ExampleModel) - Required - Enum specifying which example to generate.
- **compute_model** (bool) - Optional - Whether to compute the model before returning. Defaults to True.

### Returns
- **GeoModel** - Configured example geological model.

### Example
```python
import gempy as gp
from gempy.core.data.enumerators import ExampleModel

# Generate simple example
model = gp.generate_example_model(ExampleModel.HORIZONTAL_STRAT)

# Generate without computation
model = gp.generate_example_model(
    ExampleModel.ONE_FAULT,
    compute_model=False
)
# Can modify before computing
gp.compute_model(model)
```

### Available Examples

#### ExampleModel.HORIZONTAL_STRAT
Simple horizontal stratigraphic layers (flat-lying strata).

**Characteristics:**
- 3 horizontal layers
- Extent: 791m × 400m × 582m depth
- Resolution: 50×50×50 cells
- No faults or folding
- Good for beginners

**Usage:**
```python
model = gp.generate_example_model(ExampleModel.HORIZONTAL_STRAT)
print(f"Model: {model.meta.name}")
print(f"Elements: {model.structural_frame.number_of_elements}")
```

#### ExampleModel.ANTICLINE
Folded strata forming an anticline (upward-arching fold).

**Characteristics:**
- Multiple layers with gentle folding
- Depicts anticline structure
- Good for understanding fold geometry
- Suitable for interpolation learning

**Usage:**
```python
model = gp.generate_example_model(ExampleModel.ANTICLINE)
# Use for studying fold behavior
```

#### ExampleModel.ONE_FAULT
Model with single planar fault cutting through stratigraphy.

**Characteristics:**
- 2-3 stratigraphic layers
- One dipping fault
- Demonstrates fault displacement
- Good for fault mechanics learning

**Usage:**
```python
model = gp.generate_example_model(ExampleModel.ONE_FAULT)
solutions = model.solutions
block_model = solutions.raw_arrays.octree
```

#### ExampleModel.TWO_AND_A_HALF_D
2.5D model (oriented along X-Y plane, limited Z extent).

**Characteristics:**
- Extended in two dimensions
- Minimal third dimension
- Good for profile visualization
- Useful for 2D-like geological problems

**Usage:**
```python
model = gp.generate_example_model(ExampleModel.TWO_AND_A_HALF_D)
# Better for cross-section analysis
```

#### ExampleModel.COMBINATION
Complex model combining multiple structural elements.

**Characteristics:**
- Multiple layers
- One or more faults
- Complex geometry
- Demonstrates combined effects

**Usage:**
```python
model = gp.generate_example_model(ExampleModel.COMBINATION)
# Advanced learning about complex geometries
```

#### ExampleModel.ONE_FAULT_GRAVITY
Fault model with gravity constraints/properties.

**Characteristics:**
- Single fault cutting through strata
- Includes geophysics configuration
- Good for gravity-geologic modeling
- Demonstrates constraint integration

**Usage:**
```python
model = gp.generate_example_model(ExampleModel.ONE_FAULT_GRAVITY)
# Study gravity inversion coupling
```

#### ExampleModel.GRABEN
Graben structure (down-faulted block between two boundary faults).

**Characteristics:**
- Two parallel faults with opposing dips
- Down-dropped central block
- Classic extensional structure
- Good for understanding fault interactions

**Usage:**
```python
model = gp.generate_example_model(ExampleModel.GRABEN)
# Study extension and fault kinematics
```

#### ExampleModel.GREENSTONE
Complex greenstone belt model (real-world inspired).

**Characteristics:**
- Multiple structural elements
- Complex fold/fault patterns
- Real-world inspired geometry
- Advanced training model

**Usage:**
```python
model = gp.generate_example_model(ExampleModel.GREENSTONE)
# Advanced applications
```

#### ExampleModel.FAULT_RELATION
Model demonstrating fault-fault and fault-strata relationships.

**Characteristics:**
- Multiple intersecting faults
- Complex fault relations
- Shows fault chronology
- Good for fault network modeling

**Usage:**
```python
model = gp.generate_example_model(ExampleModel.FAULT_RELATION)
# Study fault interaction patterns
```
```

--------------------------------

### Complete GemPy Model Configuration and Computation

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating the creation of a GemPy model with custom extent, resolution, topography, surface points, orientations, anisotropy, and computation engine configuration.

```python
import gempy as gp
from gempy.core.data.gempy_engine_config import GemPyEngineConfig
from gempy.core.data.options import InterpolationOptionsType
from gempy_engine.config import AvailableBackends
from gempy_engine.core.data.transforms import GlobalAnisotropy

# Create structural frame
frame = gp.data.StructuralFrame.initialize_default_structure()

# Create model with full configuration
model = gp.create_geomodel(
    project_name='CompleteExample',
    extent=[0, 2000, 0, 2000, -1500, 0],
    resolution=[60, 60, 50],
    structural_frame=frame,
    intpolation_options_tye=InterpolationOptionsType.DENSE_GRID
)

# Configure topography
gp.set_topography_from_random(
    grid=model.grid,
    fractal_dimension=2.0,
    topography_resolution=[100, 100]
)

# Add data with custom nuggets
gp.add_surface_points(
    geo_model=model,
    x=[500, 1000, 1500],
    y=[1000, 1000, 1000],
    z=[-300, -600, -900],
    elements_names=['Layer1', 'Layer1', 'Layer1'],
    nugget=[0.00001, 0.00002, 0.00002]
)

gp.add_orientations(
    geo_model=model,
    x=[1000],
    y=[1000],
    z=[-600],
    elements_names=['Layer1'],
    nugget=[0.01]
)

# Apply anisotropy
model.update_transform(GlobalAnisotropy.Z)

# Configure computation engine
engine_config = GemPyEngineConfig(
    use_gpu=False,
    backend=AvailableBackends.numpy,
    dtype='float64',
    compute_grads=False
)

# Compute model
solutions = gp.compute_model(model, engine_config=engine_config)
```

--------------------------------

### Initialize Dense Grid with Real Topography

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/grid-API.md

Creates a dense grid and incorporates real topographical data from a GeoTIFF file. This setup is useful for terrain-inclusive geological models. Ensure the filepath is correct.

```python
# Create dense grid
grid = gp.Grid.init_dense_grid(
    extent=[0, 1000, 0, 1000, -1000, 100],
    resolution=[50, 50, 50]
)

# Load real topography
gp.set_topography_from_file(
    grid=grid,
    filepath='/data/elevation_model.tif'
)

# Compute model respecting topography
model = gp.GeoModel(
    meta=gp.data.GeoModelMeta(
        name='TerrainModel',
        creation_date='2024-01-01',
        last_modification_date=None,
        owner=None
    ),
    structural_frame=gp.data.StructuralFrame.initialize_default_structure(),
    grid=grid
)
```

--------------------------------

### Minimal Gempy Model Creation

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/README.md

Create a basic geological model, add surface points and orientation data, compute the model, and access the results. This example demonstrates the core workflow of Gempy.

```python
import gempy as gp

# Create model
model = gp.create_geomodel(
    project_name='MyModel',
    extent=[0, 1000, 0, 1000, -1000, 0],
    resolution=[50, 50, 50]
)

# Add data
gp.add_surface_points(
    geo_model=model,
    x=[100, 500, 900],
    y=[500, 500, 500],
    z=[-200, -400, -600],
    elements_names=['Layer1', 'Layer1', 'Layer1']
)

gp.add_orientations(
    geo_model=model,
    x=[500],
    y=[500],
    z=[-400],
    elements_names=['Layer1'],
    pole_vector=[[0, 0, 1]]
)

# Compute
solutions = gp.compute_model(model)

# Access results
block_model = solutions.raw_arrays.octree
```

--------------------------------

### GemPy Model Refinement Loop Example

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/compute-API.md

Illustrates a workflow for refining a geological model. It involves creating an initial model, computing a solution, adding more data points, and recomputing for a more detailed result.

```python
import gempy as gp

# Create initial model
model = gp.create_geomodel(
    project_name='RefinedModel',
    extent=[0, 1000, 0, 1000, -1000, 0],
    refinement=2
)

# Add initial data
gp.add_surface_points(
    geo_model=model,
    x=[500],
    y=[500],
    z=[-500],
    elements_names=['Layer1']
)

# Compute initial solution
solutions = gp.compute_model(model)

# Refine: add more data points
gp.add_surface_points(
    geo_model=model,
    x=[250, 750],
    y=[250, 750],
    z=[-300, -700],
    elements_names=['Layer1', 'Layer1']
)

# Recompute with refined data
solutions_refined = gp.compute_model(model)
```

--------------------------------

### create_geomodel - Setup with Complex Geometry (Faults + Strata)

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/initialization-API.md

Initializes a GemPy model designed for complex geological scenarios, including both stratigraphic layers and fault structures.

```APIDOC
## create_geomodel(project_name, extent, resolution, structural_frame)

### Description
Initializes a GemPy model for complex geological scenarios involving faults and strata.

### Usage
```python
model = gp.create_geomodel(
    project_name='ComplexModel',
    extent=[0, 10000, 0, 10000, -5000, 0],
    resolution=[100, 100, 100],
    structural_frame=gp.data.StructuralFrame.initialize_default_structure()
)

# Add stratigraphic layers
gp.add_surface_points(
    geo_model=model,
    x=[1000, 5000, 9000],
    y=[5000, 5000, 5000],
    z=[-500, -1500, -2500],
    elements_names=['Sandstone', 'Sandstone', 'Sandstone']
)

# Add fault
fault_element = gp.data.StructuralElement(
    name='MainFault',
    surface_points=gp.data.SurfacePointsTable.from_arrays(
        x=[5000, 5000],
        y=[2000, 8000],
        z=[-500, -3000],
        names='MainFault'
    ),
    orientations=gp.data.OrientationsTable.initialize_empty(),
    color='#527682'
)

fault_group = gp.data.StructuralGroup(
    name='faults',
    elements=[fault_element],
    structural_relation=gp_engine.core.data.stack_relation_type.StackRelationType.FAULT
)

model.structural_frame.append_group(fault_group)

# Set fault relations
gp.set_is_fault(
    frame=model,
    fault_groups=['MainFault']
)
```
```

--------------------------------

### create_geomodel

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/initialization-API.md

Creates a fully initialized geological model with specified grid, interpolation, and structural configuration. It handles the setup of grids, interpolation options, and structural frames.

```APIDOC
## create_geomodel()

### Description
Creates a fully initialized geological model with specified grid, interpolation, and structural configuration.

### Method
create_geomodel

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **project_name** (str) - Optional - Name of the geological model project
- **extent** (list, ndarray) - Optional - Spatial extent [min_x, max_x, min_y, max_y, min_z, max_z]
- **resolution** (list, ndarray) - Optional - Dense grid resolution [x_res, y_res, z_res]; if None, octree used
- **refinement** (int) - Optional - Octree refinement level (ignored if resolution provided)
- **structural_frame** (StructuralFrame) - Optional - Pre-configured structural frame; required if importer_helper is None
- **importer_helper** (ImporterHelper) - Optional - Helper for initializing structural frame; required if structural_frame is None
- **intpolation_options_tye** (InterpolationOptionsType) - Optional - Interpolation type (DENSE_GRID or OCTREE)

### Request Example
```python
import gempy as gp
from gempy.core.data.options import InterpolationOptionsType

# Create model with octree grid
model1 = gp.create_geomodel(
    project_name='MyProject',
    extent=[0, 1000, 0, 1000, -1000, 0],
    refinement=3,
    structural_frame=gp.data.StructuralFrame.initialize_default_structure()
)

# Create model with dense grid
model2 = gp.create_geomodel(
    project_name='DenseProject',
    extent=[0, 1000, 0, 1000, -1000, 0],
    resolution=[50, 50, 50],
    intpolation_options_tye=InterpolationOptionsType.DENSE_GRID,
    structural_frame=gp.data.StructuralFrame.initialize_default_structure()
)
```

### Response
#### Success Response (GeoModel)
- Initialized geological model

#### Response Example
None provided in source.

### Errors
- `ValueError`: If neither structural_frame nor importer_helper provided
- `ValueError`: If interpolation options type unrecognized
```

--------------------------------

### GemPy Model Setup with Complex Geometry (Faults and Strata)

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/initialization-API.md

Creates a GemPy model with both stratigraphic layers and a fault, configuring their relationships within the structural frame.

```python
model = gp.create_geomodel(
    project_name='ComplexModel',
    extent=[0, 10000, 0, 10000, -5000, 0],
    resolution=[100, 100, 100],
    structural_frame=gp.data.StructuralFrame.initialize_default_structure()
)

# Add stratigraphic layers
gp.add_surface_points(
    geo_model=model,
    x=[1000, 5000, 9000],
    y=[5000, 5000, 5000],
    z=[-500, -1500, -2500],
    elements_names=['Sandstone', 'Sandstone', 'Sandstone']
)

# Add fault
fault_element = gp.data.StructuralElement(
    name='MainFault',
    surface_points=gp.data.SurfacePointsTable.from_arrays(
        x=[5000, 5000],
        y=[2000, 8000],
        z=[-500, -3000],
        names='MainFault'
    ),
    orientations=gp.data.OrientationsTable.initialize_empty(),
    color='#527682'
)

fault_group = gp.data.StructuralGroup(
    name='faults',
    elements=[fault_element],
    structural_relation=gp_engine.core.data.stack_relation_type.StackRelationType.FAULT
)

model.structural_frame.append_group(fault_group)

# Set fault relations
gp.set_is_fault(
    frame=model,
    fault_groups=['MainFault']
)
```

--------------------------------

### Initialize Default Structural Frame

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/StructuralFrame.md

Creates a minimal default structural frame with one group and one empty element. This is useful for starting a new structural model.

```python
from gempy.core.structural_model import StructuralFrame

@classmethod
def initialize_default_structure(cls) -> StructuralFrame:
```

```python
frame = StructuralFrame.initialize_default_structure()
# Contains one group 'default_formations' with one element 'surface1'
```

--------------------------------

### Build HTML Documentation Locally

Source: https://github.com/gempy-project/gempy/blob/main/DevelopersGuide.md

Navigate to the 'docs' directory and run 'make html' to build the documentation. The output will be in the 'build/html' subfolder. This process can take several hours on the first run.

```bash
cd docs
make html
```

--------------------------------

### Create Simple Single Fault Model

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/faults-API.md

Example of creating a GemPy model with a single fault. Requires importing gempy and numpy. Ensure surfaces and orientations are correctly defined and marked as faults before computation.

```python
import gempy as gp
import numpy as np

# Create model
model = gp.create_geomodel(
    project_name='SingleFault',
    extent=[0, 1000, 0, 1000, -1000, 0],
    resolution=[50, 50, 50],
    structural_frame=gp.data.StructuralFrame.initialize_default_structure()
)

# Add stratigraphy (initial surface1 element)
gp.add_surface_points(
    geo_model=model,
    x=[100, 500, 900],
    y=[500, 500, 500],
    z=[-200, -400, -600],
    elements_names=['surface1', 'surface1', 'surface1']
)

# Add fault data
gp.add_surface_points(
    geo_model=model,
    x=[500, 500],
    y=[100, 900],
    z=[-200, -800],
    elements_names=['MainFault', 'MainFault']
)

gp.add_orientations(
    geo_model=model,
    x=[500],
    y=[500],
    z=[-500],
    elements_names=['MainFault'],
    orientation=[[90, 60, 1]]  # 60° dipping fault
)

# Mark as fault
gp.set_is_fault(model, ['MainFault'])

# Compute
solutions = gp.compute_model(model)
```

--------------------------------

### Initialize Dense Grid with Topography and Sections

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/grid-API.md

Demonstrates initializing a dense grid, adding random topography, and defining cross-sections and custom evaluation points. Ensure necessary imports are present.

```python
import gempy as gp
import numpy as np

# Create model and get grid
grid = gp.Grid.init_dense_grid(
    extent=[0, 2000, 0, 2000, -1500, 0],
    resolution=[50, 50, 50]
)

# Add random topography
gp.set_topography_from_random(
    grid=grid,
    fractal_dimension=2.0
)

# Add cross-sections
sections = {
    'Profile_E-W': {
        'x': [0, 2000],
        'y': [1000, 1000],
        'z': [-1500, 0]
    },
    'Profile_N-S': {
        'x': [1000, 1000],
        'y': [0, 2000],
        'z': [-1500, 0]
    }
}
gp.set_section_grid(grid, sections)

# Add custom evaluation points
custom_points = np.array([
    [500, 500, -300],
    [1500, 1500, -1000]
])
gp.set_custom_grid(grid, custom_points)
```

--------------------------------

### Build Complete Model from Scratch

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/data-manipulation-API.md

Initializes a new geological model with specified extent and resolution, then adds surface points and orientations for stratigraphic layers before computing the model.

```python
import gempy as gp
import numpy as np

# Create model
model = gp.create_geomodel(
    project_name='CompleteModel',
    extent=[0, 2000, 0, 2000, -1500, 0],
    resolution=[50, 50, 50],
    structural_frame=gp.data.StructuralFrame.initialize_default_structure()
)

# Add surface points for stratigraphic layers
gp.add_surface_points(
    geo_model=model,
    x=[500, 1000, 1500],
    y=[500, 1000, 1500],
    z=[-200, -400, -600],
    elements_names=['TopLayer', 'TopLayer', 'TopLayer']
)

gp.add_surface_points(
    geo_model=model,
    x=[500, 1000, 1500],
    y=[500, 1000, 1500],
    z=[-500, -700, -900],
    elements_names=['MiddleLayer', 'MiddleLayer', 'MiddleLayer']
)

# Add orientations
gp.add_orientations(
    geo_model=model,
    x=[1000],
    y=[1000],
    z=[-300],
    elements_names=['TopLayer'],
    orientation=[[0, 5, 1]]  # Slight northward dip
)

gp.add_orientations(
    geo_model=model,
    x=[1000],
    y=[1000],
    z=[-700],
    elements_names=['MiddleLayer'],
    orientation=[[0, 5, 1]]
)

# Compute model
solutions = gp.compute_model(model)

```

--------------------------------

### Build and Upload Distributions for PyPI Release

Source: https://github.com/gempy-project/gempy/blob/main/DevelopersGuide.md

Commands to create distribution files and upload them to PyPI.

```bash
#  First create the dist
python -m build

# Second upload the distributions
twine upload dist/*
```

--------------------------------

### Initialize Octree Grid with Detailed Sections

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/grid-API.md

Sets up an octree grid for a main model and adds detailed cross-sections and a focused custom grid around an area of interest. Requires NumPy for point generation.

```python
# Octree for main model
grid = gp.Grid.init_octree_grid(
    extent=[0, 5000, 0, 5000, -3000, 0],
    octree_levels=4
)

# Add detailed sections
sections = {
    'KeySection1': {
        'x': [1000, 4000],
        'y': [2500, 2500],
        'z': [-3000, 0]
    }
}
gp.set_section_grid(grid, sections)

# Add focused custom grid around area of interest
aoi_points = np.array([
    [x, y, z]
    for x in np.linspace(2000, 3000, 10)
    for y in np.linspace(2000, 3000, 10)
    for z in np.linspace(-500, -1500, 5)
])
gp.set_custom_grid(grid, aoi_points)
```

--------------------------------

### number_of_elements

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/structural-elements.md

Gets the count of elements currently in the StructuralGroup.

```APIDOC
## number_of_elements

### Description
Count of elements in group.

### Property
* **number_of_elements** (int)

### Request Example
```python
count = group.number_of_elements
```
```

--------------------------------

### Access Model Solutions

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/GeoModel.md

Shows how to compute a model and access different types of solutions, including raw arrays like octree and custom points, and the computed mesh output if available.

```python
# Compute model
solutions = gp.compute_model(geo_model)

# Access different solution types
octree_block_model = solutions.raw_arrays.octree
custom_points_solution = solutions.raw_arrays.custom

# Access mesh output (if available)
if solutions.dc_meshes is not None:
    mesh = solutions.dc_meshes[0]
```

--------------------------------

### Initialize Grid with Extent and Resolution

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/Grid.md

Creates a Grid instance with specified spatial extent and resolution. This defines the boundaries and cell sizes of the computational grid.

```python
grid = Grid(
    extent=[0, 1000, 0, 1000, -1000, 0],
    resolution=[50, 50, 50]
)
```

--------------------------------

### Checking and Setting Active Grids

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/Grid.md

Demonstrates how to check if a specific grid type is active and how to set multiple active grids using bitwise OR.

```python
# Check which grids are active
if grid.active_grids & Grid.GridTypes.OCTREE:
    print("Octree grid is active")

# Set active grids
grid.active_grids = Grid.GridTypes.OCTREE | Grid.GridTypes.TOPOGRAPHY
```

--------------------------------

### Create Geological Model with Project Name

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/configuration.md

Initialize a new geological model with a specified project name.

```python
model = gp.create_geomodel(
    project_name='MyGeologicalModel'
)
```

--------------------------------

### number_of_orientations

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/structural-elements.md

Gets the total number of orientations across all elements within the StructuralGroup.

```APIDOC
## number_of_orientations

### Description
Total orientations across all elements.

### Property
* **number_of_orientations** (int)

### Request Example
```python
total = group.number_of_orientations
```
```

--------------------------------

### Initialize Octree Grid with Refinement

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/configuration.md

Initializes an octree grid with a specified number of refinement levels. Higher levels result in finer resolution.

```python
import gempy as gp

# Coarse octree (fast computation)
grid = gp.Grid.init_octree_grid(extent, octree_levels=2)

# Fine octree (detailed results)
grid = gp.Grid.init_octree_grid(extent, octree_levels=5)
```

--------------------------------

### Get Number of Orientations

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/structural-elements.md

Retrieve the count of orientation measurements associated with the element.

```python
count = element.number_of_orientations
```

--------------------------------

### number_of_points

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/structural-elements.md

Gets the total number of surface points across all elements within the StructuralGroup.

```APIDOC
## number_of_points

### Description
Total surface points across all elements.

### Property
* **number_of_points** (int)

### Request Example
```python
total = group.number_of_points
```
```

--------------------------------

### Grid() Constructor

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/Grid.md

Creates a new, empty grid instance. You can optionally provide the spatial extent and resolution for the grid during initialization.

```APIDOC
## Grid()

### Description
Creates a new grid instance. You can optionally specify the spatial extent and resolution.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **extent** (list, ndarray) - Optional - Spatial extent as [min_x, max_x, min_y, max_y, min_z, max_z]
- **resolution** (list, ndarray) - Optional - Grid resolution as [x_res, y_res, z_res]

### Request Example
```python
# Empty grid
grid = Grid()

# With extent and resolution
grid = Grid(
    extent=[0, 1000, 0, 1000, -1000, 0],
    resolution=[50, 50, 50]
)
```

### Response
#### Success Response (200)
- **Grid** (Grid) - A new Grid instance.

#### Response Example
```json
{
  "example": "Grid instance"
}
```
```

--------------------------------

### Basic Model Computation in GemPy

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/compute-API.md

Demonstrates the fundamental steps to create a geological model, add surface data, and compute the model using GemPy. Ensure GemPy is imported and a structural frame is initialized.

```python
import gempy as gp

# Create model
geo_model = gp.create_geomodel(
    project_name='BasicModel',
    extent=[0, 1000, 0, 1000, -1000, 0],
    resolution=[50, 50, 50],
    structural_frame=gp.data.StructuralFrame.initialize_default_structure()
)

# Add data
gp.add_surface_points(
    geo_model=geo_model,
    x=[100, 500, 900],
    y=[500, 500, 500],
    z=[-200, -400, -600],
    elements_names=['TopLayer', 'MiddleLayer', 'BottomLayer']
)

gp.add_orientations(
    geo_model=geo_model,
    x=[500],
    y=[500],
    z=[-400],
    elements_names=['TopLayer'],
    pole_vector=[[0, 0, 1]]
)

# Compute
solutions = gp.compute_model(geo_model)

# Check results
print(f"Block model computed: {solutions.raw_arrays.octree is not None}")
```

--------------------------------

### Get Element Name

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/structural-elements.md

Retrieve the name of a structural element. This is used for identification and lookup.

```python
element.name  # 'TopLayer'
```

--------------------------------

### Initialize Octree Grid

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/Grid.md

Initializes a Grid with an adaptive octree discretization. Specify the spatial extent and the number of octree refinement levels.

```python
grid = Grid.init_octree_grid(
    extent=[0, 1000, 0, 1000, -1000, 0],
    octree_levels=4
)
```

--------------------------------

### Get Number of Surface Points

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/structural-elements.md

Retrieve the count of surface point constraints associated with the element.

```python
count = element.number_of_points
```

--------------------------------

### Initialize GemPyEngineConfig with Default NumPy CPU Backend

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/configuration.md

Instantiates the GemPyEngineConfig with default parameters, utilizing the NumPy backend for CPU computation. This is suitable for models with up to approximately 10 million evaluation points.

```python
from gempy.core.data.gempy_engine_config import GemPyEngineConfig

config = GemPyEngineConfig(
    use_gpu: bool = False,
    backend: AvailableBackends = AvailableBackends.numpy,
    dtype: str = 'float64',
    compute_grads: bool = False
)
```

```python
import gempy as gp

config = GemPyEngineConfig()
solutions = gp.compute_model(model, engine_config=config)
```

--------------------------------

### Get Copy of All Surface Points

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/GeoModel.md

Obtain a copy of all surface points aggregated from all structural elements.

```python
all_points = geo_model.surface_points_copy
```

--------------------------------

### Get Transformed Surface Points

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/GeoModel.md

Retrieve surface points that have been transformed according to the grid and input transforms.

```python
transformed_points = geo_model.surface_points_copy_transformed
```

--------------------------------

### Grid.init_octree_grid()

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/Grid.md

Initializes a grid with adaptive octree discretization. This method is useful for creating grids that refine spatially based on certain criteria.

```APIDOC
## Grid.init_octree_grid(extent, octree_levels, base_resolution=None, legacy=False)

### Description
Initializes a grid with adaptive octree discretization. This method is useful for creating grids that refine spatially based on certain criteria.

### Method
Class Method

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **extent** (list, ndarray) - Required - Spatial extent [min_x, max_x, min_y, max_y, min_z, max_z]
- **octree_levels** (int) - Required - Number of octree refinement levels
- **base_resolution** (np.ndarray) - Optional - Base resolution; auto-computed if None
- **legacy** (bool) - Optional - If True, uses legacy base resolution [2, 2, 2]

### Request Example
```python
grid = Grid.init_octree_grid(
    extent=[0, 1000, 0, 1000, -1000, 0],
    octree_levels=4
)
```

### Response
#### Success Response (200)
- **Grid** (Grid) - Configured octree grid.

#### Response Example
```json
{
  "example": "Octree Grid instance"
}
```
```

--------------------------------

### Get Element ID

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/structural-elements.md

Retrieve the unique integer identifier for the structural element. This ID is auto-generated if not explicitly provided.

```python
element_id = element.id
```

--------------------------------

### Get Structural Group by Name

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/StructuralFrame.md

Retrieves a structural group using its name. Raises ValueError if the group is not found.

```python
def get_group_by_name(self, group_name: str) -> StructuralGroup:
    # ... implementation details ...
    pass
```

```python
formations = frame.get_group_by_name('formations')
```

--------------------------------

### Access Structural Frame

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/GeoModel.md

Get the structural frame of the geological model, which organizes structural groups, elements, and points.

```python
structural_frame = geo_model.structural_frame
```

--------------------------------

### Batch Processing with Model Serialization

Source: https://github.com/gempy-project/gempy/blob/main/_autodocs/api-reference/serialization-API.md

Illustrates how to create, compute, and save multiple variants of a geological model in a batch process using serialization. Ensures the output directory exists before saving.

```python
import gempy as gp
import os

# Save multiple model variants
base_model = gp.create_geomodel(
    project_name='BaseModel',
    extent=[0, 1000, 0, 1000, -1000, 0],
    resolution=[50, 50, 50],
    structural_frame=gp.data.StructuralFrame.initialize_default_structure()
)

gp.add_surface_points(
    geo_model=base_model,
    x=[100, 500, 900],
    y=[500, 500, 500],
    z=[-300, -600, -900],
    elements_names=['Layer1', 'Layer1', 'Layer1']
)

# Create variants with different parameters
for refinement in [2, 3, 4]:
    model_variant = gp.create_geomodel(
        project_name=f'Model_ref{refinement}',
        extent=[0, 1000, 0, 1000, -1000, 0],
        refinement=refinement,
        structural_frame=gp.data.StructuralFrame.initialize_default_structure()
    )
    
    # Copy data from base
    gp.add_surface_points(
        geo_model=model_variant,
        x=[100, 500, 900],
        y=[500, 500, 500],
        z=[-300, -600, -900],
        elements_names=['Layer1', 'Layer1', 'Layer1']
    )
    
    # Compute and save
    gp.compute_model(model_variant)
    output_path = f'./models/model_ref{refinement}.zip'
    os.makedirs('./models', exist_ok=True)
    gp.save_model(model_variant, output_path)
    print(f"Saved: {output_path}")
```