Terminal syntax
The QGIS plugin and the terminal use the same program. A simulation that is started from a terminal therefore produces the same files as one that is started from the plugin, and both appear in the job list of the other.
Important
A terminal shows neither the input layers nor the results. Open the geodata in QGIS before the first run to verify that the layers fit together (Geodata), and inspect the results of each step on a map before the next step is started. A model can run without any error message and still be wrong, for example because an inflow line lies at the wrong place.
Open a terminal
On Linux, open a terminal and activate the Python environment in which aXqua is installed:
mamba activate axqua-env
axqua --version
On Windows, open the Miniforge Prompt from the start menu and enter the same two commands. If the simulation software is installed in the Windows Subsystem for Linux, open the terminal of the Linux distribution instead and proceed as on Linux.
Commands
A command consists of the program name, an action and, for most actions, the case file:
axqua <action> <case-file> [options]
Setting up the computer (Plugin setup):
Command |
Function |
|---|---|
|
Create the profile of the computer from the software that is found on it. |
|
Verify the profile, including whether TELEMAC and OpenFOAM can be started. |
|
Print the profile in use. |
|
Print the environment script that aXqua finds in the installation folder of TELEMAC. The other programs are |
Installing the simulation software (Simulation Software):
Command |
Function |
|---|---|
|
Show the detected operating system and, for TELEMAC, OpenFOAM and the postprocessors, where each is installed. |
|
Show what the installation would do, which system packages are missing, and the command that installs them. Nothing is changed. The other programs are |
|
Start the installation as a process of its own and enter the result in the profile. Add |
|
Show the state of the installation and the last lines of its log. |
|
Stop the installation. What is already downloaded and built is kept. |
|
Download the input files of the example cases of an installed TELEMAC that are still missing. |
Preparing and checking a case:
Command |
Function |
|---|---|
|
Report everything in the case file that is not in order: missing files, unknown or impossible settings, and settings that are still empty. The command lists all problems at once. |
|
Check the case file, the input files and the simulation software, and stop at the first problem. |
|
Create a case file with the entries that every case has. |
|
List the example cases with their size (Example case). |
|
Download the example case into |
|
Run the preprocessing and write the TELEMAC model. |
|
Run the preprocessing and start TELEMAC once, to verify that it accepts the model. |
|
Convert CAD files into the terrain and the layers of a case. |
|
Show which simulations are configured, built and run. |
|
Show the number of cells of the OpenFOAM mesh without building it. |
|
Create the workbook for field measurements. |
|
Compare the elevations of the measurement points with the terrain model. |
|
Render the predefined figures with VisIt. |
Results for ParaView and VisIt (Postprocessing):
Command |
Function |
|---|---|
|
List the TELEMAC results of the case with their time steps, and state which of them are exported. |
|
Convert the TELEMAC results of the case into files that ParaView ( |
|
Convert one result file without a case. The geometry file of the model provides the exact node coordinates. |
Tools for input data:
Command |
Function |
|---|---|
|
Cut a raster, for example a DEM, to a polygon. |
|
Estimate a rating curve from channel width, bed slope and roughness. |
|
Write a case file of the current type ( |
Disk space and documentation:
Command |
Function |
|---|---|
|
List the files of a case that nothing needs any more, by category and with their size. Nothing is removed (Freeing disk space). |
|
Remove the listed items with these identifiers. |
|
Name the copy of this documentation built on this computer, which Help in the plugin opens, and the published address. |
Running simulations as jobs (Batch-processing (headless)):
Command |
Function |
|---|---|
|
Start a simulation as a job and print its ID. |
|
Run the calibrated model for the validation situation of the case and compare it with the validation data (validation run). |
|
List all jobs. |
|
Show the state and the progress of a job. |
|
Show the log of a job while it runs. |
|
Stop a job and all processes that it started. |
Each command explains its options with --help, for example axqua submit --help.
Options for scripts
With the option --json, every command prints its result as one JSON document, which other programs can read reliably. If a command fails, its exit code indicates the cause, so that a script can react without reading the message:
Exit code |
Cause |
|---|---|
0 |
Success |
2 |
Error in the case file |
3 |
Error in the geodata |
4 |
Simulation software not reachable |
5 |
The simulation failed |
6 |
The mesh could not be created |
1 |
Any other error |
130 |
Cancelled by the user |
Scripts in the case folder
The template folder cases/case-template/ contains one Python script per working step, for example preprocessing.py, initial_run.py and mesh_convergence_study.py. They perform the same steps as the commands above and run in the foreground, so that the output of the simulation code appears directly in the terminal. Settings that apply to one step only are listed at the top of each script.
cd cases/my-reach
python preprocessing.py
python initial_run.py