A collection of functions for streamlines and related shennanigans. More...

Functions
def	stream2
	A two-dimensional streamline solver. More...

def	stream3
	A three-dimensional streamline solver. More...

def	stream3_many
	A three-dimensional streamline solver. More...

def	pathlines
	A three-dimensional lagrangian particle tracker. More...

def	pathlines_many
	A three-dimensional lagrangian particle tracker designed for tracking many particles at once. More...

def	pathlines_for_OLIC_xyzt_ani
	A three-dimensional lagrangian particle tracker designed for tracking many particles at once. More...

def	numeric_GLM_xyzt
	A three-dimensional lagrangian particle tracker designed for tracking many particles at once as a method of estimating Generalised Lagrangian-Mean velocities. More...

def	numeric_GLM_xyz
	A three-dimensional streamline solver. More...

def	bilinear_interp (x0, y0, field, x, y, len_x, len_y)
	Do bilinear interpolation of a field. More...

def	actual_bilinear_interp (field, x0, y0, x, y, len_x, len_y, x_index, y_index)
	This is a numba accelerated bilinear interpolation. More...

def	trilinear_interp (x0, y0, z0, field, x, y, z, len_x, len_y, len_z)
	Do trilinear interpolation of the field in three spatial dimensions. More...

def	trilinear_interp_arrays (x0, y0, z0, field, x, y, z, len_x, len_y, len_z)
	Do trilinear interpolation of the field in three spatial dimensions. More...

def	actual_trilinear_interp (field, x0, y0, z0, x_index, y_index, z_index, x, y, z)
	This is a numba accelerated trilinear interpolation. More...

def	quadralinear_interp (x0, y0, z0, t0, field, x, y, z, t, len_x, len_y, len_z, len_t, x_index, y_index, z_index, t_index)
	Do quadralinear interpolation of the velocity field in three spatial dimensions and one temporal dimension to get nice accurate streaklines. More...

def	actual_quadralinear_interp (field, x0, y0, z0, t0, x_index, y_index, z_index, t_index, x, y, z, t)
	This is a numba accelerated quadralinear interpolation. More...

def	indices_and_field (x, y, z, x0, y0, z0, t_index, len_x, len_y, len_z, len_t, netcdf_filehandle, variable, bias_field)
	A helper function to extract a small 4D hypercube of data from a netCDF file. More...

def	extract_along_path4D
	extract the value of a field along a path through a time varying, 3 dimensional field. More...

def	extract_along_path3D (path_x, path_y, path_z, x_axis, y_axis, z_axis, field)
	Extract the value of a field along a path through a 3 dimensional field. More...

def	extract_along_path2D
	Extract the value of a field along a path through a 2 dimensional field. More...

Detailed Description

A collection of functions for streamlines and related shennanigans.

Streamlines

Functions for creating and analysing streamlines.

These functions work on cartesian and spherical polar grids - other grids, such as cubed sphere, are not supported.

Streamlines are defined to be the path that a parcel of fluid would follow when advected by an unchanging velocity field - the velocities are constant in time.

Streaklines are defined as the path that a parcel of fluid would follow in the actual flow - the velocity fields change with time.

Function Documentation

def mitgcm.streamlines.actual_bilinear_interp	(	field,
		x0,
		y0,
		x,
		y,
		len_x,
		len_y,
		x_index,
		y_index
	)

This is a numba accelerated bilinear interpolation.

The .jit decorator just above this function causes it to be compiled just before it is run. This introduces a small, Order(1 second), overhead the first time, but not on subsequent calls.

Definition at line 2086 of file streamlines.py.

def mitgcm.streamlines.actual_quadralinear_interp	(	field,
		x0,
		y0,
		z0,
		t0,
		x_index,
		y_index,
		z_index,
		t_index,
		x,
		y,
		z,
		t
	)

This is a numba accelerated quadralinear interpolation.

The .jit decorator just above this function causes it to be compiled just before it is run. This introduces a small, Order(1 second), overhead the first time, but not on subsequent calls.

