PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

Module drifters_mod

Contact:  Alexander Pletzer
Reviewers: 
Change History: WebCVS Log

OVERVIEW

Drifters are idealized point particles with positions that evolve in time according to a prescribed velocity field, starting from some initial conditions. Drifters have no mass, no energy, no size, and no friction and therefore have no impact on the dynamics of the underlying system. The only feature that distinguishes a drifter from another is its trajectory. This makes drifters ideal for tracking pollution clouds and probing fields (e.g. temperature, salinity) along ocean currents, to name a few applications. Drifters can mimic real experiments such as the Argo floats http://www.metoffice.com/research/ocean/argo/ukfloats.html.

When run in parallel, on a 2d decomposed domain, drifters_mod will handle all the bookkeeping and communication transparently for the user. This involves adding/removing drifters as they enter/leave a processor element (PE) domain. Note that the number of drifters can vary greatly both between PE domains and within a PE domain in the course of a simulation; the drifters' module will also manage dynamically the memory for the user.

There are a number of basic assumptions which could make the drifters' module ill-suited for some tasks. First and foremost, it is assumed that the motion of drifters is not erratic but follows deterministic trajectories. Furthermore, drifters should not cross both compute and data domain boundaries within less than a time step. This limitation is imposed by the Runge-Kutta integration scheme, which must be able to complete, within a time step, a trajectory calculation that starts inside the compute domain and ends inside the data domain. Therefore, the drifters, as they are presently modelled, are unlikely to work for very fast objects. This constraint also puts a upper limit to the domain decomposition, although it can often be remedied by increasing the number of ghost nodes.

Another fundamental assumption is that the (e.g. velocity) fields are structured, on a per PE domain basis. There is no support for locally nested or unstrucured meshes. Meshes need not be smooth and continuous across PE domains, however.

OTHER MODULES USED

               mpp_mod
       mpp_domains_mod
     drifters_core_mod
    drifters_input_mod
       drifters_io_mod
     drifters_comm_mod
cloud_interpolator_mod

PUBLIC INTERFACE

drifters_new:
Constructor.
drifters_del:
Destructor.
drifters_set_domain:
Set the compute, data, and global domain boundaries.
drifters_set_pe_neighbors:
Given an MPP based deomposition, set the PE numbers that are adjacent to this processor.
drifters_save:
Append new positions to NetCDF file.
drifters_distribute:
Distribute particles across PEs.
drifters_write_restart:
Write restart file.
drifters_set_v_axes:
Set velocity field axes.
drifters_set_domain_bounds:
Set boundaries of "data" and "compute" domains
drifters_positions2lonlat:
Interpolates positions onto longitude/latitude grid.
drifters_print_checksums:
Print Runge-Kutta check sums.

PUBLIC DATA

None.

