Simulation Output

At the end of the simulation, an output file sedtrails_results.nc is written in netcdf (*.nc) format. The files have generally been written in the spirit of CF conventions for multidimensional arrays of trajectories.

Some metadata is still missing from the output files!

Output File Inspection

By entering the command sedtrails inspect -f C:\your-filepath-here\sedtrails_results.nc, you can check the data written to your file. For the example file, the following is displayed in the terminal:

Inspecting NetCDF file: C:\sedtrails\results\sedtrails_results.nc
====================================================================================
SEDTRAILS NETCDF FILE METADATA
====================================================================================
FILE: C:\sedtrails\results\sedtrails_results.nc
SIZE: 1.42 MB

GLOBAL ATTRIBUTES:
------------------------------------------------------------
  title: SedTRAILS Particle Simulation Results
  institution: SedTRAILS Particle Tracer System
  created_on: 2025-10-24T10:44:50.245422

DIMENSIONS:
------------------------------------------------------------
  n_populations: 2
  name_strlen: 24
  n_particles: 15
  n_timesteps: 880
  n_flowfields: 2

COORDINATES:
------------------------------------------------------------
  n_particles: ('n_particles',) int64 (15,)
  n_populations: ('n_populations',) int64 (2,)
  n_timesteps: ('n_timesteps',) int64 (880,)
  n_flowfields: ('n_flowfields',) int64 (2,)
  name_strlen: ('name_strlen',) int64 (24,)

DATA VARIABLES:
------------------------------------------------------------
  population_name: ('n_populations', 'name_strlen') |S1 (2, 24)
  population_particle_type: ('n_populations',) int64 (2,)
  population_start_idx: ('n_populations',) int64 (2,)
  population_count: ('n_populations',) int64 (2,)
  trajectory_id: ('n_particles', 'name_strlen') |S1 (15, 24)
  population_id: ('n_particles',) int64 (15,)
  time: ('n_particles', 'n_timesteps') float64 (15, 880)
  x: ('n_particles', 'n_timesteps') float64 (15, 880)
  y: ('n_particles', 'n_timesteps') float64 (15, 880)
  z: ('n_particles', 'n_timesteps') float64 (15, 880)
  burial_depth: ('n_particles', 'n_timesteps') float64 (15, 880)
  mixing_depth: ('n_particles', 'n_timesteps') float64 (15, 880)
  status_alive: ('n_particles', 'n_timesteps') int64 (15, 880)
  status_buried: ('n_particles', 'n_timesteps') int64 (15, 880)
  status_domain: ('n_particles', 'n_timesteps') int64 (15, 880)
  status_transported: ('n_particles', 'n_timesteps') int64 (15, 880)
  status_released: ('n_particles', 'n_timesteps') int64 (15, 880)
  status_mobile: ('n_particles', 'n_timesteps') int64 (15, 880)
  covered_distance: ('n_flowfields', 'n_particles', 'n_timesteps') float64 (2, 15, 880)
  flowfield_name: ('n_flowfields', 'name_strlen') |S1 (2, 24)

====================================================================================

This indicates the variables written (e.g., status_buried) as well as the dimensions and data types of each variable.

Details of Output File Contents

In this section we break down the above example, exploring the contents of the file and meaning of the variables in greater detail.

Global Attributes:

These are general properties of the file, indicating that it contains results generated by SedTRAILS.

  • title: SedTRAILS Particle Simulation Results

  • institution: SedTRAILS Particle Tracer System

  • created_on: 2025-10-24T10:44:50.245422: Date and time of file creation written asyyyy-mm-ddTHH:MM:SS.SSSSS

Dimensions

Dimensions are the fundamental “units” of netcdf files and can be thought of as the axes along which the data is organized. Here the names and sizes of the dimensions are defined.

  • n_populations: 2

    • The number of particle population specified in the configuration file. (see more details HERE)

  • name_strlen: 24

    • The maximum number of characters in string variables used in the file.

  • n_particles: 15

    • The total number of particles in the simulation (across all populations)

  • n_timesteps: 880

    • The total number of timesteps simulated.

  • n_flowfields: 2

    • The number of different flow fields simulated (e.g., bedload and suspended load)

Coordinates:

The coordinates indicate the actual variables for each dimension defined above (e.g., here there are 15 particles). In each of the below cases, they are just index arrays from 0, 1, ..., n-1

  • n_particles: ('n_particles',) int64 (15,)

  • n_populations: ('n_populations',) int64 (2,)

  • n_timesteps: ('n_timesteps',) int64 (880,)

  • n_flowfields: ('n_flowfields',) int64 (2,)

  • name_strlen: ('name_strlen',) int64 (24,)

For example, here our particles are numbered 0-14 and timesteps from 0-879. The actual data that we are interested in is stored below.