Definition at line 2229 of file streamlines.py.

def mitgcm.streamlines.actual_trilinear_interp	(	field,
		x0,
		y0,
		z0,
		x_index,
		y_index,
		z_index,
		x,
		y,
		z
	)

This is a numba accelerated trilinear interpolation.

The .jit decorator just above this function causes it to be compiled just before it is run. This introduces a small, Order(1 second), overhead the first time, but not on subsequent calls.

Definition at line 2183 of file streamlines.py.

def mitgcm.streamlines.bilinear_interp	(	x0,
		y0,
		field,
		x,
		y,
		len_x,
		len_y
	)

Do bilinear interpolation of a field.

This function assumes that the grid can locally be regarded as cartesian, with everything at right angles.

x0,y0 are the points to interpolate to.

Definition at line 2056 of file streamlines.py.

def mitgcm.streamlines.extract_along_path2D	(	path_x,
		path_y,
		x_axis,
		y_axis,
		field,
		order = `3`,
		dx = `0`,
		dy = `0`
	)

Extract the value of a field along a path through a 2 dimensional field.

The field must be passed as an array. Time varying fields are not supported.

Parameters

path_x - x-coordinate of the path.
path_y - y-coordinate of the path.
x_axis - vector of the x-coordinate of the input field.
y_axis - vector of the y-coordinate of the input field.
field - the input field, the values of which will be extracted along the path.
order - the order for the interpolation function, must be between 1 and 5 inclusive. 1 -> linear, 3 -> cubic.
dx, dy - order of the derivative to take in x or y. Optional arguments that are passed to the scipy cubic interpolation function.

Definition at line 2431 of file streamlines.py.

def mitgcm.streamlines.extract_along_path3D	(	path_x,
		path_y,
		path_z,
		x_axis,
		y_axis,
		z_axis,
		field
	)

Extract the value of a field along a path through a 3 dimensional field.

The field must be passed as an array. Time varying fields are not supported.

Definition at line 2403 of file streamlines.py.

def mitgcm.streamlines.extract_along_path4D	(	path_x,
		path_y,
		path_z,
		path_t,
		x_axis,
		y_axis,
		z_axis,
		t_axis,
		netcdf_filename = `'netcdf file with variable of interest'`,
		netcdf_variable = `'momVort3'`
	)

extract the value of a field along a path through a time varying, 3 dimensional field.

The field must be in a NetCDF file, since it is assumed to be 4D and very large.

This can also be used to pull out values at specific locations and times.

Definition at line 2313 of file streamlines.py.

def mitgcm.streamlines.indices_and_field	(	x,
		y,
		z,
		x0,
		y0,
		z0,
		t_index,
		len_x,
		len_y,
		len_z,
		len_t,
		netcdf_filehandle,
		variable,
		bias_field
	)

A helper function to extract a small 4D hypercube of data from a netCDF file.

This isn't intended to be used on its own.

Definition at line 2278 of file streamlines.py.

def mitgcm.streamlines.numeric_GLM_xyz	(	u,
		v,
		w,
		n_particles,
		startx,
		starty,
		startz,
		startt,
		total_time,
		timestep,
		r_x,
		r_y,
		r_z,
		grid_object,
		r_cutoff_factor = `3`,
		x_v = `'None'`,
		y_v = `'None'`,
		z_v = `'None'`,
		x_w = `'None'`,
		y_w = `'None'`,
		z_w = `'None'`,
		u_grid_loc = `'U'`,
		v_grid_loc = `'V'`,
		w_grid_loc = `'W'`
	)

A three-dimensional streamline solver.

The velocity fields must be three dimensional and not vary in time. X_grid_loc variables specify where the field "X" is located on the C-grid. Possibles options are, U, V, W, T and Zeta.

Returns:

x_stream, y_stream, z_stream - all with dimensions (particle,time_level)
t_stream - with dimensions (time_level)
com_stream - with dimensions (3(x,y,z),time_level)

