Running PyTolosa

Two running modes are available: interactive mode and batch mode.

Getting Help

To get the running information:

python3 -m pytolosa -h

Interactive Mode

The interactive mode enables the user to enter all needed information without listing the arguments manually (see Batch mode below). The user will interact with the program to enter needed information.

Serial Execution

pytolosa -i

Or without the PYTHONPATH environment variable:

# Place yourself in the /PyTolosa directory
python3 -m pytolosa -i

Parallel Execution

Run this post-treatment tool in parallel with 4 MPI processes:

mpirun -np 4 python3 -m pytolosa -i

Without the PYTHONPATH environment variable:

# Place yourself in the /PyTolosa directory
mpirun -np 4 python3 -m pytolosa -i

Batch Mode

The batch running mode enables the user to run this post-treatment program without any interaction. The existing running arguments are listed below.

General Arguments

Argument	Description
`-wdir WDIR`	Working Directory (./bin/res/…) with output directories
`-c1D`	Run 1D cases
`-c2D`	Run 2D cases
`-tmin TMIN`	Set the time to begin data extraction. Format: Gregorian (YYYY-MM-DD_HH:MM) or Julian CNES date
`-tmax TMAX`	Set the time to stop data extraction. Format: Gregorian (YYYY-MM-DD_HH:MM) or Julian CNES date
`-all`	Run all 1D and/or 2D cases found in directory tree
`-del`, `--delete`	Clean previous results in working directory
`-title TITLE`	Set title for results figures
`-ns`, `--nostream`	Access binary file without stream
`-verbose VERBOSE`	Verbosity level. From 0 to 2

Field Selection

Choose at least one field to extract:

Argument	Field
`-h`	Water depth fields
`-ssh`	Sea surface height fields
`-u`	Horizontal velocity fields
`-v`	Vertical velocity fields
`-bathy`	Bathymetry

2D Case Arguments

Arguments for 2D case post-processing:

Field Range Control

Argument	Description
`-hmin HMIN`	Minimum height value considered
`-hmax HMAX`	Maximum height value considered
`-sshmin SSHMIN`	Minimum SSH value considered
`-sshmax SSHMAX`	Maximum SSH value considered
`-umin UMIN`	Minimum horizontal velocity value considered
`-umax UMAX`	Maximum horizontal velocity value considered
`-vmin VMIN`	Minimum vertical velocity value considered
`-vmax VMAX`	Maximum vertical velocity value considered
`-bmin BATHYMIN`, `--bathymin BATHYMIN`	Minimum bathymetry value considered
`-bmax BATHYMAX`, `--bathymax BATHYMAX`	Maximum bathymetry value considered

Display Window

Argument	Description
`-plottype PLOTTYPE`	Plot type if smaller window is considered: `static` or `dynamic`
`-xmin XMIN`	Set smaller display window with minimum x coordinate
`-xmax XMAX`	Set smaller display window with maximum x coordinate
`-ymin YMIN`	Set smaller display window with minimum y coordinate
`-ymax YMAX`	Set smaller display window with maximum y coordinate
`-lonmin LONGITUDEMIN`, `--longitudemin LONGITUDEMIN`	Set smaller display window with minimum longitude
`-lonmax LONGITUDEMAX`, `--longitudemax LONGITUDEMAX`	Set smaller display window with maximum longitude
`-latmin LATITUDEMIN`, `--latitudemin LATITUDEMIN`	Set smaller display window with minimum latitude
`-latmax LATITUDEMAX`, `--latitudemax LATITUDEMAX`	Set smaller display window with maximum latitude

Animation Settings

Argument	Description
`-an_fps AN_FPS`	Animation frames per second
`-an_ext AN_EXT`	Animation extension (default: mp4)
`-an_size AN_SIZE`	Animation image size (number of horizontal pixels)
`-cmap CMAP`	Colormap: new color range. See matplotlib colormap reference
`-dpi DPI`	Image resolution in dots per inch. Default: 400

Usage Examples

Example 1: Process 2D Water Depth

python3 -m pytolosa -wdir ./bin/res -c2D -h

Example 2: Process 1D SSH Time Series

python3 -m pytolosa -wdir ./results -c1D -ssh

Example 3: Process 2D with Custom Range and Animation

python3 -m pytolosa -wdir ./bin/res -c2D -ssh \
  -sshmin -2.0 -sshmax 2.0 \
  -an_fps 30 -an_ext mp4 \
  -cmap viridis -dpi 600

Example 4: Process with Time Range

python3 -m pytolosa -wdir ./results -c2D -h \
  -tmin 2024-01-01_00:00 \
  -tmax 2024-01-02_00:00

Example 5: Zoom on Subdomain

python3 -m pytolosa -wdir ./results -c2D -ssh \
  -xmin 0 -xmax 1000 \
  -ymin 0 -ymax 500 \
  -plottype dynamic

Example 6: Process All Cases in Directory

python3 -m pytolosa -wdir ./simulations -all -c2D -h -ssh

Example 7: Parallel Processing

mpirun -np 8 python3 -m pytolosa -wdir ./large_simulation -c2D -h -u -v

Batch Mode Command Template

Serial Execution

pytolosa [arguments]

Or without PYTHONPATH:

# Place yourself in the /PyTolosa directory
python3 -m pytolosa [arguments]

Parallel Execution

Run with 4 MPI processes:

mpirun -np 4 pytolosa [arguments]

Or without PYTHONPATH:

# Place yourself in the /PyTolosa directory
mpirun -np 4 python3 -m pytolosa [arguments]

Output Files

PyTolosa generates:

For 1D Cases

PNG/PDF plots of time series
Located in same directory as input CSV files

For 2D Cases

MP4/AVI/GIF animations (depending on -an_ext)
PNG/PDF static frames
Located in working directory specified by -wdir

Troubleshooting

Common Issues

Error: No module named ‘pytolosa’

Solution: Check your PYTHONPATH or run from PyTolosa directory

Error: No binary mesh file found

Solution: Ensure mesh connectivity file is in the same directory as output files

Error: FFMPEG not found

Solution: Install FFMPEG (conda install ffmpeg or apt-get install ffmpeg)

Animation is too slow/fast

Solution: Adjust -an_fps parameter (try 20-60 fps)

Colors are washed out

Solution: Adjust field min/max values or change colormap

Next Steps

Features - Learn about all PyTolosa capabilities
System Requirements - Ensure proper environment setup