NavalToolbox

High-performance naval architecture library for Python, powered by Rust.

PyPI version License: AGPL v3 Python 3.9+

Overview

NavalToolbox provides fast and accurate naval architecture calculations through a Python API, with a high-performance Rust backend that handles the heavy computational work.

Features

  • ⚓ Hull Geometry: Load and manipulate ship hulls from STL/VTK files
  • 🚢 Multi-hull Support: Catamarans, trimarans, and arbitrary configurations with contact surface detection
  • 📊 Hydrostatics: Volume, COB, Waterplane ($A_{wp}$, LCF, $BM_t$, $BM_l$), Free Surface Correction ($GM_{dry}/GM_{wet}$)
  • ⚖️ Stability Analysis: GZ curve calculation with automatic trim optimization
  • 🌊 Downflooding Detection: Automatic detection of submerged openings
  • 🛢️ Tank Management: Fill levels, free surface effects, sounding tables
  • 📎 Appendages: Add arbitrary geometry (STL/VTK) or primitive shapes for volume and buoyancy contributions
  • 📏 Deck Edges: Define deck edge contours (livet) for freeboard calculation and deck immersion point detection
  • ⚖️ Loading Conditions: Compose mass inventories and tank overrides to build operational profiles
  • 💨 Wind Heeling: Silhouette-based wind calculations (DXF/VTK support)
  • 📝 Scriptable Verification: Rhai scripting engine for custom stability criteria
  • 🧊 3D Visualization: Interactive vessel and hydrostatic visualization with Plotly
  • 📈 Plotting: Built-in 2D plotting utilities with Matplotlib integration
  • ⚡ High Performance: Rust backend with Python convenience

Installation

pip install navaltoolbox

Requirements:

  • Python 3.9 or higher
  • No additional dependencies required (all native code included in wheels)

Quick Start

Loading a Hull

from navaltoolbox import Hull

# Load hull from STL file
hull = Hull("ship.stl")

# Get hull dimensions
bounds = hull.get_bounds()
loa = bounds[1] - bounds[0]  # Length overall
boa = bounds[3] - bounds[2]  # Beam overall

print(f"LOA: {loa:.2f}m, BOA: {boa:.2f}m")
print(f"Triangles: {hull.num_triangles()}")

Hydrostatics Calculation

from navaltoolbox import Hull, Vessel, HydrostaticsCalculator

# Create vessel
hull = Hull("ship.stl")
vessel = Vessel(hull)

# Calculate hydrostatics at a given draft
calc = HydrostaticsCalculator(vessel, water_density=1025.0)

# Option 1: At draft with VCG (computes stability)
state = calc.from_draft(draft=5.0, vcg=7.0)

print(f"Volume: {state.volume:.1f} m³")
print(f"Displacement: {state.displacement:.0f} kg")
print(f"COB: ({state.cob[0]:.2f}, {state.cob[1]:.2f}, {state.cob[2]:.2f})")
print(f"Waterplane Area: {state.waterplane_area:.1f} m²")
print(f"LCF: {state.lcf:.2f} m")
print(f"GMT (wet): {state.gmt:.3f} m")
print(f"GMT (dry): {state.gmt_dry:.3f} m")

# Option 2: Find draft for displacement
state_disp = calc.from_displacement(512500.0)
print(f"Draft for {state_disp.displacement:.0f}kg: {state_disp.draft:.3f} m")

Stability Analysis (GZ Curve)

from navaltoolbox import Hull, Vessel, StabilityCalculator

# Create vessel and calculator
hull = Hull("ship.stl")
vessel = Vessel(hull)
calc = StabilityCalculator(vessel, water_density=1025.0)

# Calculate GZ curve
displacement_mass = 8635000.0  # kg
cog = (71.67, 0.0, 7.555)      # LCG, TCG, VCG in meters
heels = [0, 10, 20, 30, 40, 50, 60, 70, 80, 90]

