Non-Mathematical Fish/System Management Functions

For this simulation, the system of fish are stored the following format:

\[\begin{split}\mathbf{X} := \begin{bmatrix} x_1 & y_1 & z_1 & n_{1x} & n_{1y} & n_{1z} \\ x_2 & y_2 & z_2 & n_{2x} & n_{2y} & n_{2z} \\ \vdots & \vdots & \vdots & \vdots & \vdots & \vdots \\ x_N & y_N & z_N & n_{Nx} & n_{Ny} & n_{Nz} \end{bmatrix}\end{split}\]

This module consists of fish management functions that aren’t specified in papers Mabrouk and Floryan [3] and Mabrouk and Floryan [4], such as finds.fish.positions(), finds.fish.orientations(), and finds.fish.normalize_orientation_vectors() alongside fish/system generation functions.

finds.fish.normalize_orientation_vectors(system)

Normalizes the orientation vectors for the given system.

Parameters:

system (NDArray) – The system to normalize.

Returns:

The system, with normalized orientation vectors.

Return type:

NDArray

finds.fish.perturb_orientations(orientations, angle_delta)

Perturbs an orientations matrix by \(\Delta \theta\).

Parameters:

  • orientations (NDArray) – The matrix of fish orientations

  • angle_delta (float) – The maximum random angular perturbation for a given fish in radians, \(\Delta \theta\)

Return type:

NDArray

finds.fish.generate_positions_random(n, bounds)

Generates a fresh system at random.

Parameters:

  • n (int) – The number of fish to include in the system.

  • bounds (ArrayLike) – The cartesian bounds (in meters) for which to generate fish. Supplied in form \((x_b,y_b,z_b)\), and means that the fish will be generated at position \((x,y,z)\) where \(x \in (-x_b, x_b), y \in (-x_b, y_b)\), and \(z \in (-z_b, z_b)\).

  • angle_delta (float) – The maximum random angular perturbation for all fish in radians.

Returns:

A matrix with shape \((N,6)\) storing the position of each fish.

Return type:

NDArray

finds.fish.generate_positions_lattice(side_length, spacing)

Generates the positions of fish arranged as a cubic lattice centered at (0,0).

Parameters:

  • side_length – The side length of the cube.

  • spacing – The grid spacing between fish within the lattice.

Return type:

NDArray

finds.fish.generate_positions_sphere(radius, spacing)

Generates the positions of fish arranged as a sphere centered at (0,0).

Parameters:

  • radius – The radius of the cube.

  • spacing – The grid spacing between fish within the sphere.

Rtype NDArray:

finds.fish.generate_positions_square(side_length, spacing)

Generates the positions of fish arranged as a planar square oriented with its normal vector on the \(x\)-axis and centered at (0,0).

Parameters:

  • side_length – The side length of the square.

  • spacing – The grid spacing between fish in the square.

Return type:

NDArray

finds.fish.generate_positions_circle(radius, spacing)

Generates the positions of fish arranged as a planar circle oriented with its normal vector on the \(x\)-axis and centered at (0,0).

Parameters:

  • radius – The radius of the circle

  • spacing – The grid spacing between fish in the circle.

Return type:

NDArray

finds.fish.generate_system(distribution, orientation, size=20, spacing=1.0, n_random=2, bounds=[10, 10, 10], angle_delta=0, debug_print=True)

Generates a system of fish distributed according to distribution: either spherically, as a lattice, or randomly within a box.

Parameters:

  • distribution ('random' | 'lattice' | 'sphere' | 'square' | 'circle') – How the fish are distributed.

  • orientation ('random' | 'aligned' | 'radial outward' | 'radial inward' | 'swirl inward' | 'swirl outward' | 'saddle') – How the fish are oriented.

  • n_random – The number of fish, provided that this is a random distribution. For all other distributions, the size parameter is used.

  • spacing (float) – How far apart the fish are (assuming it isn’t random).

Return type:

NDArray