navaltoolbox 0.2.0

High-performance naval architecture library for hydrostatics, stability, and tank calculations
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

# NavalToolbox

High-performance naval architecture library written in **Rust** with **Python bindings**.

## Architecture

NavalToolbox is built as a **Rust library** (`navaltoolbox`) with optional Python bindings via PyO3/Maturin. This architecture provides:

- ⚡ **High performance**: Rust's zero-cost abstractions and memory safety
- 🐍 **Python convenience**: Easy-to-use Python API for rapid prototyping
- 🔒 **Type safety**: Compile-time guarantees in Rust
- 🚀 **Production ready**: Deploy as Rust library or Python package

## Features

- **Hull geometry**: Load STL/VTK files, transform, scale, export
- **Multi-hull support**: Catamarans, trimarans, arbitrary configurations
- **Hydrostatics**: Volume, COB vector, Waterplane ($A_{wp}$, LCF, $BM_{t/l}$), Wetted Surface, Midship Area, LOS, Coefficients ($C_b, C_m, C_p$), Stiffness Matrix, Free Surface ($GM_{dry/wet}$)
- **Stability**: GZ curve calculation with trim optimization and downflooding detection
- **Complete stability analysis**: Combines hydrostatics, GZ curve, and wind heeling data
- **Tanks**: Fill level management, free surface effects
- **Silhouettes**: Wind heeling calculations (DXF/VTK support)

## Installation

### Python Package

```bash
pip install navaltoolbox
```

### Rust Library

Add to your `Cargo.toml`:

```toml
[dependencies]
navaltoolbox = "0.2"
```

## Quick Start

### Python

```python
from navaltoolbox import Hull, Vessel, HydrostaticsCalculator, StabilityCalculator

# Load a hull
hull = Hull("ship.stl")
print(f"Bounds: {hull.get_bounds()}")

# Create a vessel
vessel = Vessel(hull)

# Calculate hydrostatics
# Calculate hydrostatics
calc = HydrostaticsCalculator(vessel, water_density=1025.0)

# Option 1: At draft with VCG
state = calc.calculate_at_draft(5.0, vcg=6.0)
print(f"Volume: {state.volume:.1f} m³")
print(f"Waterplane Area: {state.waterplane_area:.1f} m²")
print(f"GMT (wet): {state.gmt:.3f} m")

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

# Calculate GZ curve
stab = StabilityCalculator(vessel, water_density=1025.0)
heels = [0, 10, 20, 30, 40, 50, 60]
curve = stab.calculate_gz_curve(
    displacement_mass=1000000,
    cog=(50.0, 0.0, 5.0),
    heels=heels
)
for heel, gz in zip(curve.heels(), curve.values()):
    print(f"Heel: {heel}°, GZ: {gz:.3f}m")

# Complete stability analysis (hydrostatics + GZ + wind data)
result = stab.calculate_complete_stability(
    displacement_mass=1000000,
    cog=(50.0, 0.0, 5.0),
    heels=heels
)
print(f"GM0: {result.gm0:.3f}m")
print(f"Max GZ: {result.max_gz:.3f}m at {result.heel_at_max_gz}°")
```

### Rust

```rust
use navaltoolbox::{Hull, Vessel, HydrostaticsCalculator, StabilityCalculator};

// Load a hull
let hull = Hull::from_stl("ship.stl")?;
println!("Bounds: {:?}", hull.get_bounds());

// Create a vessel
let vessel = Vessel::new(hull);

// Calculate hydrostatics
let calc = HydrostaticsCalculator::new(&vessel, 1025.0);
let state = calc.calculate_at_draft(5.0, 0.0, 0.0, 0.0)?;
println!("Volume: {} m³", state.volume);

// Calculate GZ curve
let stab = StabilityCalculator::new(&vessel, 1025.0);
let heels = vec![0.0, 10.0, 20.0, 30.0, 40.0, 50.0, 60.0];
let curve = stab.calculate_gz_curve(1000000.0, [50.0, 0.0, 5.0], &heels);
for point in &curve.points {
    println!("Heel: {}°, GZ: {:.3}m", point.heel, point.value);
}
```

## Development

### Building from Source

```bash
# Build Rust library
cd rust
cargo build --release

# Build Python package
cd python
maturin develop --release
```

## License

AGPL-3.0-or-later

## 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.

## Author

[Antoine ANCEAU](https://github.com/antoineanceau) · [Website](https://antoine.anceau.fr)