Conventions

Units

We use SI units for the model parameters, except for angles (degrees instead of radians) and target strength (deciBels). All model code must accept inputs and produce results using the units below. If the model calculations use different units internally, the code should internally convert between them.

Parameter	Units	Notes
length, diameter, radius, thickness, etc	m
density	kg/m³
sound speed	m/s
angle	°	See Coordinate systems
frequency	Hz
target strength	dB	reference value is 1 m²

Coordinate systems

The right-handed cartesian coordinate system as defined by ISO 80000-2¹ is to be used, as illustrated below. The acoustic wave is defined to always travel in the positive z direction and the organism is rotated to achieve different acoustic incidence angles.

The Tait-Bryan z-y'-x'' (intrinsic) convention was chosen to represent organism rotations as it is commonly used in nautical situations. Intrinsic means that the rotations are about the axes of the rotating organism, rather than the original coordinate system. The order of rotations is z, then y, then x.

Rotations about the z-axis are yaw (ψ), about the y-axis are pitch (θ), and about the x-axis are roll (ɸ). The definitions are such that:

• A yaw (ψ) value of 0° occurs when the organism lies along the positive x-axis (as per the illustration) and positive yaw values (as per the yellow arrow) rotate the organism's head towards the positive y-axis,
• Pitch (θ) values of 0°, 90°, and 180° correspond to acoustic wave incidence angles of head on, dorsal, and tail on, respectively,
• Roll (ɸ) values of –90°, 0°, and 90° correspond to acoustic wave incidences onto the right (starboard), dorsal, and left (port) sides of the organism, respectively.

All model code should accept angles and produce results in this coordinate system. If the model calculations use a different coordinate system, the code should internally convert between the system given above and the version used in the code.

Code style

Contributions of code should follow standardised or community-agreed styles and be provided in (or added to) a structure suitable for packaging and uploading to package libraries. For Python this includes pip and/or conda, for R this would be CRAN, for Matlab this would be a toolbox on the MATLAB File Exchange, etc.

Python code should follow PEP8 and docstrings should use PEP257 with the contents following the numpydoc style. An exception to PEP8 is made to allow lines of up to 100 characters.

---

1. ISO. 2019. ISO 80000-2. Part 2: Mathematics. ↩