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[source]#

Bases: RuntimeError

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

exception parcels.tools.statuscodes.FieldSamplingError[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)[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: float | datetime64 | timedelta64 | datetime = 0)[source]#

Bases: object

Converter class for dates with different calendars in FieldSets

Parameters:

time_origin (float, integer, numpy.datetime64 or cftime.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: TimeConverter | datetime64 | timedelta64 | datetime) → float | ndarray[tuple[Any, ...], dtype[_ScalarT]][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: ArrayLike) → ndarray[tuple[Any, ...], dtype[_ScalarT]][source]#

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

Parameters:

var (Array) – 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.

parcels.tools.warnings module

exception parcels.tools.warnings.FieldSetWarning[source]#

Warning that is raised when there are issues in the construction of the FieldSet or its Grid.

These warnings are often caused by issues in the input data dimensions or options selected when loading data into a FieldSet.

exception parcels.tools.warnings.FileWarning[source]#

Warning that is raised when there are issues with input or output files.

These warnings can be related to file chunking, naming, or decoding issues. Chunking issues in particular may negatively impact performance (see also https://docs.oceanparcels.org/en/latest/examples/documentation_MPI.html#Chunking-the-FieldSet-with-dask)

exception parcels.tools.warnings.KernelWarning[source]#

Warning that is raised when there are issues with the Kernel.

These warnings often result from issues in the FieldSet or user-defined Kernel that are passed into the Parcels Kernel loop.

exception parcels.tools.warnings.ParticleSetWarning[source]#

Warning that is raised when there are issues in the construction of the ParticleSet.

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