Definition at line 1821 of file streamlines.py.

def mitgcm.streamlines.numeric_GLM_xyzt	(	u_netcdf_filename,
		v_netcdf_filename,
		w_netcdf_filename,
		n_particles,
		startx,
		starty,
		startz,
		startt,
		total_time,
		timestep,
		r_x,
		r_y,
		r_z,
		t,
		grid_object,
		r_cutoff_factor = `3`,
		u_netcdf_variable = `'UVEL'`,
		v_netcdf_variable = `'VVEL'`,
		w_netcdf_variable = `'WVEL'`,
		u_grid_loc = `'U'`,
		v_grid_loc = `'V'`,
		w_grid_loc = `'W'`,
		u_bias_field = `None`,
		v_bias_field = `None`,
		w_bias_field = `None`
	)

A three-dimensional lagrangian particle tracker designed for tracking many particles at once as a method of estimating Generalised Lagrangian-Mean velocities.

The algorithm is a little slow because it spends time checking that the particles are within a given distance of the centre of mass, that they are in the fluid not the bathymetry and that they are below the surface. This means that the cloud of particles should remain within the fluid and not get trapped by the bathymetry.

The velocity fields must be four dimensional (three spatial, one temporal) and have units of m/s. It should work to track particles forwards or backwards in time (set timestep <0 for backwards in time). But, be warned, backwards in time hasn't been thoroughly tested yet.

Because this is a very large amount of data, the fields are passed as netcdffile handles.

Returns:

x_stream, y_stream, z_stream - all with dimensions (particle,time_level)
t_stream - with dimensions (time_level)
com_stream - with dimensions (time_level)

The variables are:

?_netcdf_filename = name of the netcdf file with ?'s data in it.
n_particles = number of particles to track
start? = starting value for x, y, z, or time
total_time = length of time to track particles for, in seconds. This is always positive
timestep = timestep for particle tracking algorithm, in seconds. This can be positive or negative.
r_? = radius of sedding ellipsoid in x, y, or z direction
t = vector of time levels that are contained in the velocity data.
grid_object is m.grid if you followed the standard naming conventions.
?_netcdf_variable = name of the "?" variable field in the netcdf file.
?_grid_loc = where the field "?" is located on the C-grid. Possibles options are, U, V, W, T and Zeta.
?_bias_field = bias to add to that velocity field component. If set to -mean(velocity component), then only the time varying portion of that field will be used.

Definition at line 1474 of file streamlines.py.

def mitgcm.streamlines.pathlines	(	u_netcdf_filename,
		v_netcdf_filename,
		w_netcdf_filename,
		startx,
		starty,
		startz,
		startt,
		t,
		grid_object,
		t_max,
		delta_t,
		u_netcdf_variable = `'UVEL'`,
		v_netcdf_variable = `'VVEL'`,
		w_netcdf_variable = `'WVEL'`,
		u_grid_loc = `'U'`,
		v_grid_loc = `'V'`,
		w_grid_loc = `'W'`,
		u_bias_field = `None`,
		v_bias_field = `None`,
		w_bias_field = `None`
	)

A three-dimensional lagrangian particle tracker.

The velocity fields must be four dimensional (three spatial, one temporal) and have units of m/s. It should work to track particles forwards or backwards in time (set delta_t <0 for backwards in time). But, be warned, backwards in time hasn't been thoroughly tested yet.

Because this is a very large amount of data, the fields are passed as netcdffile handles.

The variables are:

?_netcdf_filename = name of the netcdf file with ?'s data in it.
start? = intial value for x, y, z, or t.
t = vector of time levels that are contained in the velocity data.
grid_object is m.grid if you followed the standard naming conventions.
?_netcdf_variable = name of the "?" variable field in the netcdf file.
t_max = length of time to track particles for, in seconds. This is always positive
delta_t = timestep for particle tracking algorithm, in seconds. This can be positive or negative.
?_grid_loc = where the field "?" is located on the C-grid. Possibles options are, U, V, W, T and Zeta.
?_bias_field = bias to add to that velocity field omponent. If set to -mean(velocity component), then only the time varying portion of that field will be used.

