Run Simulation From Terminal

Seeding

A CarbonDrift Simulation can be run directly from the terminal. First, however, we must provide a seeding pickle file, which contains the following information:

lons: Array of particle longitudes.
lats: Array of particle latitudes.
z: Array of release depths.
mass: Array of particle masses.
origin_marker: Array of speciffic markers (integers), which allow for post analysis grouping (not required).

An example of such a pickle file is provided in the supplementary data directory. Its contents can be viewed in python with:


                    import pickle
                    with open("./supplementary_data/cnidaria_M_seed.pkl", "rb") as f:
                        data = pickle.load(f)
                    print(data)


                        lon     lat          mass    z   origin_marker
                0      -163     -77  0.000000e+00  -20               3
                1      -162     -77  1.478556e+09  -20               3
                ...     ...     ...           ...   ..             ...
                36596   -16      83  3.649607e+09  -20               0

Here the origin_marker specifies a speciffic biome (Luo et al, 2020.).

CarbonDrift provides a Seed class, in which the user can seed the particles with the prescripton from Luo et al, (2020). Initial mass can be set to either their esitmates or to the relative value of 1. The grid geometry can be manipulated by the use of arguments latmin, latmax, lonmin, lonmax, dx and dy.

The above pickle file, e.g. can be reproduced by running the following python script


                    from carbondrift.simulation.seeding import Seed

                    phylum = "cnidaria"
                    poctype = "M"

                    S = Seed(areapath = "./CarbonDrift/supplementary_data/area_grid.npy",
                            bathymetrypath="./CarbonDrift/supplementary_data/etopo2_remaped1deg.nc",
                            outfile = f"{phylum}_{poctype}_seed.pkl", phylum = phylum,
                            initialmassdata="./CarbonDrift/supplementary_data/Luo_M_Eg_biome_data.json",
                            biomegridpath="./CarbonDrift/supplementary_data/biome_grid.npy", poctype = poctype)

Running

To run a CarbonDrift simulation one simply has to run the following command in the terminal

                    run_simulation -tmp <temperature netcdf filepath>

Of course other parameters should be provided as well. The full list of the parameters can be viewed here, or use the header in the terminal.

The parameters can also be presaved to a .txt file. For example

                    -tmp
                    ./supplementary_data/tmp_luo_remaped1deg.nc
                    -b
                    ./supplementary_data/etopo2_remaped1deg.nc
                    -s
                    1993-01-01-0
                    -mdtype
                    mass
                    -ev
                    2
                    -sdata
                    ./supplementary_data/cnidaria_M_seed.pkl
                    -o
                    test.nc
                    -st
                    50
                    -w0
                    -0.01
                    -dto
                    1:0:0
                    -d
                    exp
                    -wtype
                    variable

One can then simply run the simulation by running the command

                run_simulation @/path_to_params.txt

Example

An example of how to run a simulation in bash is provided here.

Fragmentation

To activate fragmentation the -f parameter should be added to the parameters file. Additionaly, a fragmentation condition (boolean array) in the form of python code should be provided, where the variables are inclosed in semicolumns. For example:

                    -ffunc
                    np.logical__and(;m;>0.1, np.sqrt(;m; / ;m0;) * 0.2 > np.random.random(len(;m0;)))

Here, the model will first check if the mass of active particles is greater than 0.1 and then proceed to see, if their relative value are greater than some sampled random numbers. If both conditions are True, each particle will split into two new particles, with masses sampled from a uniform distribution, where the total mass is preserved. The command line run method currently allows the use of the following variables:

T for sea water temperature
m for particle mass
m0 for initial particle mass
u for x sea water velocity
v for y sea water velocity
uh for horizontal sea water velocity
z for particle depth

Note: The run time of a simulation can be significantly increased with fragmentation. Furthermore the memory usage can be substantial, thus it is advised to run these simulations in grid mode by specifying

in the parameter file, where sf is the split factor argument, which splits the simulation into a given number of sub-simulations.

Notes

Horizontal Advection considerably increases simulation time.
To reduce the output file size, paramters -ev and -dto should be adjusted appropriately. The former specifies the export_variables in the run() method (for more info reffer to the main() function in simulation.run), while the latter specifies the time_step_output.

For release-specific notes refer to Release Notes.