seaduck.lagrangian

seaduck.lagrangian#

class seaduck.lagrangian.Particle(*arg, **kwarg)#

Bases: Position

Lagrangian particle object.

The Lagrangian particle object. Simply a eulerian Position object that know how to move itself.

Parameters:

  • kwarg (dict) – The keyword argument that feed into Position.from_latlon method

  • uname (str) – The variable names for the velocity/mass-transport components. If transport is true, pass in names of the volume/mass transport across cell wall in m^3/3 else, just pass something that is in m/s

  • vname (str) – The variable names for the velocity/mass-transport components. If transport is true, pass in names of the volume/mass transport across cell wall in m^3/3 else, just pass something that is in m/s

  • wname (str) – The variable names for the velocity/mass-transport components. If transport is true, pass in names of the volume/mass transport across cell wall in m^3/3 else, just pass something that is in m/s

  • free_surface (string) – Sometimes there is non-zero vertical velocity at sea surface. free_surface = “noflux” set that to zero. free_surface = “kick_back” move particles trying to cross back to the middle of the cell. There could be errors if neither is used.

  • save_raw (Boolean) – Whether to record the analytical history of all particles in an unstructured list.

  • transport (Boolean) – If transport is true, pass in names of the volume/mass transport across cell wall in m^3/3 else, just pass velocity that is in m/s

  • callback (function that take Particle as input) – A callback function that takes Particle as input. Return boolean array that determines which Particle should still be going. Users can also define customized functions here.

  • max_iteration (int) – The number of analytical steps allowed for the to_next_stop method.

analytical_step(tf)#

Integrate the particle with velocity.

The core method. A set of particles trying to integrate for time tf (could be negative). at the end of the call, every particle are either: 1. ended up somewhere within the cell after time tf. 2. ended up on a cell wall before (if tf is negative, then “after”) tf.

Parameters:

tf (float, numpy.ndarray) – The longest duration of the simulation for each particle.

cross_cell_wall(tend)#

Update properties after particles cross wall.

This function is called when particle reached the wall. The nearest grid points change as well as the way the package describe the location of particles. This method handles the handover of particles between grid points.

Parameters:

tend (numpy.ndarray of [0,1,2,3,4,5,6]) – Which neighboring cell to move into. 0-6 means left, right, down, up, deep, shallow, and stay in the current cell, respectively.

deepcopy()#

Return a clone of the object.

empty_lists()#

Empty/Create the lists.

Some times the raw-data list get too long, It would be necessary to dump the data, and empty the lists containing the raw data. This method does the latter.

fillna()#

Fill the np.nan values to nan.

This is just to let those in rock stay in rock.

get_u_du()#

Read the velocity at particle position.

Read the velocity and velocity derivatives in all three dimensions using the interpolate method with the default kernel. Read eulerian.Position.interpolate for more detail.

get_vol()#

Read in the volume of the cell.

For particles that has transport = True, volume of the cell is needed for the integration. This method read the volume that is calculated at __init__.

note_taking(subset_index=None, stamp=-1)#

Record raw data into list of lists.

This method is only called in save_raw = True particles. This method will note done the raw info of the particle trajectories. With those info, one could reconstruct the analytical trajectories to arbitrary position.

Parameters:

subset_index (iterable of int or None) – if not None, assume this method is called from a subset of the full particle object, and subset_index is the indices the subset occupy in the original object.

to_list_of_time(normal_stops, update_stops='default', return_in_between=True, dump_filename=False, store_kwarg={})#

Integrate the particles to a list of time.

Parameters:

  • normal_stops (iterable) – The time steps that user request a output

  • update_stops (iterable, or 'default') – The time steps that uvw array changes in the model. If ‘default’ is set, the method is going to figure it out automatically.

  • return_in_between (Boolean) – Users can get the values of update_stops free of computational cost.We understand that user may sometimes don’t want those in the output.In that case, it that case, set it to be False, and the output will all be at normal_stops.

Returns:

  • stops (list) – The list of stops. It is the combination of normal_stops and output_stops by default. f return_in_between is set to be False, this is then the same as normal stops.

  • to_return (list) – A list deep copy of particle that inherited the interpolate method as well as velocity and coords info.

to_next_stop(t_stop)#

Integrate all particles towards time tl.

This is done by repeatedly calling analytical step. Or at least try to do so before maximum_iteration is reached. If the maximum time is reached, we also force all particle’s internal clock to be tl.

Parameters:

t_stop (float) – The final time relative to 1970-01-01 in seconds.

trim(tol=0.0)#

Move the particles from outside the cell into the cell.

At the same time change the velocity accordingly. In the mean time, creating some negiligible error in time.

Parameters:

tol (float) – The relative tolerance when particles is significantly close to the cell.

update_uvw_array()#

Update the prefetched velocity arrays.

The way to do it is slightly different for dataset with time dimensions and those without.