curve = calc.gz_curve(displacement_mass, cog, heels)

# Display results
print("Heel (°)  |  GZ (m)")
print("-" * 25)
for heel, gz in zip(curve.heels(), curve.values()):
    print(f"{heel:7.1f}  |  {gz:7.3f}")

# Get max GZ
gz_values = curve.values()
max_gz = max(gz_values)
max_idx = gz_values.index(max_gz)
max_heel = heels[max_idx]
print(f"\nMax GZ: {max_gz:.3f}m at {max_heel}°")

Loading Conditions

from navaltoolbox import Hull, Vessel, Tank, LoadingCondition, MassCategory

# Create vessel with a tank
vessel = Vessel(Hull("ship.stl"))
vessel.add_tank(Tank.from_box("FO_1", 20.0, 30.0, -5.0, 5.0, 0.0, 2.0, 1000.0))

# Define loading condition
lc = LoadingCondition("Arrival")
lc.add_mass_simple("Lightship", 5000000.0, (40.0, 0.0, 5.0), MassCategory.lightship())
lc.set_tank_fill_percent("FO_1", 50.0)

# Import/Export (JSON or CSV)
# lc.save_json("arrival.json")
# lc2 = LoadingCondition.load_csv("departure.csv")

# Use convenience methods directly to seamlessly merge the solid masses and tank configurations:
from navaltoolbox import StabilityCalculator, HydrostaticsCalculator

stab_calc = StabilityCalculator(vessel)
curve = stab_calc.gz_curve_from_loading(lc, heels=[0, 10, 20, 30])
print(f"Calculated GZ max: {max(curve.values()):.3f} m")

hydro_calc = HydrostaticsCalculator(vessel)
state = hydro_calc.from_loading(lc)
print(f"Equilibrium Draft: {state.draft:.3f} m")

Documentation

For more detailed documentation, examples, and API reference, visit:

Performance

NavalToolbox is built with performance in mind:

  • Written in Rust for maximum speed and memory safety
  • Efficient mesh operations using parry3d
  • Parallel processing where applicable
  • Zero-copy data transfer between Python and Rust

Example benchmark (DTMB 5415 hull, 3436 triangles):

  • Load STL: ~10ms
  • Hydrostatics calculation: ~50ms
  • GZ curve (13 points): ~650ms

Use Cases

NavalToolbox is suitable for:

  • 🎓 Naval architecture education: Teaching hydrostatics and stability
  • 🔬 Research: Rapid prototyping of new methods and algorithms
  • 🏭 Engineering: Production stability calculations and analysis
  • 🤖 Optimization: Integration with optimization frameworks
  • 📊 Batch processing: Analyzing multiple design variants

Requirements and Compatibility

  • Python: 3.9, 3.10, 3.11, 3.12, 3.13
  • Operating Systems:
    • macOS (Intel and Apple Silicon)
    • Linux (x86_64, aarch64)
    • Windows (x86_64)
  • File Formats:
    • Hull geometry: STL (binary and ASCII), VTK
    • Silhouettes: DXF, VTK

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests on GitHub.

License

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

This means:

  • ✅ Free to use, modify, and distribute
  • ✅ Can be used in commercial projects
  • ⚠️ Source code must be made available under AGPL
  • ⚠️ Network use is considered distribution (AGPL provision)

See the LICENSE file for details.

Disclaimer

NavalToolbox has been developed with care to ensure that all models and methods are correct, and that calculations reflect the most accurate results achievable with the implemented algorithms. However, results must not be considered as a guarantee of performance. The author cannot be held responsible for any inaccuracies in the calculations or for any consequences arising from the use of this software. Users are advised to independently verify critical calculations and to use this software as a tool to support, not replace, professional engineering judgment.

Citation

If you use NavalToolbox in your research, please cite:

