{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Getting started\n", "\n", "Here we provide general information on setting up and running PyLag. For specific applications - e.g., running PyLag with data generated by a given hydrodynamic model, such as FVCOM - please see [PyLag's tutorial examples](../examples/index.ipynb).\n", "\n", "After PyLag has been [installed](../install/installation.rst), a typical workflow involves *three* steps: 1) Obtaining and/or generating the required input files; 2) Running the simulation; and 3) Analysing the results. Further details regarding these three steps are provided below. \n", "\n", "\n", "## Step 1: Obtaining and/or generating the set of input files required by PyLag\n", "\n", "For typical use cases, PyLag requires four types of input:\n", "\n", "1) **NetCDF data files** containing input data (e.g. velocity components) required by PyLag.\n", "\n", "2) **A grid metrics file**, which describes the underlying grid on which input data are defined.\n", "\n", "3) **An initial positions file**, which gives the starting coordinates of particles in Cartesian or Geographic coordinates.\n", "\n", "4) **A run configuration file** in which all run parameters and paths are set.\n", "\n", "### 1) NetCDF data files\n", "\n", "NetCDF data files containing fluid velocity components, eddy diffusivities etc are required inputs. All ocean specific variables for a given time point or set of time points should be provided in the same file. The dataset may be split into multiple files through time, with all files following a common naming convention (see below). When support for including the impact of waves and direct atmospheric forcing is included, the set of input files will be extended to include files specific to wave and astmopheric products respectively.\n", "\n", "If the set of ocean specific variables have been generated by one of the named models supported by PyLag (e.g. ROMS, FVCOM) then the data files can be fed to PyLag as is. This will typically be the case for data obtained from other supported sources too (e.g. the CMEMS catalogue). However, some manipulation may be needed if, say, the set of ocean variables have been saved in separate files.\n", "\n", "All input files must contain a `time` variable with a [units attribute](https://unidata.github.io/netcdf4-python/), allowing times to be converted into [datetime](https://docs.python.org/3/library/datetime.html) objects. The files should also contain grid information (e.g. depth, latitude and longitude arrays). Any number of input data files can be provided. With respect to file name conventions, the primary requirement is that they are named using a pattern that allows them to be sorted sequentially through time. For example, two data files for January and February 2002 could be named `file_001.nc` and `file_002.nc`. Using appropriately constructed datestrings in the file name is usually sufficient to guarentee sequential ordering. PyLag will automatically check that the simulation start and end times lie within the time range covered by the input files, and that at least one of the particles in the initial particle seed lies within the spatial grid.\n", "\n", "As an example, the header for a NetCDF file downloaded from the CMEMS catalogue is given below. The file contains information from the [GLOBAL_REANALYSIS_PHY_001_031](http://marine.copernicus.eu/documents/PUM/CMEMS-GLO-PUM-001-031.pdf) product. The file contains grid information and *u* and *v* velocity components for a global reanalysis run at 1/4 degree resolution. From the global metadata, it can be seed data from multiple months has been concatenated into a single file for convenience.\n", "\n", "
\n", "NetCDF header for CMEMS data product GLOBAL_REANALYSIS_PHY_001_031\n", "
\n", "```\n", "netcdf grepv2_monthly_surface_2016_2017 {\n", "dimensions:\n", " \tdepth = 1 ;\n", " \tlatitude = 681 ;\n", " \tlongitude = 1440 ;\n", " \ttime = UNLIMITED ; // (24 currently)\n", "variables:\n", " \tfloat depth(depth) ;\n", "\t\tdepth:valid_min = 0.50576f ;\n", "\t\tdepth:valid_max = 5902.058f ;\n", "\t\tdepth:units = \"m\" ;\n", "\t\tdepth:positive = \"down\" ;\n", "\t\tdepth:unit_long = \"Meters\" ;\n", "\t\tdepth:long_name = \"Depth\" ;\n", "\t\tdepth:standard_name = \"depth\" ;\n", "\t\tdepth:axis = \"Z\" ;\n", "\tfloat latitude(latitude) ;\n", "\t\tlatitude:valid_min = -80.f ;\n", "\t\tlatitude:valid_max = 90.f ;\n", "\t\tlatitude:step = 0.25f ;\n", "\t\tlatitude:units = \"degrees_north\" ;\n", "\t\tlatitude:unit_long = \"Degrees North\" ;\n", "\t\tlatitude:long_name = \"Latitude\" ;\n", "\t\tlatitude:standard_name = \"latitude\" ;\n", "\t\tlatitude:axis = \"Y\" ;\n", "\tfloat longitude(longitude) ;\n", "\t\tlongitude:valid_min = -180.f ;\n", "\t\tlongitude:valid_max = 179.75f ;\n", "\t\tlongitude:step = 0.25f ;\n", "\t\tlongitude:units = \"degrees_east\" ;\n", "\t\tlongitude:unit_long = \"Degrees East\" ;\n", "\t\tlongitude:long_name = \"Longitude\" ;\n", "\t\tlongitude:standard_name = \"longitude\" ;\n", "\t\tlongitude:axis = \"X\" ;\n", "\tfloat time(time) ;\n", "\t\ttime:axis = \"T\" ;\n", "\t\ttime:long_name = \"Time\" ;\n", "\t\ttime:standard_name = \"time\" ;\n", "\t\ttime:calendar = \"gregorian\" ;\n", "\t\ttime:units = \"days since 1950-01-01 00:00:00\" ;\n", "\t\ttime:cell_methods = \"time: mean\" ;\n", "\tfloat uo_foam(time, depth, latitude, longitude) ;\n", "\t\tuo_foam:long_name = \"Eastward velocity\" ;\n", "\t\tuo_foam:standard_name = \"eastward_sea_water_velocity\" ;\n", "\t\tuo_foam:units = \"m s-1\" ;\n", "\t\tuo_foam:unit_long = \"Meters per second\" ;\n", "\t\tuo_foam:_FillValue = 9.96921e+36f ;\n", "\t\tuo_foam:cell_methods = \"area: mean time: mean\" ;\n", "\t\tuo_foam:valid_min = -3.f ;\n", "\t\tuo_foam:valid_max = 3.f ;\n", "\tfloat vo_foam(time, depth, latitude, longitude) ;\n", "\t\tvo_foam:long_name = \"Northward velocity\" ;\n", "\t\tvo_foam:standard_name = \"northward_sea_water_velocity\" ;\n", "\t\tvo_foam:units = \"m s-1\" ;\n", "\t\tvo_foam:unit_long = \"Meters per second\" ;\n", "\t\tvo_foam:_FillValue = 9.96921e+36f ;\n", "\t\tvo_foam:cell_methods = \"area: mean time: mean\" ;\n", "\t\tvo_foam:valid_min = -3.f ;\n", "\t\tvo_foam:valid_max = 3.f ;\n", "// global attributes:\n", "\t\t:product = \"GLOBAL_REANALYSIS_PHY_001_031\" ;\n", "\t\t:producer = \"CMEMS - Global Monitoring and Forecasting Centre\" ;\n", "\t\t:area = \"Global\" ;\n", "\t\t:quality_information_document = \"http://marine.copernicus.eu/documents/QUID/CMEMS-GLO-QUID-001_031.pdf\" ;\n", "\t\t:Conventions = \"CF-1.6\" ;\n", "\t\t:credit = \"E.U. Copernicus Marine Service Information (CMEMS)\" ;\n", "\t\t:contact = \"servicedesk.cmems@mercator-ocean.eu\" ;\n", "\t\t:references = \"http://marine.copernicus.eu\" ;\n", "\t\t:licence = \"http://marine.copernicus.eu/services-portfolio/service-commitments-and-licence/\" ;\n", "\t\t:institution = \"Mercator Ocean\" ;\n", "\t\t:product_user_manual = \"http://marine.copernicus.eu/documents/PUM/CMEMS-GLO-PUM-001-031.pdf\" ;\n", "\t\t:title = \"Monthly mean fields for product GLOBAL_REANALYSIS_PHY_001_031\" ;\n", "\t\t:history = \"Tue Mar 9 08:11:13 2021: ncrcat grepv2_monthly_surface_201601.nc grepv2_monthly_surface_201602.nc grepv2_monthly_surface_201603.nc grepv2_monthly_surface_201604.nc grepv2_monthly_surface_201605.nc grepv2_monthly_surface_201606.nc grepv2_monthly_surface_201607.nc grepv2_monthly_surface_201608.nc grepv2_monthly_surface_201609.nc grepv2_monthly_surface_201610.nc grepv2_monthly_surface_201611.nc grepv2_monthly_surface_201612.nc grepv2_monthly_surface_201701.nc grepv2_monthly_surface_201702.nc grepv2_monthly_surface_201703.nc grepv2_monthly_surface_201704.nc grepv2_monthly_surface_201705.nc grepv2_monthly_surface_201706.nc grepv2_monthly_surface_201707.nc grepv2_monthly_surface_201708.nc grepv2_monthly_surface_201709.nc grepv2_monthly_surface_201710.nc grepv2_monthly_surface_201711.nc grepv2_monthly_surface_201712.nc grepv2_monthly_surface_2016_2017.nc\\n\",\n", "\t\t\t\"Tue Mar 9 08:07:09 2021: ncks -v vo_foam,uo_foam -d depth,0,0 /data/thaumus2/scratch/jcl/CMEMS_global_phy_reanalysis_1_4_deg/ftp/monthly/all/grepv2_monthly_201601.nc ./grepv2_monthly_surface_201601.nc\\n\",\n", "\t\t\t\"Creation 2019-Jan-16 08:00:00 GMT+0200\" ;\n", "\t\t:dataset = \"global-reanalysis-phy-001-031-grepv2-monthly\" ;\n", "\t\t:source = \"Copernicus Marine Service\" ;\n", "\t\t:NCO = \"4.6.8\" ;\n", "\t\t:nco_openmp_thread_number = 1 ;\n", "}\n", "```\n", "
\n", "\n", "Example files for ROMS and FVCOM, which are used in PyLag's [tutorial examples](../examples/index.ipynb), can be [downloaded here](https://drive.google.com/open?id=15UX7Y9JnuLpnPAz700mzmzd917nTClxR). You will see the header information for the different types of input data varies considerably. For the most part, PyLag deals with this variation internally, or through run configuration settings.\n", "\n", "### The grid metrics file\n", "\n", "The second input requirement is a grid metrics file in NetCDF format. It is required for all runs involving 2D or 3D spatial data. Within it are a set of variables describing an unstructured triangular mesh which has been constructed from the underlying grid. In the case of FVCOM, which already employs an unstructured grid, the grid metrics file saves variables describing the same grid, but with node and neighbour elements reordered to match PyLag's requirements. For regular grids, a new unstructured grid is created from scratch.\n", "\n", "The grid metrics is a requirement as it saves on having to compute the same information at the start of each run. It provides all the information PyLag needs to correctly read in and interpret the gridded input data. Special functions are provided in the module [`pylag.grid_metrics`](../api/pylag.grid_metrics.rst) which can be used to create grid metrics files that are specific to the type of input data being used. As an example, a grid metrics file for the above CMEMS data can be created so:\n", "\n", "```python\n", ">>> import pylag\n", ">>> pylag.grid_metrics.create_arakawa_a_grid_metrics_file('./grepv2_monthly_surface_2016_2017.nc', reference_var_name='uo_foam', is_global=True, surface_only=True)\n", "```\n", "\n", "A full explanation of each argument can be found in the [module documentation](../api/pylag.grid_metrics.rst). The above function will generate a file called `grid_metrics.nc`. The corresponding NetCDF header is:\n", "\n", "
\n", "NetCDF header for a PyLag grid metrics file constructed from CMEMS input data\n", "
\n", "```\n", "netcdf grepv2_grid_metrics_surface_only {\n", "dimensions:\n", "\tthree = 3 ;\n", "\tlongitude = 1440 ;\n", "\tlatitude = 680 ;\n", "\tnode = 979200 ;\n", "\telement = 1958396 ;\n", "variables:\n", "\tdouble longitude(node) ;\n", "\t\tlongitude:units = \"degrees_east\" ;\n", "\t\tlongitude:standard_name = \"longitude\" ;\n", "\t\tlongitude:long_name = \"Longitude\" ;\n", "\tdouble longitude_c(element) ;\n", "\t\tlongitude_c:units = \"degrees_east\" ;\n", "\t\tlongitude_c:standard_name = \"longitude\" ;\n", "\t\tlongitude_c:long_name = \"Longitude\" ;\n", "\tdouble latitude(node) ;\n", "\t\tlatitude:units = \"degrees_north\" ;\n", "\t\tlatitude:standard_name = \"latitude\" ;\n", "\t\tlatitude:long_name = \"Latitude\" ;\n", "\tdouble latitude_c(element) ;\n", "\t\tlatitude_c:units = \"degrees_north\" ;\n", "\t\tlatitude_c:standard_name = \"latitude\" ;\n", "\t\tlatitude_c:long_name = \"Latitude\" ;\n", "\tint64 trim_first_latitude ;\n", "\t\ttrim_first_latitude:long_name = \"0 - no, 1 - yes\" ;\n", "\tint64 trim_last_latitude ;\n", "\t\ttrim_last_latitude:long_name = \"0 - no, 1 - yes\" ;\n", "\tint64 permutation(node) ;\n", "\t\tpermutation:long_name = \"node permutation\" ;\n", "\tint64 nv(three, element) ;\n", "\t\tnv:long_name = \"nodes surrounding each element\" ;\n", "\tint64 nbe(three, element) ;\n", "\t\tnbe:long_name = \"elements surrounding each element\" ;\n", "\tint64 mask_c(element) ;\n", "\t\tmask_c:standard_name = \"sea_binary_mask\" ;\n", "\t\tmask_c:units = \"1\" ;\n", "\t\tmask_c:long_name = \"Land-sea mask: sea = 0, land = 1, boundary element = 2\" ;\n", "\tint64 mask(node) ;\n", "\t\tmask:standard_name = \"sea_binary_mask\" ;\n", "\t\tmask:units = \"1\" ;\n", "\t\tmask:long_name = \"Land-sea mask: sea = 0, land = 1\" ;\n", "\tdouble area(element) ;\n", "\t\tarea:standard_name = \"areas\" ;\n", "\t\tarea:units = \"m^2\" ;\n", "\t\tarea:long_name = \"Element areas\" ;\n", "\n", "// global attributes:\n", "\t\t:Conventions = \"CF-1.7\" ;\n", "\t\t:title = \"PyLag grid metrics file\" ;\n", "\t\t:institution = \"Plymouth Marine Laboratory (PML)\" ;\n", "\t\t:contact = \"James R. Clark (jcl@pml.ac.uk)\" ;\n", "\t\t:netcdf-version-id = \"netCDF-4\" ;\n", "\t\t:pylag-version-id = \"6a56a34d0649e2c029f5d38584548c2ea01eeb1f\" ;\n", "\t\t:is_global = \"True\" ;\n", "}\n", "```\n", "
\n", "\n", "Most of the variables are self explanatory, given the variable long names. Possible exceptions are the variables `trim_first_latitude` and `trim_last_latitude`. These are binary flags, which indicate whether the first and/or last latitude points should be trimmed when PyLag reads input data from file. They are included as global data products are sometimes interpolated onto a regular grid which includes a row of points lying directly over one or both poles. On a spherical Earth, all these points refer to the same location, and the row is frequently masked. To prevent problems associated with handling such points, PyLag will trim them if they exist. These flags indicate whether this has happened or not. Other variables of note are `perturbation`, gives the order of nodes in the grid. It is used to sort input arrays so that data points are correctly matched to nodes that make up the unstructured grid. Lastly, the `_c` name qualifier is used to flag variables specific to element centres (as opposed to element nodes).\n", "\n", "### The initial positions file\n", "\n", "*PyLag* must be given the initial positions of particles at the start of each new simulation. When running *PyLag* from the command line, particle initial positions can be specified in one of two ways. In the first approach, particle initial positions are read in from a text file with a specified format, as outlined below. In the second approach, particle initial positions are read from a restart file which has been created at the end of or during a previous simulation. The choice is specified in the run configuration file. \n", "\n", "Initial position text files must have the following format:\n", "\n", "```\n", "n\n", "group_id x1 x2 x3\n", "group_id x1 x2 x3\n", "...\n", "```\n", "\n", "The entries have the following meaning:\n", "\n", "* **n** is the total number of particles. It must always be the first entry in the file.\n", "* **group_id** is an integer number that can be used to group particles. This can be useful if, say, you want to look at a group of particles that started off from a similar location. It does not affect particle dynamics. It is recorded in the simulation output files.\n", "* **x1** is the particle's first position coordinate. In a cartesian coordinate system, this should be *x* in meters. In a geographic coordinates, it should be the particle's longitude in degrees east.\n", "* **x2** is the particle's second position coordinate. In a cartesian coordinate system, this should be *y* in meters. In a geographic coordinates, it should be the particle's latitude in degrees north.\n", "* **x3** is the particle's third position coordinate. This is always the particle's depth, *z*, in meters. *z* can be given relative to the moving free surface or the sea floor. The choice is set in the run configuration file using the option `depth_coordinates`. Depth is positive up. Thus, if `depth_coordinates` is set to `depth_below_surface`, a depth, $z$, of -0.1 would specify a starting *z* position 0.1 m below the free surface. The model will interpolate the free surface height to the particle's position in time and space, so you don't need to worry about what the sea surface height is at a particlular point in time (unless you set a starting depth that lies below the sea floor). There is also an option to start particles off from a specified distance above the sea floor.\n", "\n", "For example, an initial positions file, `initial_positions.dat`, for a simulation involving two particles with the same group ID, whose lateral coordinates are given in degrees and initial vertical coordinates are coincident with the free surface, might look like:\n", "\n", "```\n", "2\n", "1 -4.17 50.0 0.0\n", "1 -4.17 50.1 0.0\n", "```\n", "\n", "For simulations involving tens of particles or more, the initial positions file is most easily [created programatically](./cookbook/initial_positions.ipynb).\n", "\n", "\n", "### The run configuration file\n", "\n", "The final input required by PyLag is the run configuration file, where all settings for a given run are specified. Example run configuration files for each of the different types of input data that PyLag works with have been provided in the [resources directory of the code repository](https://github.com/pmlmodelling/pylag/tree/master/resources). They can simply be downloaded and adapted to specific use cases. The template file for running with CMEMS like data on an Arakawa A-grid is given below. The file contains a detailed set of comments for each setting.\n", "\n", "
\n", "Template run configuration file for CMEMS like data\n", "
\n", "```\n", "[GENERAL]\n", "# Logging\n", "log_level = INFO\n", "\n", "# Directory containing input files\n", "in_dir = ./input\n", "\n", "# Directory in which simulation output will be saved\n", "out_dir = ./output\n", "\n", "# Name of the netCDF data file to be created (without the nc extension)\n", "output_file = %(out_dir)s/pylag\n", "\n", "[SIMULATION]\n", "# Simulation type\n", "simulation_type = trace\n", "\n", "# Initialisation method\n", "# : init_file: Initialise particle state data from an ascii file. The\n", "# name of the file is given by the parameter `initial_positions_file`.\n", "# : restart_file: Initialise particle state data from a restart file. The\n", "# name of the restart file is given by the parameter `restart_file_name`\n", "# in section `RESTART`.\n", "# : rectangular_grid: Initialise particle state data by creating a set\n", "# of particles on a regular rectangular grid. (NOT IMPLEMENTED)\n", "initialisation_method = init_file\n", "\n", "# Initial positions data file\n", "initial_positions_file = ./input/initial_positions.dat\n", "\n", "# Flag for surface only transport. If set to True, PyLag will only read\n", "# surface fields. In this case, initial vertical positions should be\n", "# set to 0.0 m below the free surface. Depth restoring should be set to\n", "# False for efficiency reasons.\n", "surface_only = False\n", "\n", "# The coordiate system. Options include cartesian (x, y) and geographic (lat, lon)\n", "# coordinate systems. The choice should reflect the grid on which the underlying\n", "# input data (e.g. u, v velocity components) are defined. PyLag will adopt the\n", "# same coordinate system for particle positions. This choice does not impact\n", "# the vertical coordinate system, where at the current time, regular (z) depth\n", "# levels are assumed. Note that some models such as FVCOM can output particle\n", "# coordinates in both cartesian (x, y) and geographic (lat, lon) coordinates.\n", "# In these cases, and in paricular for small domains where grid distortions\n", "# due to the projection are small, it is generally faster and better to use\n", "# cartesian coordinates.\n", "# : cartesian - Cartesian (x, y) coordinates.\n", "# : geographic - Geographic (lat, lon) coordinates.\n", "coordinate_system = geographic\n", "\n", "# Depth coordinates\n", "# : depth_below_surface: Starting depth is given as the depth below the \n", "# (moving) free surface in meters. Positive up, meaning a starting depth\n", "# of -0.1 is 0.1 m below the free surface. NB A starting depth of 0.1 would\n", "# be above the free surface and flagged as an error.\n", "# : hieght_above_bottom: Depth is given as the height above the sea floor\n", "# in meters. Positive up, meaning a starting depth of 0.1 is 0.1 m above\n", "# the sea floor.\n", "depth_coordinates = depth_below_surface\n", "\n", "# Keep particles at a fixed depth below the surface by restoring to a fixed depth each time step\n", "depth_restoring = False\n", "\n", "# The fixed depth below the surface that particles are held at if `depth_restoring' is True. A value\n", "# 0f 0.0 corresponds to the sea surface; a value of -1.0 to 1m below the free surface.\n", "fixed_depth = 0.0\n", "\n", "# The time and date at which the first set of particles is released. The format is: yyyy-mm-dd hh:mm:ss\n", "start_datetime = 2016-01-12 00:00:00\n", "\n", "# Simulation end time - only used when running a single particle release\n", "end_datetime = 2016-03-12 00:00:00\n", "\n", "# Time direction\n", "# : forward: Forward in time integration\n", "# : reverse: Backward in time integration\n", "time_direction = forward\n", "\n", "# Number of particle releases\n", "number_of_particle_releases = 1\n", "\n", "# Number of hours between particle releases\n", "particle_release_interval_in_hours = 1.0\n", "\n", "# Simulation duration - used to compute simulation end times with multiple particle releases\n", "duration_in_days = 0.5\n", "\n", "# Period at which output data should be saved (s)\n", "output_frequency = 900.0\n", "\n", "# Period at which output data is synced to disk (s)\n", "sync_frequency = 900.0\n", "\n", "[RESTART]\n", "# The name of the restart file that will be used to initialise the model if\n", "# initialisation_method == restart_file\n", "restart_file_name = ./restart.nc\n", "\n", "# Create restart files?\n", "create_restarts = True\n", "\n", "# The directory in which restart files will be created. Full or relative path.\n", "restart_dir = ./restart\n", "\n", "# Period at which restart files will be created (s)\n", "restart_frequency = 3600.0\n", "\n", "[OCEAN_DATA]\n", "# Name of the ocean circulation model or data source from which velocity data\n", "# have been generated. Supported options include:\n", "# : ArakawaA: Model outputs on an Arakawa-a grid with CF compliant variable names\n", "# : FVCOM: The Finite Volume Community Ocean Model\n", "# : GOTM: The General Ocean Turbulence Model\n", "name = ArakawaA\n", "\n", "# Directory containing model output files\n", "data_dir = /data/arakawa_a\n", "\n", "# File containing grid info, in particular the adjacency. If not given, this\n", "# data is extracted from the first data file, which will increase run times. \n", "# The full path is required.\n", "grid_metrics_file = %(data_dir)s/grid_metrics.nc\n", "\n", "# Data file name stem (e.g. \"data_\"). Files should be stored at the top level of\n", "# `data_dir'. The model will automatically look for and concatenate across files\n", "# whose names begin with this string (e.g. data_0001.nc, data_0002.nc etc etc). \n", "# If a grid metrics file is given make sure its file name does not match\n", "# data_file_stem, otherwise the model will attempt to read this too.\n", "data_file_stem = data_\n", "\n", "# Rounding interval (s) used for rounding datetime objects constructed from the\n", "# model time variable, which may have been written to file with only limited\n", "# numerical precision. e.g. a rounding interval of 3600s will round\n", "# times to the nearest hour.\n", "rounding_interval = 3600\n", "\n", "# Constant value for the horizontal eddy diffusivity (units: m^2/s). This value is\n", "# only used with the iterative method `Diff_Const_2D'. See section `NUMERICS'.\n", "horizontal_eddy_diffusivity_constant = 10.0\n", "\n", "# Dimension names\n", "# ---------------\n", "\n", "# Time dimension\n", "time_dim_name = time\n", "\n", "# Depth dimension name\n", "depth_dim_name = depth\n", "\n", "# Latitude dimension name\n", "latitude_dim_name = latitude\n", "\n", "# Longitude dimension name\n", "longitude_dim_name = longitude\n", "\n", "# Variable names\n", "# --------------\n", "\n", "# Time (mandatory)\n", "time_var_name = time\n", "\n", "# u-velocity component (mandatory)\n", "uo_var_name = uo_foam\n", "\n", "# v-velocity component (mandatory)\n", "vo_var_name = vo_foam\n", "\n", "# w-velocity component (leave blank or comment if not included)\n", "wo_var_name =\n", "\n", "# Sea surface elevation (leave blank or comment if not included)\n", "zos_var_name =\n", "\n", "# Temperature (leave blank or comment if not included)\n", "thetao_var_name =\n", "\n", "# Salinity (leave blank or comment if not included)\n", "so_var_name =\n", "\n", "# Does the mask change with wetting and drying?\n", "has_is_wet = False\n", "\n", "# Options for vertical eddy diffusivity\n", "# -------------------------------------\n", "\n", "# Method used to calculate the vertical eddy diffusivity (Kz). NB values are case insensitive.\n", "# : none - Kz cannot be retrieved or calculated from the data set.\n", "# : file - Kz is read in from file. Users must provide a value for `Kz_var_name`.\n", "Kz_method = none\n", "\n", "# Vertical eddy diffusivity variable name (leave blank or comment if `Kz_method` is `none`)\n", "Kz_var_name =\n", "\n", "# Options for horizontal eddy diffusivity\n", "# ---------------------------------------\n", "\n", "# Method used to calculate the horizontal eddy diffusivity (Ah). NB values are case insensitive.\n", "# : none - Ah cannot be retrieved or calculated from the data set. Setting this value\n", "# to none does not preclude the use of a constant value for Ah. This is viewed\n", "# as being a property of the numerical scheme, and is set in the `NUMERICS`\n", "# section of the config.\n", "# : smagorinsky - Compute Ah using Smagorinsky formulation. Parameters for the Smagorinksy\n", "# relationship should be set in the section [SMAGORINSKY].\n", "# : file - Ah is read in from file. With this option users must provide a value for `Ah_var_name`.\n", "Ah_method = none\n", "\n", "# Horizontal eddy diffusivity variable name (leave blank or comment if `Ah_method` is `none`)\n", "Ah_var_name =\n", "\n", "# Interpolation scheme used when computing the vertical eddy diffusivity. At\n", "# present, this option is only supported by GOTM. If set when working with\n", "# FVCOM model outputs, it will have absolutely no effect on the interpolation\n", "# scheme used. See PyLag's documentation for more details.\n", "# linear - Linear interpolation\n", "# cubic_spline = Cubic spline interpolation\n", "# vertical_interpolation_scheme = cubic_spline\n", "\n", "[SMAGORINSKY]\n", "# Constant to use with the Smagoriksy estimate of horizontal eddy diffusivities.\n", "constant = 0.2\n", "\n", "[NUMERICS]\n", "# The numerical method used to compute changes in particle positions. This option\n", "# controls whether operator splitting is used to combine the contributions of\n", "# advection and diffusion.\n", "# standard - The iterative method is set through the option `iterative_method'.\n", "# The specified iterative method may correspond to cases of pure\n", "# advection, pure diffusion or both. In the case of both advection\n", "# and diffusion, operator splitting is not performed; rather, the effects\n", "# of both processes are computed at the same time using the same time step\n", "# and using the specified iterative method. StdNumMethod objects require no\n", "# knowledge or the type of iterative method being used; they simply\n", "# use it compute the change in a particle's position.\n", "# operator_split_0 - A form of operator splitting in which the advection step is\n", "# performed first followed by the diffusion step. The iterative \n", "# methods used for the advection and diffusion steps are set through\n", "# the options `adv_iterative_method' and `diff_iterative_method' \n", "# respectively. The two processes can use different time steps; these\n", "# are set through the parameters `time_step_adv' and `time_step_diff'\n", "# respectively. `time_step_adv' must be greater than or equal to\n", "# `time_step_diff' and `time_step_adv'%`time_step_diff' must equal 0.\n", "# An exception will be raised if either of these conditions is not\n", "# met.\n", "# operator_split_1 - A form of operator splitting in which a half step for diffusion \n", "# is performed first followed by a full advection step followed\n", "# by a half diffusion step. The iterative methods used for the advection\n", "# and diffusion steps are set through the options `adv_iterative_method'\n", "# and `det_iterative_method' respectively. The two processes use different\n", "# time steps; these are set through the parameters `time_step_adv' and\n", "# `time_step_diff' respectively. `time_step_adv' must be exactly equal to\n", "# 2 * `time_step_diff'. An exception will be raised if this condition is not\n", "# met.\n", "num_method = standard\n", "\n", "# The iterative method used to simulate pure advection, pure diffusion or both combined\n", "# (in the absence of operator splitting). For deterministic methods that solve for advection\n", "# only, \"Adv\" is appended to the beginning of the name. For stochastic methods that solve for\n", "# diffusion only, \"Diff\" is appended to the beginning of the name. Lastly, for methods that do\n", "# both advection and diffusion, \"AdvDiff\" is appended to the beginning of the name. The\n", "# dimensionality of each scheme is implicit within the name. 1D schemes compute changes\n", "# in position in e_k only; 2D schemes in e_i and e_j only; and 3D scehemes in e_i, e_j and e_k.\n", "# Adv_RK4_2D - 2D fourth order Runge-Kutta (uses horizontal velocities only)\n", "# Adv_RK4_3D - 3D fourth order Runge-Kutta (uses horizontal and vertical velocities)\n", "# Diff_Const_2D - 2D method that uses a constant horizontal eddy diffusivity. The constant\n", "# is set using the parameter `horizontal_eddy_diffusivity_constant'\n", "# in the section OCEAN_DATA.\n", "# Diff_Naive_[1,2]D - 1- or 2-D Naive scheme; only suitable for homogeneous diffusivity/\n", "# diffusivity fields.\n", "# Diff_Euler_1D - 1D Euler sceheme which includes a pseudo velocity correction term for \n", "# inhomogeneous diffusivity fields. The sceheme converges with\n", "# delta t and sqrt(delta t) in the weak and strong sense respectively.\n", "# Diff_Visser_1D - 1D Visser scheme which includes a pseudo velocity correction for \n", "# inhomgeneous diffusivity fields. Diffusivities are evaluated at a z \n", "# position offset from Z_n. The scheme converges with delta t and \n", "# sqrt(delta t) in the weak and strong sense respectively.\n", "# Diff_Milstein_[1,2,3]D - 1-, 2- or 3-D Milstein schemes that converge with delta t in both the\n", "# strong and the weak sense.\n", "# AdvDiff_Milstein_3D - 3D Milstein scheme that converges with delta t in both the strong and the\n", "# weak sense.\n", "iterative_method = Adv_RK4_3D\n", "\n", "# The iterative method used for advection when operator splitting is used:\n", "adv_iterative_method = Adv_RK4_3D\n", "\n", "# The iterative method used for diffusion when operator splitting is used:\n", "diff_iterative_method = Diff_Milstein_3D\n", "\n", "# The time step used by iterative methods that deal with advection only (s)\n", "time_step_adv = 100\n", "\n", "# The time step used by iterative methods that deal with either diffusion only\n", "# or advection and diffusion combined (s).\n", "time_step_diff = 1\n", "\n", "[BOUNDARY_CONDITIONS]\n", "\n", "# Horizontal boundary condition calculator\n", "# NB These are specific to the coordinate system (cartesian or geographic) in which\n", "# the model is run.\n", "# None - Run without a horizontal boundary condition calculator. This will only\n", "# work successfully if there are no land boundaries, or if the setup is such that\n", "# horizontal boundary crossings are impossible. If neither of these are true,\n", "# and this option is set to `None', an exception will be raised.\n", "# restoring - Restore the particle to its last known good position.\n", "# reflecting - Apply reflecting horizontal boundary conditions\n", "horiz_bound_cond = restoring\n", "\n", "# Vertical boundary condition calculator\n", "# None - Run without a vertical boundary condition calculator. It is okay to set\n", "# this to `None' if it is possible to guarantee a vertical boundadry will not be\n", "# crossed (e.g. if the input data is 2D). An exception will be raised if a vertical\n", "# boundary is crossed and this option is set to `None'.\n", "# reflecting - Apply reflecting vertical boundary conditions\n", "vert_bound_cond = reflecting\n", "\n", "[OUTPUT]\n", "\n", "# List of environmental variables to be saved to file along with particle data.\n", "# This facility allows one to analyse changes in a given environmental variable\n", "# (e.g. temperature) along a particle's pathline. Values are output along with\n", "# particle position data. For now, support for the following environmental\n", "# variables exists:\n", "#\n", "# ArakawaA\n", "# --------\n", "# thetao - Sea water potential temperature\n", "# so - Salinity\n", "#\n", "# FVCOM\n", "# -----\n", "# thetao - Sea water potential temperature\n", "# so - Salinity\n", "#\n", "# GOTM\n", "# ----\n", "# N/A\n", "#\n", "# Variables should be given as a comma separated list.\n", "#environmental_variables = thetao, so\n", "```\n", "
\n", "\n", "## Step 2: Running PyLag\n", "\n", "With PyLag installed and all required inputs generated, you can start a new simulation. PyLag can be run in serial or parallel modes. A simulation can be run in serial using the following commands:\n", "\n", "```bash\n", "\n", "$ python -m pylag.main -c pylag.cfg\n", "\n", "```\n", "\n", "where `pylag.cfg` is the name of the run configuration file.\n", "\n", "To launch a parallel run, simply type:\n", "\n", "```bash\n", "\n", "$ mpiexec -np n_proc python -m pylag.parallel.main -c pylag.cfg\n", "\n", "```\n", "\n", "where `n_proc` is the number of processors the run will be distributed over.\n", "\n", "
\n", "\n", "**Note:**\n", "\n", "For the time being, the number of processors used must be an exact divisor of the total number of particles. If this is not the case, an error will be raised and the simulation halted.\n", "\n", "
\n", "\n", "If the model run completed successfully, a set of outputs will have been saved in the specified output directory.\n", "\n", "\n", "## Step3: Analysing simulation outputs\n", "\n", "The [pylag.processing](../api/pylag.processing.rst) sub-package provides a number of tools to assist with analysing simulation outputs. Examples of their usage can be found in the [tutorial examples](../examples/index.rst)." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.9.7" } }, "nbformat": 4, "nbformat_minor": 4 }