pylag.processing.release_zone module

A set of classes and functions to help with creating particle release zones.

class pylag.processing.release_zone.ReleaseZone(group_id=1, radius=100.0, centre=[0.0, 0.0])[source]

Bases: object

Release zone

A release zone is a circular region in cartesian space containing a set of particles.

Parameters

  • group_id (int) – Group ID associated with the release zone

  • radius (float) – The radius of the release zone in m.

  • centre (array_like) – Two element array giving the coordinates of the centre of the release zone.

add_particle(x, y, z)[source]

Add a particle to the release zone

Parameters

  • x (float) – x-coordinate

  • y (float) – y-coordinate

  • z (float) – z-coordinate

Return type

None

create_particle_set(n_particles=100, z=0.0, random=True)[source]

Create a new particle set

Create a new particle set (n=n_particles). The spatial coordinates of each particle are computed. If random is true, exactly n, random, uniformly distributed particles will be created. If false, particles are uniformly distributed on a cartesian grid, which is then filtered for the area encompassed by the release zone, which is determined from the radius. The latter algorithm yields a particle set with n <= n_particles where |n - n_particles| / n -> 1 for large n. The former guarantees that positions for exactly n particles are created. However, for small n the particle distribution with be patchy. All particles are created are given the same depth coordinates.

Parameters

  • n_particles (int, optional) – The number of particles to be created and added to the release zone.

  • z (float, optional) – The depth of the particles.

  • random (bool, optional) – If True (default) create particle positions at random. This guarantees that n_particles will be added to the release zone. If False, particles are regularly spaced on a Cartesian grid, which is then filtered for the area of the circle.

Return type

N/A

get_area()[source]

Get the area

Returns

The area of the release zone

Return type

float

get_centre()[source]

Get the central coordinates

Returns

Array of central coordinates [x, y].

Return type

array_list

get_coords()[source]

Get particle coordinates

Returns

  • array_like – Eastings

  • array_like – Northings

  • array_like – Depths

get_depths()[source]

Get depths

Returns

Depths

Return type

array_like

get_eastings()[source]
Returns

Eastings

Return type

array_like

get_group_id()[source]

Return the group ID

Returns

The group ID.

Return type

int

get_northings()[source]

Get northings

Returns

Northings

Return type

array_like

get_number_of_particles()[source]

Get the total number of particles

Returns

The total number of particles

Return type

int

get_particle_set()[source]

Get the particle set

Returns

List of tuples of particle coordinates

Return type

list[tuple]

get_radius()[source]

Get the radius

Returns

The radius of the relase zone

Return type

float

get_zone_polygon()[source]

Make a polygon of the points in the zone (based on its convex hull)

Returns

poly – Polygon

Return type

shapely.geometry.Polygon

set_group_id(id)[source]

Set the group ID

Parameters

id (int) – The group ID.

Return type

None

pylag.processing.release_zone.create_release_zone(group_id=1, radius=100.0, centre=[0.0, 0.0], n_particles=100, depth=0.0, random=True)[source]

Create a new release zone

Parameters

  • group_id (integer, optional) – Group identifier.

  • radius (float, optional) – Radius of the circle in meters.

  • centre (ndarray [float, float], optional) – x, y coordinates of the circle centre in meters.

  • n_particles (integer, optional) – The number of particles.

  • depth (float, optional) – Zone depth in m (default 0.0m).

  • random (boolean, optional) – Assign x/y positions randomly (default).

Returns

release_zone – ReleaseZone object.

Return type

ReleaseZone

pylag.processing.release_zone.create_release_zones_along_cord(r1, r2, group_id=1, radius=100.0, n_particles=100, depth=0.0, random=True, verbose=False)[source]

Generate a set of release zones along a cord

Return particle positions along a line r3, defined by the position vectors r1 and r2. Particles are packed into circlular zones of radius radius, running along r3. Positions for approximately n particles (= n if random is True) are returned per zone. If 2*radius is > |r3|, no zones are created.

Parameters

  • r1 (ndarray [float, float]) – Two component position vector in cartesian coordinates (x,y).

  • r2 (ndarray [float, float]) – Two component position vector in cartesian coordinates (x,y).

  • group_id (integer, optional) – Group id for the 1st release zone created along the cord.

  • radius (float, optional) – Zone radius in m.

  • n_particles (integer, optional) – Number of particles per zone.

  • depth (float, optional) – Zone depth in m.

  • random (boolean, optional) – If true create a random uniform distribution of particles within each zone (default).

  • verbose (boolean, optional) – Hide warnings and progress details (default).

Returns

zones – List of release zone objects along the cord.

Return type

object, iterable

pylag.processing.release_zone.create_release_zones_around_shape(shape_obj, start, target_length, group_id, radius, n_particles, depth=0.0, random=True, epsg_code=None, maximum_vertex_separation=None, return_end_zone=True, verbose=False, ax=None)[source]

Create a set of adjacent release zones around an arbitrary polygon.

Parameters

  • shape_obj (_Shape from module shapefile, np.ndarray) – Shapefile describing a given landmass or an array of points (n, 2) as (x, y).

  • start (tuple(float,float)) – Approximate starting point (lon,lat) in degrees

  • target_length (float) – Distance along which to position release zones

  • group_id (integer) – Group identifier.

  • radius (float) – Zone radius in m.

  • n_particles (integer) – Number of particles per zone.

  • depth (float, optional) – Zone depth in m.

  • random (boolean, optional) – If true create a random uniform distribution of particles within each zone (default).

  • epsg_code (str, optional) – EPSG code to which to force all coordinates. This is useful if you’ve got a large model domain.

  • maximum_vertex_separation (float, optional) – Skip sections of the shapefile which have a length in excess of this value. Helps skip parts of a domain which are very simple.

  • return_end_zone (bool, optional) – If False, do not return the last zone. Defaults to True (do return it). This is useful when chaining release zones along a shapefile with a fixed distance and we want to use the end of one chain as the start of another.

  • verbose (boolean, optional) – Hide warnings and progress details (default).

pylag.processing.release_zone.create_release_zones_around_shape_section(shape_obj, start, target_length, group_id, radius, n_particles, depth=0.0, epsg_code=None, random=True, check_overlaps=False, overlap_tol=0.0001, verbose=False)[source]

Create a set of adjacent release zones around a some part of an arbritray poloygon.

This function is distinct from the function create_release_zones_around_shape in the sense that it a) only creates release zones around a specified length of the polygon, and b) gives each release zone a separate individual ID tag.

Parameters

  • shape_obj (_Shape from module shapefile) – Shapefile describing a given landmass

  • start (tuple(float,float)) – Approximate starting point (lon,lat) in degrees

  • target_length (float) – Distance along which to position release zones

  • group_id (integer) – Group identifier.

  • radius (float) – Zone radius in m.

  • n_particles (integer) – Number of particles per zone.

  • depth (float) – Zone depth in m.

  • epsg_code (str, optional) – EPSG code within which to calculate lat/lon coordinates

  • random (boolean) – If true create a random uniform distribution of particles within each zone (default).

  • check_overlaps (boolean) – If true check for overlaps between non-adjacent release zones that may result from jagged features. NOT YET IMPLEMENTED.

  • overlap_tol (float) – Overlap tolerance, ratio ((target-act)/target < overlap_tol). Assists in avoiding false positives, which can arise from rounding issues.

  • verbose (boolean) – Hide warnings and progress details (default).

Todo

1) Allow users to provide a set of finish coordinates as an alternative to a length, which can then be used to determine the location of the last release zone to be created.