Miscellaneous#

parcels.rng module#

parcels.rng.expovariate(lamb)[source]#: Returns a random float of an exponential distribution with parameter lamb.

parcels.rng.normalvariate(loc, scale)[source]#: Returns a random float on normal distribution with mean loc and width scale.

parcels.rng.randint(low, high)[source]#: Returns a random int between low and high.

parcels.rng.random()[source]#: Returns a random float between 0.0 and 1.0.

parcels.rng.seed(seed)[source]#: Sets the seed for parcels internal RNG.

parcels.rng.uniform(low, high)[source]#: Returns a random float between low and high.

parcels.rng.vonmisesvariate(mu, kappa)[source]#: Returns a random float of a Von Mises distribution with mean angle mu and concentration parameter kappa.

parcels.tools.statuscodes module#

Handling of Errors and particle status codes

exception parcels.tools.statuscodes.FieldOutOfBoundError(x, y, z, field=None)[source]#

Bases: RuntimeError

Utility error class to propagate out-of-bound field sampling.

exception parcels.tools.statuscodes.FieldSamplingError(x, y, z, field=None)[source]#

Bases: RuntimeError

Utility error class to propagate erroneous field sampling.

exception parcels.tools.statuscodes.KernelError(particle, fieldset=None, msg=None)[source]#

Bases: RuntimeError

General particle kernel error with optional custom message.

class parcels.tools.statuscodes.StatusCode[source]#

Bases: object

Class defining the status codes for particles.state.

exception parcels.tools.statuscodes.TimeExtrapolationError(time, field=None, msg='allow_time_extrapoltion')[source]#

Bases: RuntimeError

Utility error class to propagate erroneous time extrapolation sampling.

parcels.tools.converters module#

class parcels.tools.converters.Geographic[source]#

Bases: UnitConverter

Unit converter from geometric to geographic coordinates (m to degree)

Methods

ccode_to_source
ccode_to_target
to_source
to_target

class parcels.tools.converters.GeographicPolar[source]#

Bases: UnitConverter

Unit converter from geometric to geographic coordinates (m to degree) with a correction to account for narrower grid cells closer to the poles.

Methods

ccode_to_source
ccode_to_target
to_source
to_target

class parcels.tools.converters.GeographicPolarSquare[source]#

Bases: UnitConverter

Square distance converter from geometric to geographic coordinates (m2 to degree2) with a correction to account for narrower grid cells closer to the poles.

Methods

ccode_to_source
ccode_to_target
to_source
to_target

class parcels.tools.converters.GeographicSquare[source]#

Bases: UnitConverter

Square distance converter from geometric to geographic coordinates (m2 to degree2)

Methods

ccode_to_source
ccode_to_target
to_source
to_target

class parcels.tools.converters.TimeConverter(time_origin=0)[source]#

Bases: object

Converter class for dates with different calendars in FieldSets

Parameters: time_origin (float, integer, numpy.datetime64 or netcdftime.DatetimeNoLeap) – time origin of the class.

Methods

`fulltime`(time)	Method to convert a time difference in seconds to a date, based on the time_origin
`reltime`(time)	Method to compute the difference, in seconds, between a time and the time_origin of the TimeConverter

fulltime(time)[source]#

Method to convert a time difference in seconds to a date, based on the time_origin

Parameters: time –
Returns: self.time_origin + time
Return type: type

reltime(time)[source]#

Method to compute the difference, in seconds, between a time and the time_origin of the TimeConverter

Parameters: time –
Returns: time - self.time_origin
Return type: type

class parcels.tools.converters.UnitConverter[source]#

Bases: object

Interface class for spatial unit conversion during field sampling that performs no conversion.

Attributes

source_unit
target_unit

Methods

ccode_to_source
ccode_to_target
to_source
to_target

parcels.tools.converters.convert_to_flat_array(var)[source]#

Convert lists and single integers/floats to one-dimensional numpy arrays

Parameters: var (np.ndarray, float or array_like) – list or numeric to convert to a one-dimensional numpy array

parcels.tools.converters.convert_xarray_time_units(ds, time)[source]#: Fixes DataArrays that have time.Unit instead of expected time.units

parcels.tools.loggers module#

Script to create a logger for Parcels.

class parcels.tools.loggers.XarrayDecodedFilter(name='')[source]#

Filters the warning_once from fieldfilebuffer when cf_decoding fails.

Methods

filter(record)

Determine if the specified record is to be logged.

filter(record)[source]#

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

parcels.tools.exampledata_utils module#

parcels.tools.exampledata_utils.download_example_dataset(dataset: str, data_home=None)[source]#

Load an example dataset from the parcels website.

This function provides quick access to a small number of example datasets that are useful in documentation and testing in parcels.

Parameters

dataset (str) – Name of the dataset to load.
data_home (pathlike, optional) – The directory in which to cache data. If not specified, the value of the PARCELS_EXAMPLE_DATA environment variable, if any, is used. Otherwise the default location is assigned by get_data_home().

Returns

dataset_folder – Path to the folder containing the downloaded dataset files.

Return type

Path

parcels.tools.exampledata_utils.get_data_home(data_home=None)[source]#

Return a path to the cache directory for example datasets.

This directory is used by load_dataset().

If the data_home argument is not provided, it will use a directory specified by the PARCELS_EXAMPLE_DATA environment variable (if it exists) or otherwise default to an OS-appropriate user cache location.

parcels.tools.exampledata_utils.list_example_datasets() → List[str][source]#

List the available example datasets.

Use download_example_dataset() to download one of the datasets.

Returns: datasets – The names of the available example datasets.
Return type: list of str