# 🔌 HADEX API Reference

## Core API

### EquationOfState

```python
from hadex.core import EquationOfState

eos = EquationOfState(temperature=1.9, salinity=34.68, pressure=110.2)

# Calculate density
density = eos.compute_density()  # Returns: 1048.7 kg/m³

# Calculate compression ratio
compression = eos.compression_ratio()  # Returns: 0.047 (4.7%)

# Get pressure at depth
pressure = eos.pressure_at_depth(depth=10911)  # Returns: 110.2 MPa
```

AcousticModel

```python
from hadex.core import AcousticModel

acoustic = AcousticModel(temperature=1.9, salinity=34.68, depth=10911)

# Calculate sound velocity
c = acoustic.sound_speed()  # Returns: 1663.8 m/s

# Calculate travel time
time = acoustic.travel_time(distance=5000)  # Returns: 3.005 seconds

# Get refraction index
refraction = acoustic.refraction_index()  # Returns: 1.109
```

PressureViscosity

```python
from hadex.core import PressureViscosity

visc = PressureViscosity(temperature=1.9)

# Calculate dynamic viscosity
mu = visc.dynamic_viscosity(pressure=110.2)  # Returns: 2.18e-3 Pa·s

# Calculate Reynolds number
re = visc.reynolds_number(velocity=0.25, diameter=0.01)  # Returns: 470

# Get drag coefficient
cd = visc.drag_coefficient(reynolds=470)  # Returns: 1.32
```

Navigation API

SwarmNavigationEngine

```python
from hadex.navigation import SwarmNavigationEngine

# Initialize 12-vehicle swarm
swarm = SwarmNavigationEngine(
    num_vehicles=12,
    acoustic_frequency=12000,  # Hz
    max_range=500  # meters
)

# Run 72-hour mission simulation
trajectory = swarm.simulate_mission(
    duration_hours=72,
    depth=10911,
    survey_area=500  # meters
)

# Get current positions
positions = swarm.get_positions()  # Returns array of (x,y,z)

# Calculate positioning accuracy
accuracy = swarm.position_accuracy()  # Returns RMS error in meters

# Handle vehicle loss
swarm.reconfigure(active_vehicles=11)  # Graceful degradation
```

PositionEstimator

```python
from hadex.navigation import PositionEstimator

estimator = PositionEstimator()

# Multi-lateration from acoustic ranges
position = estimator.solve(
    ranges=[125.3, 142.7, 98.2, 167.1],
    anchor_positions=[[0,0,0], [100,0,0], [0,100,0], [0,0,100]]
)

# Kalman filter update
filtered = estimator.kalman_update(
    measurement=position,
    uncertainty=0.8
)

# Outlier rejection
cleaned = estimator.reject_outliers(
    measurements=all_ranges,
    threshold=3.0  # sigma
)
```

AdaptiveRanging

```python
from hadex.navigation import AdaptiveRanging

ranging = AdaptiveRanging()

# Correct sound velocity from CTD
corrected_c = ranging.correct_sound_velocity(
    measured_c=1663.8,
    temperature=1.9,
    salinity=34.68,
    depth=10911
)

# Calculate corrected range
range_m = ranging.calculate_range(
    time_of_flight=3.005,
    sound_velocity=corrected_c
)

# Detect thermocline anomaly
anomaly = ranging.detect_anomaly(
    measurements=range_history,
    threshold=0.5  # meters
)
```

BioNavigation

```python
from hadex.navigation import BioNavigation

bio_nav = BioNavigation()

# Detect bioluminescence event
event = bio_nav.detect_event(
    intensity=8.2e4,
    wavelength=472,
    duration=1.2
)

# Use as navigation beacon
position_improvement = bio_nav.correction_factor(
    event_position=[125.3, 142.7, 10911],
    current_uncertainty=0.8
)  # Returns: 0.6 (30% improvement)

# Map bioluminescence hotspots
hotspots = bio_nav.map_hotspots(
    events=event_history,
    cluster_threshold=50  # meters
)
```

Sensing API

OxygenFlux

```python
from hadex.sensing import OxygenFlux

oxygen = OxygenFlux()

# Measure oxygen concentration
conc = oxygen.measure_concentration(
    depth=10911,
    sediment_type="sandy"
)  # Returns: 195 μM

# Calculate penetration depth
penetration = oxygen.penetration_depth(
    profiles=vertical_measurements
)  # Returns: 3.7 cm

# Map spatial heterogeneity
heterogeneity = oxygen.spatial_variability(
    grid=survey_grid,
    resolution=50  # meters
)  # Returns: 21%
```