Definition at line 490 of file streamlines.py.

def mitgcm.streamlines.pathlines_for_OLIC_xyzt_ani	(	u_netcdf_filename,
		v_netcdf_filename,
		w_netcdf_filename,
		n_particles,
		startt,
		t,
		grid_object,
		t_tracking,
		delta_t,
		trace_length,
		u_netcdf_variable = `'UVEL'`,
		v_netcdf_variable = `'VVEL'`,
		w_netcdf_variable = `'WVEL'`,
		u_grid_loc = `'U'`,
		v_grid_loc = `'V'`,
		w_grid_loc = `'W'`,
		u_bias_field = `None`,
		v_bias_field = `None`,
		w_bias_field = `None`
	)

A three-dimensional lagrangian particle tracker designed for tracking many particles at once.

If you're tracking fewer than O(10) - use the streaklines function.

The velocity fields must be four dimensional (three spatial, one temporal) and have units of m/s. It should work to track particles forwards or backwards in time (set delta_t <0 for backwards in time). But, be warned, backwards in time hasn't been thoroughly tested yet.

Because this is a very large amount of data, the fields are passed as netcdffile handles.

Returns:

x_stream, y_stream, z_stream - all with dimensions (particle,time_level)
t_stream - with dimensions (time_level)

The variables are:

?_netcdf_filename = name of the netcdf file with ?'s data in it.
n_particles = number of particles to track
startt = start time
t = vector of time levels that are contained in the velocity data.
grid_object is m.grid if you followed the standard naming conventions.
?_netcdf_variable = name of the "?" variable field in the netcdf file.
t_tracking = length of time to track particles for, in seconds. This is always positive
delta_t = timestep for particle tracking algorithm, in seconds. This can be positive or negative.
trace_length = length of time for each individual trace
?_grid_loc = where the field "?" is located on the C-grid. Possibles options are, U, V, W, T and Zeta.
?_bias_field = bias to add to that velocity field component. If set to -mean(velocity component), then only the time varying portion of that field will be used.

Definition at line 1143 of file streamlines.py.

def mitgcm.streamlines.pathlines_many	(	u_netcdf_filename,
		v_netcdf_filename,
		w_netcdf_filename,
		startx,
		starty,
		startz,
		startt,
		t,
		grid_object,
		t_max,
		delta_t,
		u_netcdf_variable = `'UVEL'`,
		v_netcdf_variable = `'VVEL'`,
		w_netcdf_variable = `'WVEL'`,
		u_grid_loc = `'U'`,
		v_grid_loc = `'V'`,
		w_grid_loc = `'W'`,
		u_bias_field = `None`,
		v_bias_field = `None`,
		w_bias_field = `None`
	)

A three-dimensional lagrangian particle tracker designed for tracking many particles at once.

If you're tracking fewer than O(10) - use the pathlines function.

The velocity fields must be four dimensional (three spatial, one temporal) and have units of m/s. It should work to track particles forwards or backwards in time (set delta_t <0 for backwards in time). But, be warned, backwards in time hasn't been thoroughly tested yet.

Because this is a very large amount of data, the fields are passed as netcdffile handles.

Returns:

x_stream, y_stream, z_stream - all with dimensions (particle,time_level)
t_stream - with dimensions (time_level)

The variables are:

?_netcdf_filename = name of the netcdf file with ?'s data in it.
start? = (nx1) arrays of initial values for x, y, or z.
startt = start time
t = vector of time levels that are contained in the velocity data.
grid_object is m.grid if you followed the standard naming conventions.
?_netcdf_variable = name of the "?" variable field in the netcdf file.
t_max = length of time to track particles for, in seconds. This is always positive
delta_t = timestep for particle tracking algorithm, in seconds. This can be positive or negative.
?_grid_loc = where the field "?" is located on the C-grid. Possibles options are, U, V, W, T and Zeta.
?_bias_field = bias to add to that velocity field component. If set to -mean(velocity component), then only the time varying portion of that field will be used.

