Overview
Stacker is a numerical forward model designed to explore Walther's Law and simulate the migration of facies patches in shallow-water carbonate environments. The model provides insights into stratigraphic architecture through forward modeling of sediment deposition, facies distribution, and environmental changes over geological time.
Key Features:
- Simulation of facies belt and facies mosaic models
- Configurable sediment production models (Constant or Bosscher & Schlager)
- Support for multiple facies with distinct deposition rates and characteristics
- Integration of subsidence and sea-level changes
- Advanced visualization and analysis tools
- GUI-based operation for ease of use
Disclaimer
The manual pages https://mindthegap-erc.github.io/Stacker/ have been generated based on the code using an LLM and reviewed by the author and the maintainers. The latter take responsibility for the contents.
Installation & Requirements
Prerequisites
- MATLAB: R2018b or later recommended
- Required Toolboxes: None (uses core MATLAB functionality)
- Operating System: Windows, macOS, or Linux
Installation Steps
- Clone or download the Stacker repository
- Add the Stacker directory to your MATLAB path
- Ensure all parameter files are in the
parameters/subdirectory. Note that the default files are already provided in this directory - Verify initial bathymetry and sea-level curve files are accessible
% In MATLAB, add Stacker to your path:
addpath('/path/to/stacker')
addpath('/path/to/stacker/parameters')Running Stacker
Starting the Application
Launch Stacker from the MATLAB command window:
% Start Stacker GUI
stacker
GUI Interface: The Stacker GUI will open with control buttons on the right side and a visualization area on the left. The interface is designed for intuitive, step-by-step model execution.
Basic Workflow
Default Configuration
By default, Stacker looks for:
- Parameter Path:
parameters/ - Parameter File:
stackerFaciesMosaic.txt
Important: Parameter files must be properly formatted and all referenced files (bathymetry, sea-level curves, cloud point files) must exist in their specified locations.
Parameter Reference
Main Model Parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
modelName |
String | Identifier for the model run | FaciesMosaic |
gridCellsX |
Integer | Number of grid cells in X dimension | 100 |
gridCellsY |
Integer | Number of grid cells in Y dimension | 100 |
gridDx |
Float | Grid cell spacing in X (km) | 0.1 |
gridDy |
Float | Grid cell spacing in Y (km) | 0.1 |
totalEMT |
Float | Total model duration (My) | 1.0 |
deltaT |
Float | Model time step (My) | 0.001 |
subsidenceRate |
Float | Subsidence rate (m/My) | 20.0 |
intertdidalWDRange |
Float | Tidal range (meters) | 1.0 |
nFacies |
Integer | Number of facies types | 5 |
File References
| Parameter | Description | Format |
|---|---|---|
initialBathymetryFname |
Initial topography/bathymetry file | ASCII matrix |
sealevelCurveFname |
Sea-level curve through time | ASCII vector |
Facies Parameters
For each facies, specify:
| Parameter | Type | Description |
|---|---|---|
deposRate |
Float | Maximum deposition rate (m/My) |
faciesRGB |
Float[3] | RGB color code for visualization (0-1 scale) |
Model Types
FaciesBelts Model
Deterministic depth-controlled facies distribution.
| Parameter | Description |
|---|---|
minWaterDepth |
Minimum water depth for facies occurrence |
maxWaterDepth |
Maximum water depth for facies occurrence |
FaciesMosaic Model
Stochastic facies patches with migration.
| Parameter | Description |
|---|---|
nFaciesMosaicElements |
Number of facies mosaic elements |
nFaciesMosaicNumberOfCloudPoints |
Number of XY points per element |
faciesMosaicElementMovementType |
Migration type: RandomWalk, StraightLines, DeepestNeighbour, SteepestDescent |
Facies Mosaic Element Parameters
For each mosaic element:
| Parameter | Type | Description |
|---|---|---|
faciesCode |
Integer | Associated facies type (1-5) |
migrationRateX |
Float | Maximum migration rate in X (km/iteration) |
migrationRateY |
Float | Maximum migration rate in Y (km/iteration) |
startX |
Float | Initial X coordinate of centroid (km) |
startY |
Float | Initial Y coordinate of centroid (km) |
radius |
Float | Element radius (km) |
cloudFilename |
String | MATLAB .mat file with point cloud coordinates |
Sediment Production Models
- Constant: Uniform production rate independent of water depth
- Bosscher&Schlager: Depth-dependent production following the Bosscher & Schlager (1992) curve
Detailed Workflow
Step 1: Load Parameter File
- Set the parameter file path (default:
parameters/) - Set the parameter filename (default:
stackerFaciesMosaic.txt) - Click "Load parameter file"
- Verify console output confirms successful loading
Console Output Example:
Read parameters file for model FaciesMosaic type FaciesMosaic to run for 1000 iterations for 1.00 My with 5 facies on a 100 by 100 cell grid
Step 2: Initialise Model
- Click "Initialise model"
- The model arrays are allocated in memory
- Initial bathymetry is plotted in the main window
- Random number generator is seeded (seed: 42) for reproducibility
Step 3: Run Model
- Click "Run model" to execute the simulation
- Progress is displayed in the console
- Simulation iterates through all time steps
Note: Model execution time depends on grid size and number of iterations. For a 100×100 grid with 1000 iterations, expect several minutes of computation.
Step 4: Plot Model Results
- Click "Plot model results"
- Multiple visualization windows display:
- Final bathymetry and facies distribution
- Stratigraphic cross-sections
- Chronostratigraphic diagrams (five virtual cores)
- Migration pathways of each mosaic element in plan view
Optional: Analysis Tools
Additional analysis functions (commented out in GUI but available):
- Analyse model output: Calculate bed thickness distributions and stratigraphic order metrics
- Run and plot animation: Generate animated visualization during model execution
- Plot cross-section animation: Create GIF animation of traverse through model
- Plot correlation panel animation: Generate animated correlation panels
Clearing Results
Click "Clear results" to reset all model variables and start fresh.
Example Parameter File
Below is a minimal example of a parameter file structure:
FaciesMosaic # Model name
100 # Grid cells X
100 # Grid cells Y
0.1 # Grid spacing X (km)
0.1 # Grid spacing Y (km)
1.000 # Model duration (My)
0.001 # Time step (My)
parameters/initialTopography.txt # Initial bathymetry file
20.0 # Subsidence rate (m/My)
parameters/sealevelCurve.txt # Sea-level curve file
1.0 # Tidal range (m)
2 # Number of facies
# Facies 1
1 # Facies code
5000.0 # Max deposition rate (m/My)
1 0.498 0.314 # RGB color
# Facies 2
2
1000.0
1 1 0
# ... (continue for all facies)
FaciesMosaic # Model type
Constant # Production model
5 # Number of mosaic elements
500 # Points per element
RandomWalk # Migration type
# Mosaic Element 1
1 # Element number (it is possible that more than one mosaic elements correspond to one facies)
1 # Facies code
0.5 0.5 # Migration rates (km/iteration)
2.5 2.5 # Initial position (km)
2.4 # Radius (km)
parameters/cloud1.mat # Cloud point file
# ... (continue for all elements)