TurbidityCurrents

```python
from hadex.sensing import TurbidityCurrents

turbidity = TurbidityCurrents()

# Detect current event
event = turbidity.detect_current(
    backscatter_intensity=-78.3,  # dB
    threshold=-80.0
)

# Calculate transport velocity
velocity = turbidity.transport_velocity(
    slope=4.2,  # degrees
    sediment_density=1050  # kg/m³
)  # Returns: 1.5 m/s

# Classify deposit type
deposit = turbidity.classify_deposit(
    thickness=8,  # cm
    grading="normal",
    extent=[127, 83]  # meters
)
```

BioluminescenceDetector

```python
from hadex.sensing import BioluminescenceDetector

detector = BioluminescenceDetector(
    wavelength_range=[400, 600]  # nm
)

# Measure light emission
emission = detector.measure(
    sample_rate=100,  # Hz
    duration=3600  # seconds
)

# Spectral analysis
spectrum = detector.spectral_analysis(
    emission=emission_data
)  # Returns peak at 472 nm

# Classify organism type
organism = detector.classify_source(
    wavelength=472,
    duration=1.2,
    intensity=8.2e4
)
```

PressureSensing

```python
from hadex.sensing import PressureSensing

pressure_sensor = PressureSensing(
    range=[0, 120]  # MPa
)

# Measure ambient pressure
P = pressure_sensor.measure(depth=10911)  # Returns: 110.2 MPa

# Detect fluctuations
fluctuations = pressure_sensor.detect_oscillations(
    sample_rate=10,  # Hz
    duration=3600  # seconds
)

# Classify source (microseism vs turbidity)
source = pressure_sensor.classify_source(
    amplitude=2000,  # Pa
    frequency=0.05  # Hz
)
```

Energy API

PiezoHarvester

```python
from hadex.energy import PiezoHarvester

harvester = PiezoHarvester(
    material="PZT-5H",
    area=10,  # cm²
    d33=650  # pC/N
)

# Calculate power output
power = harvester.calculate_power(
    stress=2000,  # Pa
    frequency=0.05  # Hz
)  # Returns: 3.2 mW

# Measure actual power
measured = harvester.measure_power(
    duration=28800  # 8 hours in seconds
)  # Returns: 2.8 ± 0.4 mW

# Optimize for conditions
optimized = harvester.optimize(
    frequency_range=[0.01, 1.0],  # Hz
    stress_range=[100, 5000]  # Pa
)
```

EnergyStorage

```python
from hadex.energy import EnergyStorage

storage = EnergyStorage(
    battery_capacity=180,  # Wh
    capacitor=0.1  # F
)

# Check state of charge
soc = storage.state_of_charge()  # Returns: 85%

# Manage power flow
power_available = storage.manage_power(
    harvested=2.8e-3,  # W
    load=1.0e-3  # W
)

# Buffer fluctuations
smoothed = storage.buffer_fluctuations(
    input_power=power_series,
    time_constant=60  # seconds
)
```

PowerBudget

```python
from hadex.energy import PowerBudget

budget = PowerBudget(
    mission_duration=72,  # hours
    baseline_power=2.5  # W
)

# Calculate energy requirements
required = budget.calculate_requirements(
    sensors=["oxygen", "pressure", "acoustic"],
    sampling_rate=0.1  # Hz
)

# Add harvesting contribution
with_harvesting = budget.add_harvesting(
    harvested_power=2.8e-3,  # W
    harvesting_duty_cycle=0.8
)

# Check mission feasibility
feasible = budget.check_feasibility()  # Returns: True
```

Robotics API

AUVController

```python
from hadex.robotics import AUVController

auv = AUVController(
    vehicle_id=1,
    swarm_size=12
)

# Set mission waypoints
auv.set_waypoints([
    [0, 0, 10911],
    [100, 0, 10911],
    [100, 100, 10911],
    [0, 100, 10911]
])

# Execute survey pattern
auv.lawnmower_survey(
    area_size=500,  # meters
    transect_spacing=50,  # meters
    altitude=5  # meters
)

# Emergency procedures
if auv.alert_level == "CRITICAL":
    auv.emergency_ascent()
```