@software{navaltoolbox2026,
  author = {Anceau, Antoine},
  title = {NavalToolbox: High-performance naval architecture library},
  year = {2026},
  url = {https://github.com/NavalToolbox/navaltoolbox-lib}
}

Author

Antoine ANCEAU

Support

Note: This package uses a Rust backend for high performance. Pre-built wheels are provided for common platforms. If a wheel is not available for your platform, the package will attempt to build from source (requires Rust toolchain).

Project links

Data verified by PyPI on Jul 6, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for antoineanceau from gravatar.com antoineanceau

Credits

Author: Antoine ANCEAU

GitHub Statistics

Data verified by PyPI on Jul 6, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU Affero General Public License v3 or later (AGPLv3+) (AGPL-3.0-or-later)

Requires

Python >=3.9

Tags

naval-architecture hydrostatics stability marine-engineering ship-design

Classifiers

Report project as malware

Metadata

Project links

Data verified by PyPI on Jul 6, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for antoineanceau from gravatar.com antoineanceau

Credits

Author: Antoine ANCEAU

GitHub Statistics

Data verified by PyPI on Jul 6, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

GNU Affero General Public License v3 or later (AGPLv3+) (AGPL-3.0-or-later)

Requires

Python >=3.9

Tags

naval-architecture hydrostatics stability marine-engineering ship-design

Classifiers

Report project as malware

Release files for navaltoolbox 0.9.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for navaltoolbox 0.9.3
File Size Uploaded
navaltoolbox-0.9.3.tar.gz 346.6 kB Details

Built distributions (wheels)

Table of built distributions (wheels) for navaltoolbox 0.9.3
File
navaltoolbox-0.9.3-cp313-cp313-win_amd64.whl 3.0 MB CPython 3.13 CPython 3.13 Windows x86-64 Details
navaltoolbox-0.9.3-cp313-cp313-manylinux_2_28_x86_64.whl 3.2 MB CPython 3.13 CPython 3.13 Linux glibc 2.28+ x86-64 Details
navaltoolbox-0.9.3-cp313-cp313-manylinux_2_28_aarch64.whl 3.1 MB CPython 3.13 CPython 3.13 Linux glibc 2.28+ ARM64 Details
navaltoolbox-0.9.3-cp313-cp313-manylinux_2_24_x86_64.whl 3.2 MB CPython 3.13 CPython 3.13 Linux glibc 2.24+ x86-64 Details
navaltoolbox-0.9.3-cp313-cp313-manylinux_2_24_aarch64.whl 3.1 MB CPython 3.13 CPython 3.13 Linux glibc 2.24+ ARM64 Details
navaltoolbox-0.9.3-cp313-cp313-macosx_11_0_arm64.whl 2.9 MB CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details
navaltoolbox-0.9.3-cp312-cp312-win_amd64.whl 3.0 MB CPython 3.12 CPython 3.12 Windows x86-64 Details
navaltoolbox-0.9.3-cp312-cp312-manylinux_2_28_x86_64.whl 3.2 MB CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64 Details
navaltoolbox-0.9.3-cp312-cp312-manylinux_2_28_aarch64.whl 3.1 MB CPython 3.12 CPython 3.12 Linux glibc 2.28+ ARM64 Details
navaltoolbox-0.9.3-cp312-cp312-manylinux_2_24_x86_64.whl 3.2 MB CPython 3.12 CPython 3.12 Linux glibc 2.24+ x86-64 Details
navaltoolbox-0.9.3-cp312-cp312-manylinux_2_24_aarch64.whl 3.1 MB CPython 3.12 CPython 3.12 Linux glibc 2.24+ ARM64 Details
navaltoolbox-0.9.3-cp312-cp312-macosx_11_0_arm64.whl 2.9 MB CPython 3.12 CPython 3.12 macOS 11.0+ ARM64 Details
navaltoolbox-0.9.3-cp311-cp311-win_amd64.whl 3.0 MB CPython 3.11 CPython 3.11 Windows x86-64 Details
navaltoolbox-0.9.3-cp311-cp311-manylinux_2_28_x86_64.whl 3.2 MB CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64 Details
navaltoolbox-0.9.3-cp311-cp311-manylinux_2_28_aarch64.whl 3.1 MB CPython 3.11 CPython 3.11 Linux glibc 2.28+ ARM64 Details
navaltoolbox-0.9.3-cp311-cp311-manylinux_2_24_x86_64.whl 3.2 MB CPython 3.11 CPython 3.11 Linux glibc 2.24+ x86-64 Details
navaltoolbox-0.9.3-cp311-cp311-manylinux_2_24_aarch64.whl 3.1 MB CPython 3.11 CPython 3.11 Linux glibc 2.24+ ARM64 Details
navaltoolbox-0.9.3-cp311-cp311-macosx_11_0_arm64.whl 2.9 MB CPython 3.11 CPython 3.11 macOS 11.0+ ARM64 Details
navaltoolbox-0.9.3-cp310-cp310-win_amd64.whl 3.0 MB CPython 3.10 CPython 3.10 Windows x86-64 Details
navaltoolbox-0.9.3-cp310-cp310-manylinux_2_28_x86_64.whl 3.2 MB CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64 Details
navaltoolbox-0.9.3-cp310-cp310-manylinux_2_28_aarch64.whl 3.1 MB CPython 3.10 CPython 3.10 Linux glibc 2.28+ ARM64 Details
navaltoolbox-0.9.3-cp310-cp310-manylinux_2_24_x86_64.whl 3.2 MB CPython 3.10 CPython 3.10 Linux glibc 2.24+ x86-64 Details
navaltoolbox-0.9.3-cp310-cp310-manylinux_2_24_aarch64.whl 3.1 MB CPython 3.10 CPython 3.10 Linux glibc 2.24+ ARM64 Details
navaltoolbox-0.9.3-cp310-cp310-macosx_11_0_arm64.whl 2.9 MB CPython 3.10 CPython 3.10 macOS 11.0+ ARM64 Details
navaltoolbox-0.9.3-cp39-cp39-win_amd64.whl 3.0 MB CPython 3.9 CPython 3.9 Windows x86-64 Details
navaltoolbox-0.9.3-cp39-cp39-manylinux_2_28_x86_64.whl 3.2 MB CPython 3.9 CPython 3.9 Linux glibc 2.28+ x86-64 Details
navaltoolbox-0.9.3-cp39-cp39-manylinux_2_28_aarch64.whl 3.1 MB CPython 3.9 CPython 3.9 Linux glibc 2.28+ ARM64 Details
navaltoolbox-0.9.3-cp39-cp39-manylinux_2_24_x86_64.whl 3.2 MB CPython 3.9 CPython 3.9 Linux glibc 2.24+ x86-64 Details
navaltoolbox-0.9.3-cp39-cp39-manylinux_2_24_aarch64.whl 3.1 MB CPython 3.9 CPython 3.9 Linux glibc 2.24+ ARM64 Details
navaltoolbox-0.9.3-cp39-cp39-macosx_11_0_arm64.whl 2.9 MB CPython 3.9 CPython 3.9 macOS 11.0+ ARM64 Details

Total release size: 91.9 MB

Release history Release notifications | RSS feed

This release

0.9.3 This release

31 release files

0.9.2

31 release files

0.9.1

31 release files

0.9.0

31 release files

0.8.0

31 release files

0.7.0

31 release files

0.6.4

31 release files

0.6.3

16 release files

0.6.2

16 release files

0.6.1

16 release files

0.6.0

16 release files

0.5.1

16 release files

0.4.3

16 release files

0.4.2

16 release files

0.4.1

16 release files

0.4.0

16 release files

0.3.0

16 release files

0.2.0

16 release files

0.1.0

16 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page