Piccard Mariana / Documentation
Put marine physics
to work.
Start with a synthetic vehicle on your CPU. Then use the same Python library in your own Isaac Sim application.
Mariana supplies marine forces and vehicle-definition tools. The download includes the core library, an optional passive Kit extension and small examples you can inspect and run.
Run your first calculation01 / Before you start
Choose your starting point.
CPU calculation
Use Python 3.11 or newer and a terminal. The synthetic example calculates one acceleration from explicit vehicle parameters and thrust. It needs neither Isaac Sim nor a GPU.
Isaac / Kit library
Use an existing, compatible Isaac / Kit installation. The 0.1.3 flow, contact and sonar features were exercised in synthetic fixtures on Linux with an RTX GPU and Isaac Sim 6.0.1. That check covers this runtime and these fixtures.
Enabling the extension exposes piccard_mariana. It creates no scene, vehicle, callback or sensor. Your application owns those integrations.
Also included
The kit includes the optics, pressure and tabulated thrust modules from 0.1.1:
- Water RGB optics: attenuation and backscatter using your assumed water parameters. This is not a calibrated underwater camera model.
- Pressure and depth: convert between hydrostatic absolute pressure and depth using explicit water and reference inputs.
- Tabulated thrust: interpolate the PWM, voltage and thrust measurements you supply.
02 / Install
Unpack. Keep the folder together.
Extract the ZIP into a folder you control. Keep piccard.mariana/ intact when you move it; its configuration, source and examples travel together. Read the included README for this preview’s instructions and limits.
The commands below use a Unix-style shell and python3. Replace /absolute/path/to/piccard.mariana with the extracted folder’s real absolute path, and check that your Python is version 3.11 or newer.
Terminal · set your package path
export MARIANA_DIR="/absolute/path/to/piccard.mariana"
python3 --versionThis installs no simulator and starts no background process. For the CPU example, the next command makes the extracted source visible to that Python process only.
Optional image-array optics
Scalar use remains dependency-free. Only the apply_water_optics image-array function needs NumPy 1.26 or newer, below version 3, in the Python environment that calls it. Supply floating-point linear-light RGB and co-registered water-path ranges in metres.
Terminal · optional array dependency
python3 -m pip install 'numpy>=1.26,<3'03 / First CPU example
Calculate a synthetic vehicle’s response.
Run the supplied box definition with 10 N on its named main thruster. You can run this from a directory outside the extracted package.
Terminal · Python 3.11 or newer
PYTHONPATH="$MARIANA_DIR/src" \
python3 "$MARIANA_DIR/examples/select_synthetic_vehicle.py" \
--definition "$MARIANA_DIR/examples/synthetic_box.json" \
--thruster main_thruster --effort-n 10The JSON response identifies synthetic_box and reports body_acceleration. These are deliberately synthetic inputs, not calibrated vehicle coefficients. This calculation does not step a physics engine or run a controller.
04 / Varying current
Prescribe a current that varies in space and time.
Pass current_field=field and time_s=sim_time_s to external_wrench() or coupled_step(). Your callable takes the vehicle’s center of mass in world ENU metres and the pre-step simulation time in seconds. It returns ENU water velocity in metres per second. For nonzero added mass, return a CurrentSample with the local velocity, its time derivative at a fixed position, and its spatial velocity gradient. The example shows how to supply all three.
Terminal · run the bundled pulsing jet
PYTHONPATH="$MARIANA_DIR/src" \
python3 "$MARIANA_DIR/examples/varying_current.py"For a constant current, keep using current_world_m_s=(east, north, up). Do not pass a nonzero constant vector and a field together.
You can supply a measured or precomputed wake as an input. The bundled CPU example samples flow at the center of mass of a fully submerged body. Mariana accepts a wake field you supply and does not generate wakes. Varying current is unavailable with partial immersion and with the separate still-water static-plane fixture.
05 / New in 0.1.3
Model flow loads, obstacle contact and sonar.
- Ambient pressure loading. Opt in with
pressure_gradient=True. Supply the dynamic pressure gradient, excluding hydrostatic pressure, or provide velocity derivatives for the local fluid-acceleration approximation. - Multiple bodies.
batch_wrenches()calculates one wrench per body in input order.apply_marine_batch()sends the ordered forces and torques to a compatible Isaac rigid-body view in one call. Field sampling and force calculations still run on the CPU. - Distributed hull drag. Use weighted
HullDragPointlocations to sample flow across the hull. In shear, the resulting drag can create a turning moment even when the body is at rest. - Obstacle contact. Use ordinary PhysX colliders for floors, walls and obstacles in varying flow. Use zero added mass for contact studies, since PhysX resolves collision impulses using the body's dry inertia.
- Geometric sonar. Imaging sonar uses nearest-surface hits for shadows, with optional seeded intensity speckle and a single reciprocal reflected path. Profiling multibeam returns the nearest hit's slant range, travel time and intensity for each beam.
Read flow-loads-and-sonar.md in the ZIP for API examples and frame conventions. These models use prescribed flow and collider geometry. The synthetic Isaac Sim 6.0.1 checks do not establish CFD accuracy, full acoustic behavior, a throughput gain or calibration against a real sonar or vehicle.
06 / Isaac integration
Enable the library in an existing Kit session.
Start your own Isaac / Kit application. Before importing Mariana, run this in that application’s Python session. Use a fresh session with no Mariana source directory on PYTHONPATH.
Python · inside your running Kit application
import runpy
runpy.run_path(
"/absolute/path/to/piccard.mariana/examples/enable_library.py",
run_name="__main__",
)The example discovers and enables piccard.mariana, checks the enabled folder and imported module, and prints runtime versions, an entry-point SHA-256 and a synthetic force calculation. Save that output with your package and runtime versions.
It refuses an already imported Mariana module or a different enabled folder. If it refuses, start a clean session and check the path. Your application still owns startup, scene construction, physics callbacks, output collection and shutdown.
07 / Your vehicle
Supply parameters, not just a mesh.
Copy examples/synthetic_box.json or examples/synthetic_ellipsoid.json as a schema reference. Replace the synthetic values with documented inputs for your vehicle and keep their provenance and usage rights explicit.
- Physics: dry mass and inertia, displaced volume, centers of gravity and buoyancy, water density, drag and the supported added-mass inputs.
- Mounts: named positions, orientations and thrust axes relative to the dry mechanical center of gravity.
- Source: revision, reference, declared license and per-field provenance. The loader records these; it does not independently verify calibration or rights.
| Quantity | Convention |
|---|---|
| World | Right-handed ENU: east, north, up |
| Body | Right-handed FLU: forward, left, up |
| Body origin | Dry mechanical center of gravity |
| Orientation | Scalar-first (w, x, y, z), body to world |
| Units | SI: m, s, kg, rad, N and N m |
Convert NED / FRD inputs explicitly. A matching label is not a frame conversion. Geometry alone does not supply mass, inertia, displacement or drag.
Python · explicit definition loading
from piccard_mariana import load_vehicle_definition
vehicle = load_vehicle_definition("/absolute/path/to/vehicle.json")
parameters, dry_inertia = vehicle.dynamic_inputs()
thrust = vehicle.point_thrust("main_thruster", 10.0)Fields can be resolved, source_only or unresolved. dynamic_inputs() refuses unresolved physics. Mount transforms and thrust axes must be resolved before the corresponding APIs can use them.
08 / Integration & current limits
The physics library is one part of your application.
Mariana
Marine forces & vehicle definitions
Geometric sonar tools
Optional Isaac / PhysX adapter
Your application
Scene & vehicle
Sensors & ROS
Estimator, controller & lifecycle
The reusable download does not include a complete vehicle simulation, a calibrated physical AUV, a configured sensor suite, an estimator or an autonomy stack. Simulated cameras, sensor acquisition, ROS bridges and controllers belong in the integrating application.
The RACE application is separate
The RACE vehicle, lab scene, controller and onboard cameras belong to a separate application with its own installation, runtime and vehicle dependencies. They are not included in this library ZIP, and enabling the extension does not launch RACE.
Supported combinations depend on the chosen path: the coupled added-mass solve applies to a fully submerged body in free water; partial buoyancy uses analytic box geometry. Current and contact combinations have their own explicit restrictions. There is no general CFD, wave field or arbitrary-hull partial hydrostatics.
Mounted-point and bottom-plane APIs are integration inputs. Native simulator checks are specific to their recorded cases and runtimes; CPU checks do not establish native integration or physical accuracy.
Keep three questions separate: does the code behave as specified, does your native integration work, and does your model agree with physical measurements?
09 / Go further
Make the next result reproducible.
Read the README and examples inside the package for the release’s usage instructions and limits. Start with examples/pure_force.py for direct wrench use. The optional native probe requires a separately prepared Isaac runtime and GPU; the CPU setup does not install either.
When discussing a model or reporting a discrepancy, include the package version, vehicle-definition revision, runtime version, expected behavior and a minimal reproducible case. Label synthetic inputs, native observations and physical measurements separately. Keep restricted vehicle data out of shared reports.
Discuss your integration with Piccard