ThrusterModel

```python
from hadex.robotics import ThrusterModel

thruster = ThrusterModel(
    viscosity=2.18e-3,  # Pa·s
    density=1048.7  # kg/m³
)

# Calculate thrust
thrust = thruster.calculate_thrust(
    rpm=1200,
    diameter=0.05  # meters
)

# Compensate for viscosity
compensated_rpm = thruster.viscosity_compensation(
    required_velocity=0.25,  # m/s
    depth=10911
)

# Power consumption
power = thruster.power_required(
    thrust=thrust,
    efficiency=0.7
)
```

BuoyancyControl

```python
from hadex.robotics import BuoyancyControl

buoyancy = BuoyancyControl(
    vehicle_mass=8.2,  # kg
    displacement=0.008  # m³
)

# Calculate buoyancy at depth
force = buoyancy.calculate_buoyancy(
    depth=10911,
    water_density=1048.7
)

# Adjust for pressure compression
adjusted = buoyancy.pressure_compensation(
    pressure=110.2,  # MPa
    foam_density=600  # kg/m³
)

# Maintain neutral buoyancy
buoyancy.maintain_neutral(
    depth=10911,
    control_rate=0.1  # Hz
)
```

AcousticCommunication

```python
from hadex.robotics import AcousticCommunication

comm = AcousticCommunication(
    frequency=12000,  # Hz
    bandwidth=1000,  # Hz
    range=500  # meters
)

# Send message
comm.send(
    destination_id=2,
    message_type="position",
    data=[125.3, 142.7, 10911]
)

# Receive broadcast
messages = comm.receive(
    timeout=30,  # seconds
    filter_sender=None
)

# Calculate link budget
snr = comm.link_budget(
    distance=450,  # meters
    power=10,  # W
    noise_level=-80  # dB
)
```

Utilities API

DataPipeline

```python
from hadex.utils import DataPipeline

pipeline = DataPipeline()

# Load CTD data
ctd_data = pipeline.load_ctd(
    source="noaa",
    trench="challenger",
    time_range=["2024-01-01", "2024-12-31"]
)

# Process bathymetry
bathymetry = pipeline.process_bathymetry(
    resolution="15s",  # arc-seconds
    format="netcdf"
)

# Merge datasets
merged = pipeline.merge(
    datasets=[ctd_data, bathymetry],
    on="coordinates"
)
```

Visualization

```python
from hadex.utils import Visualization

viz = Visualization()

# Plot 3D swarm trajectory
viz.plot_trajectory(
    positions=swarm_history,
    colors=['red', 'blue', 'green'],
    title="Swarm Mission 72h"
)

# Map oxygen flux
viz.map_oxygen_flux(
    grid=oxygen_grid,
    resolution=50,  # meters
    colormap='viridis'
)

# Animate bioluminescence events
viz.animate_events(
    events=bioluminescence_events,
    timespan=56,  # hours
    output='bioluminescence.mp4'
)
```

Validation

```python
from hadex.utils import Validation

validation = Validation()

# Validate against Challenger Deep data
results = validation.validate_trench(
    trench_name="challenger",
    predicted=model_predictions,
    measured=field_data
)

# Calculate error metrics
metrics = validation.error_metrics(
    predicted=density_predictions,
    measured=density_measurements
)  # Returns: {'mae': 0.3, 'rmse': 0.4, 'r2': 0.99}

# Generate validation report
validation.generate_report(
    results=results,
    output_format="pdf",
    destination="reports/validation.pdf"
)
```

MissionLogger

```python
from hadex.utils import MissionLogger

logger = MissionLogger(
    mission_name="challenger_deep_2024",
    log_level="INFO"
)

# Log sensor readings
logger.log_sensor(
    sensor_type="pressure",
    value=110.2,
    unit="MPa",
    timestamp="2024-03-06T12:00:00Z"
)

# Log navigation events
logger.log_navigation(
    event_type="position_update",
    position=[125.3, 142.7, 10911],
    uncertainty=0.8
)

# Log alerts
logger.log_alert(
    level="WATCH",
    message="Thermocline detected at 10400m",
    severity=3
)

# Export mission log
logger.export(
    format="json",
    destination="logs/mission_2024.json"
)
```