Definition at line 841 of file streamlines.py.

def mitgcm.streamlines.quadralinear_interp	(	x0,
		y0,
		z0,
		t0,
		field,
		x,
		y,
		z,
		t,
		len_x,
		len_y,
		len_z,
		len_t,
		x_index,
		y_index,
		z_index,
		t_index
	)

Do quadralinear interpolation of the velocity field in three spatial dimensions and one temporal dimension to get nice accurate streaklines.

This function assumes that the grid can locally be regarded as cartesian, with everything at right angles.

x0,y0,z0, and t0 represent the point to interpolate to.

The velocity field, "field", is passed as a truncated 4D field.

x,y,z,t are vectors of these dimensions.

Definition at line 2209 of file streamlines.py.

def mitgcm.streamlines.stream2	(	u,
		v,
		startx,
		starty,
		grid_object,
		t_max = `2592000`,
		delta_t = `3600`,
		u_grid_loc = `'U'`,
		v_grid_loc = `'V'`
	)

A two-dimensional streamline solver.

The velocity fields must be two dimensional and not vary in time. X_grid_loc variables specify where the field "X" is located on the C-grid. Possibles options are, U, V, T and Zeta.

Definition at line 29 of file streamlines.py.

def mitgcm.streamlines.stream3	(	u,
		v,
		w,
		startx,
		starty,
		startz,
		grid_object = `None`,
		x_v = `'None'`,
		y_v = `'None'`,
		z_v = `'None'`,
		x_w = `'None'`,
		y_w = `'None'`,
		z_w = `'None'`,
		t_max = `2592000`,
		delta_t = `3600`,
		u_grid_loc = `'U'`,
		v_grid_loc = `'V'`,
		w_grid_loc = `'W'`
	)

A three-dimensional streamline solver.

The velocity fields must be three dimensional and not vary in time. X_grid_loc variables specify where the field "X" is located on the C-grid. Possibles options are, U, V, W, T and Zeta.

Definition at line 144 of file streamlines.py.

def mitgcm.streamlines.stream3_many	(	u,
		v,
		w,
		startx,
		starty,
		startz,
		grid_object = `None`,
		x_v = `'None'`,
		y_v = `'None'`,
		z_v = `'None'`,
		x_w = `'None'`,
		y_w = `'None'`,
		z_w = `'None'`,
		t_max = `2592000`,
		delta_t = `3600`,
		u_grid_loc = `'U'`,
		v_grid_loc = `'V'`,
		w_grid_loc = `'W'`
	)

A three-dimensional streamline solver.

The velocity fields must be three dimensional and not vary in time. X_grid_loc variables specify where the field "X" is located on the C-grid. Possibles options are, U, V, W, T and Zeta.

Returns:

x_stream, y_stream, z_stream - all with dimensions (particle,time_level)
t_stream - with dimensions (time_level)

Definition at line 311 of file streamlines.py.

def mitgcm.streamlines.trilinear_interp	(	x0,
		y0,
		z0,
		field,
		x,
		y,
		z,
		len_x,
		len_y,
		len_z
	)

Do trilinear interpolation of the field in three spatial dimensions.

This function assumes that the grid can locally be regarded as cartesian, with everything at right angles. It also requires that the entire field can be held in memory at the same time.

x0,y0, and z0 represent the point to interpolate to.

Definition at line 2096 of file streamlines.py.

def mitgcm.streamlines.trilinear_interp_arrays	(	x0,
		y0,
		z0,
		field,
		x,
		y,
		z,
		len_x,
		len_y,
		len_z
	)

Do trilinear interpolation of the field in three spatial dimensions.

This function assumes that the grid can locally be regarded as cartesian, with everything at right angles. It also requires that the entire field can be held in memory at the same time.

x0,y0, and z0 represent the point to interpolate to.

Definition at line 2140 of file streamlines.py.