PUBLIC ROUTINES

  1. drifters_new

    call drifters_new (self, input_file, output_file, ermesg)
    DESCRIPTION
    Will read positions stored in the netCDF file input_file. The trajectories will be saved in files output_file.PE, one file per PE domain.


    INPUT
    input_file    NetCDF input file name containing initial positions.
       [character, dimensionSCALAR]
    output_file    NetCDF output file. Will contain trajectory positions and interpolated fields.
       [character, dimensionSCALAR]

    INPUT/OUTPUT
    self    Opaque data structure.
       [drifters_type, dimensionSCALAR]

    OUTPUT
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

  2. drifters_del

    call drifters_del (self, ermesg)
    DESCRIPTION
    Call this to reclaim memory.


    INPUT/OUTPUT
    self    Opaque data structure.
       [drifters_type, dimensionSCALAR]

    OUTPUT
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

  3. drifters_set_domain

    call drifters_set_domain (self, & & xmin_comp, xmax_comp, ymin_comp, ymax_comp, & & xmin_data, xmax_data, ymin_data, ymax_data, & & xmin_glob, xmax_glob, ymin_glob, ymax_glob, & & ermesg)
    DESCRIPTION
    The data domain extends beyond the compute domain and is shared between two or more PE domains. A particle crossing the compute domain boundary will trigger a communication with one or more neighboring domains. A particle leaving the data domain will be removed from the list of particles.


    INPUT
    xmin_comp    Min of longitude-like axis on compute domain.
       [real, dimensionSCALAR]
    xmax_comp    Max of longitude-like axis on compute domain.
       [real, dimensionSCALAR]
    ymin_comp    Min of latitude-like axis on compute domain.
       [real, dimensionSCALAR]
    ymax_comp    Max of latitude-like axis on compute domain.
       [real, dimensionSCALAR]
    xmin_data    Min of longitude-like axis on data domain.
       [real, dimensionSCALAR]
    xmax_data    Max of longitude-like axis on data domain.
       [real, dimensionSCALAR]
    ymin_data    Min of latitude-like axis on data domain.
       [real, dimensionSCALAR]
    ymax_data    Max of latitude-like axis on data domain.
       [real, dimensionSCALAR]
    xmin_glob    Min of longitude-like axis on global domain.
       [real, dimensionSCALAR]
    xmax_glob    Max of longitude-like axis on global domain.
       [real, dimensionSCALAR]
    ymin_glob    Min of latitude-like axis on global domain.
       [real, dimensionSCALAR]
    ymax_glob    Max of latitude-like axis on global domain.
       [real, dimensionSCALAR]

    INPUT/OUTPUT
    self    Opaque data structure.
       [drifters_type, dimensionSCALAR]

    OUTPUT
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

  4. drifters_set_pe_neighbors

    call drifters_set_pe_neighbors (self, domain, ermesg)
    DESCRIPTION
    This will allow several PEs to track the trajectories of particles in the buffer regions.


    INPUT/OUTPUT
    self    Opaque data structure.
       [drifters_type, dimensionSCALAR]
    domain    MPP domain.
       [, dimensionSCALAR]

    OUTPUT
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

  5. drifters_save

    call drifters_save (self, ermesg)
    DESCRIPTION
    Use this method to append the new trajectory positions and the interpolated probe fields to a netCDF file.


    INPUT/OUTPUT
    self    Opaque daata structure.
       [drifters_type, dimensionSCALAR]

    OUTPUT
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

  6. drifters_distribute

    call drifters_distribute (self, ermesg)
    DESCRIPTION
    Use this method after setting the domain boundaries (drifters_set_domain) to spread the particles across PE domains.


    INPUT/OUTPUT
    self    Opaque handle.
       [drifters_type, dimensionSCALAR]

    OUTPUT
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

  7. drifters_write_restart

    call drifters_write_restart (self, filename, & & x1, y1, geolon1, & & x2, y2, geolat2, & & root, mycomm, ermesg)
    DESCRIPTION
    Gather all the particle positions distributed across PE domains on root PE and save the data in netCDF file.


    INPUT
    filename    Restart file name.
       [character, dimensionSCALAR]
    x1    Pseudo-longitude axis supporting longitudes.
       [real, dimension]
    x2    Pseudo-longitude axis supporting latitudes.
       [real, dimension]
    root    Root PE.
       [integer, dimensionSCALAR]
    mycomm    MPI communicator.
       [integer, dimensionSCALAR]

    INPUT/OUTPUT
    self    Opaque data structure.
       [drifters_type, dimensionSCALAR]
    y1    Pseudo-latitude axis supporting longitudes.
       [, dimension]
    geolon1    Longitude array (x1, y1).
       [, dimension]
    y2    Pseudo-latitude axis supporting latitudes.
       [, dimension]
    geolat2    Latitudes array (x2, y2)
       [, dimension]

    OUTPUT
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

  8. drifters_set_v_axes

    call drifters_set_v_axes (self, component, x, y, z, ermesg)
    DESCRIPTION
    Velocity axis components may be located on different grids or cell faces. For instance, zonal (u) and meridional (v) velcity components are staggered by half a cell size in Arakawa's C and D grids. This call will set individual axes for each components do as to allow interpolation of the velocity field on arbitrary positions.


    INPUT
    component    Velocity component: either 'u', 'v', or 'w'.
       [character, dimensionSCALAR]
    x    X-axis.
       [real, dimension]

    INPUT/OUTPUT
    self    Opaque data structure.
       [drifters_type, dimensionSCALAR]
    y    Y-axis.
       [, dimension]
    z    Z-axis.
       [, dimension]

    OUTPUT
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

  9. drifters_set_domain_bounds

    call drifters_set_domain_bounds (self, domain, backoff_x, backoff_y, ermesg)
    DESCRIPTION
    Each particle will be tracked sol long is it is located in the data domain.


    INPUT
    backoff_x    Data domain is reduced (if backoff_x > 0) by backoff_x nodes at east and west boundaries.
       [integer, dimensionSCALAR]
    backoff_y    Data domain is reduced (if backoff_y > 0) by backoff_y nodes at north and south boundaries.
       [integer, dimensionSCALAR]

    INPUT/OUTPUT
    self    Opaque data structure.
       [drifters_type, dimensionSCALAR]
    domain    Instance of Domain2D (see mpp_domain)
       [, dimensionSCALAR]

    OUTPUT
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

  10. drifters_positions2lonlat

    call drifters_positions2lonlat (self, positions, & & x1, y1, geolon1, & & x2, y2, geolat2, & & lons, lats, & & ermesg)
    DESCRIPTION
    In many cases, the integrated positions will not be longitudes or latitudes. This call can be ionvoked to recover the longitude/latitude positions from the "logical" positions.


    INPUT
    positions    Logical positions.
       [real, dimension]
    x1    X-axis of "geolon1" field.
       [real, dimension]
    x2    X-axis of "geolat2" field.
       [real, dimension]

    INPUT/OUTPUT
    self    Opaque data structure.
       [drifters_type, dimensionSCALAR]
    y1    Y-axis of "geolon1" field.
       [, dimension]
    geolon1    Longitude field as an array of (x1, y1).
       [, dimension]
    y2    Y-axis of "geolat2" field.
       [, dimension]
    geolat2    Latitude field as an array of (x2, y2)
       [, dimension]
    lats    Returned latitudes.
       [, dimension]

    OUTPUT
    lons    Returned longitudes.
       [real, dimension]
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

  11. drifters_print_checksums

    call drifters_print_checksums (self, pe, ermesg)
    DESCRIPTION
    Useful for debugging only.


    INPUT
    pe    Processor element.
       [integer, dimensionSCALAR]

    INPUT/OUTPUT
    self    Opaque handle.
       [drifters_type, dimensionSCALAR]

    OUTPUT
    ermesg    Error message (if any).
       [character, dimensionSCALAR]

DATA SETS

None.

ERROR MESSAGES

None.

REFERENCES


COMPILER SPECIFICS


PRECOMPILER OPTIONS


LOADER OPTIONS

TEST PROGRAM


KNOWN BUGS


NOTES

See NOTE above.

FUTURE PLANS


top