Data Variables:

These are the main output variables that will be of primary interest for users who want to understand where their particles are going:

  • population_name: ('n_populations', 'name_strlen') |S1 (2, 24)

    • The name of each population as a string of characters (e.g., population_1 and population_2)

  • population_particle_type: ('n_populations',) int64 (2,)

    • The type of particle contained in each population (e.g., sand)

  • population_start_idx: ('n_populations',) int64 (2,)

    • The start index of each population in the array of all particles (e.g., 0 and 10 here)

  • population_count: ('n_populations',) int64 (2,)

    • The number of particles in each populations of the model (e.g., 10 and 5 here)

  • trajectory_id: ('n_particles', 'name_strlen') |S1 (15, 24)

    • The name of each trajectory (e.g., traj_0 through traj_14 here)

  • population_id: ('n_particles',) int64 (15,)

    • The ID indicating which population each particle belongs to (e.g., [0 0 0 0 0 0 0 0 0 0 1 1 1 1 1] here)

  • time: ('n_particles', 'n_timesteps') float64 (15, 880)

    • The time for each particle at each timestep (e.g., 1.47448560e+09, which is the number of seconds since 1970-01-01 00:00:00 UTC, i.e., the Unix epoch)

  • x: ('n_particles', 'n_timesteps') float64 (15, 880)

    • The x-coordinate of each particle at each timestep.

  • y: ('n_particles', 'n_timesteps') float64 (15, 880)

    • The y-coordinate of each particle at each timestep.

  • z: ('n_particles', 'n_timesteps') float64 (15, 880)

    • The z-coordinate of each particle at each timestep.

  • burial_depth: ('n_particles', 'n_timesteps') float64 (15, 880)

    • The burial depth \(\delta_{burial}\) of each particle at each timestep.

  • mixing_depth: ('n_particles', 'n_timesteps') float64 (15, 880)

    • The mixing depth \(\delta_{mixing}\) of each particle at each timestep.

  • status_alive: ('n_particles', 'n_timesteps') int64 (15, 880)

    • A binary status indicator showing whether a particle is “alive” and therefore capable of being transported (1), or dead and (permanently) removed from consideration (0). This variable is primarily intended for biological particles (e.g., coral larvae or mangrove propagules), and has not yet been fully implemented in the current version of the model. For all abiotic particles (e.g., sediment or passive tracers), status_alive = 1, since it concerns their availability for transport.

  • status_buried: ('n_particles', 'n_timesteps') int64 (15, 880)

    • A binary status indicator showing whether a particle is buried (and therefore capable of being transported) (1), or not buried and (temporarily) removed from consideration (0).

  • status_domain: ('n_particles', 'n_timesteps') int64 (15, 880)

    • A binary status indicator showing whether a particle is in the domain (and therefore capable of being transported) (1), or has exited the domain and therefore been removed from consideration (0).

  • status_transported: ('n_particles', 'n_timesteps') int64 (15, 880)

    • A binary status indicator showing whether a particle has been transported (1), or not (0).

  • status_released: ('n_particles', 'n_timesteps') int64 (15, 880)

    • A binary status indicator showing whether a particle has already been released (1) or is waiting to be released (0).

  • status_mobile: ('n_particles', 'n_timesteps') int64 (15, 880)

    • A binary status indicator showing whether a particle is mobile (1) or static (0).

  • covered_distance: ('n_flowfields', 'n_particles', 'n_timesteps') float64 (2, 15, 880)

    • The distance travelled by each particle in a given output timestep (\(distance=\sqrt{\Delta x^2 + \Delta y^2}\))

  • flowfield_name: ('n_flowfields', 'name_strlen') |S1 (2, 24)

    • The name of each flowfield specified in the config file (e.g., bed_load_velocity or suspended_velocity)

For example, we can see from this that the covered_distance variable is stored as a float64 number for 15 'n_particles' transported by 2 'n_flowfields' at 880 'n_timesteps'.

Output Visualization

By entering the command sedtrails viz trajectories -f C:\your-filepath-here\sedtrails_results.nc, you can plot the trajectories of your particles and information about their distance travelled plus differences in population:

sedtrails trajectory example

The following commands can be used to save and customize output:

  • --file or -f: Path to the SedTRAILS netCDF file to visualize. By default, it expects a sedtrails_results.nc file in the current directory. [default: sedtrails_results.nc]

  • --save or -s: Save plot as a PNG file. Creates a particle_trajectories.png file

  • --output-dir or -o:Directory to save plot if --save is used. Default is the current directory. [default: .]

  • --help or -h: Show this message and exit.

More advanced visualization functions will be added in future releases, but for now we encourage users to get creative with their own visualizations directly from the output data.