Geoloop Command-Line Interface (CLI)
Geoloop provides a unified command-line interface for running single simulations, stochastic simulations, processing lithology data to subsurface thermal properties, generating heat load time-profiles based on data-files or synthetic patterns, generating flow rate time-profiles based on data-files or synthetic patterns, plotting simulation results, and creating batch-run workflows.
This page describes the full CLI and how to use it.
Overview
After installing Geoloop, the geoloop command becomes available:
Top-Level Simulation Commands
Each command runs a specific module and expects a JSON configuration file as input.
Single Borehole Heat Exchanger (BHE) Simulation
Runs one complete BHE simulation.Stochastic (Monte Carlo) Simulation
Process Lithology
Computes and plots depth-dependent thermal subsurface properties.
Compute Heat Load Profile
Generates and plots a time-profile of heat extraction and/or injection rates.
Compute Flow Rate Profile
Generates and plots a time-profile of flow rates.
Plot Simulation Results
Creates plots of simulation results (e.g. temperature-depth profiles, time-plots of system variables).
Batch Processing
A batch run allows you to chain multiple top-level simulation commands into one workflow using a single JSON file. To view all batch run commands:
Geoloop batch provides commands to build batch configuration JSON files and to execute the batch script. Note: all batch commands come with their own --help method.
The batch commands should be executed from the directory where the batch configuration JSON and linked configuration commands are stored. For an example, see Simple Simulation.
Creating batch Configuration Files
A. Using batch create
This method generates a batch JSON by specifying steps explicitly, for example:
geoloop batch create batch.json \
--process-lithology lithology.json \
--calculate-loadprofile loadprofile.json \
--single-run simulation.json \
--plot plot.json
Each flag adds a new step.
Example output (batch.json):
{
"commands": [
{ "command": "Lithology", "args": ["lithology.json"] },
{ "command": "Loadprofile", "args": ["loadprofile.json"] },
{ "command": "SingleRunSim", "args": ["simulation.json"] },
{ "command": "Plotmain", "args": ["plot.json"] }
]
}
B. Using the Interactive batch Wizard
The wizard guides you step-by-step for creating a batch configuration JSON:
You will be prompted to:
- enable/disable steps
- provide config file paths
- confirm execution order
- save the resulting batch JSON
Example prompt:
geoloop batch wizard
Welcome to the Geoloop Batch Wizard!
Let's build your batch sequence.
Select command to add:
Options: stochastic-run, single-run, process-lithology, calculate-loadprofile, calculate-flowdata, plot, done:
single-run
Enter path to the config JSON file:: simulation.json
Command added!
Select command to add:
Options: stochastic-run, single-run, process-lithology, calculate-loadprofile, calculate-flowdata, plot, done:
plot
Enter path to the config JSON file:: plot.json
Command added!
Select command to add:
Options: stochastic-run, single-run, process-lithology, calculate-loadprofile, calculate-flowdata, plot, done:
done
Where should the batch JSON be saved?:
path/to/directory/batch.json
Executing a batch File
The system prints progress:
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Running command Lithology
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Running command Loadprofile
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
...
Path Resolution in batch Files
All file paths inside a batch JSON are resolved relative to the location of the batch file.
Recommended structure:
This ensures the batch workflow can be moved as a self-contained folder.