# 🌊 CONTRIBUTING TO HADEX

First off, thank you for considering contributing to HADEX! We welcome contributions from deep-sea researchers, oceanographers, marine biologists, geophysicists, robotics engineers, data scientists, and anyone passionate about understanding Earth's final frontier—the hadal zone.

---

## Code of Conduct

This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.

---

## Types of Contributions

### 🐟 Scientific Contributions
- New hadal datasets (bathymetry, sediment cores, CTD profiles)
- Pressure-dependent fluid mechanics models
- Acoustic propagation measurements (Mackenzie equation validation)
- Benthic oxygen flux data from lander deployments
- Turbidity current observations and transport models
- Bioluminescence recordings from hadal depths
- Microfossil assemblages and sedimentology
- Earthquake and subduction zone seismology

### 🤖 Robotics Contributions
- Swarm navigation algorithms for GPS-denied environments
- Cooperative acoustic ranging improvements
- Pressure-tolerant electronics designs
- Piezoelectric energy harvesting systems
- Autonomous underwater vehicle (AUV) control systems
- Sensor integration (oxygen, temperature, pressure, bioluminescence)
- Fault-tolerant swarm architectures

### 💻 Code Contributions
- HADEX core calculation engine improvements
- Parameter module development
- Real-time data ingestion pipelines
- Dashboard and visualization tools
- API extensions
- Alert system enhancements
- Pressure equation of state (Tait equation) refinements
- Acoustic model (Mackenzie equation) implementations

### 📊 Data Contributions
- Bathymetric surveys (multibeam, sub-bottom profiler)
- Sediment core data (physical properties, geochemistry)
- Benthic lander time series (oxygen, temperature, pressure)
- CTD profiles (conductivity, temperature, depth)
- Acoustic doppler current profiler (ADCP) data
- Earthquake and seismicity catalogs
- Biological observations (image data, specimen records)

### 📝 Documentation Contributions
- Tutorials and examples
- API documentation
- Parameter explanations
- Case study write-ups (trench expeditions)
- Translation of documentation
- User guides for researchers and expedition planners

---

## Getting Started

### Prerequisites
- **Python 3.8–3.11**
- **Git**
- **Basic knowledge of oceanography or fluid mechanics**

### Setup Development Environment

```bash
# Fork the repository, then clone
git clone https://gitlab.com/YOUR_USERNAME/HADEX.git
cd HADEX

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install development dependencies
pip install -e ".[dev]"
pre-commit install
```

Verify Setup

```bash
# Run basic validation
python scripts/validate_environment.py

# Run tests
pytest tests/unit/ -v

# Check pressure calculations
python scripts/check_pressure.py --depth 10911 --expected 110

# Test data ingestion
python scripts/test_data_sources.py --source gebco
```

---

Development Workflow

1. Create an issue describing your proposed changes
2. Fork and branch:
   ```bash
   git checkout -b feature/your-feature-name
   git checkout -b fix/issue-description
   git checkout -b parameter/new-parameter
   ```
3. Make changes following our standards
4. Write/update tests
5. Run tests locally
6. Commit with clear messages
7. Push to your fork
8. Open a Merge Request

---

Coding Standards

Python

· Format: Black (line length 88)
· Imports: isort with black profile
· Type Hints: Required for all public functions
· Docstrings: Google style

Example Parameter Module

```python
"""Hcr - Hydrostatic Compression parameter."""

from typing import Optional, Tuple
import numpy as np

from hadex.core import ParameterBase
from hadex.physics.tait import calculate_density


class HydrostaticCompression(ParameterBase):
    """Hcr: Rate of material compression under extreme pressure.
    
    Calculates density increase using Tait equation of state for seawater
    under hydrostatic pressure up to 110 MPa (11,000m depth).
    
    Attributes:
        P: Pressure [MPa]
        T: Temperature [°C]
        S: Salinity [PSU]
        rho0: Surface density [kg/m³]
    """
    
    def compute(self, depth_data: dict) -> float:
        """Compute normalized Hcr score.
        
        Args:
            depth_data: Dictionary with 'depth', 'temperature', 'salinity'
            
        Returns:
            Normalized Hcr value (0-1) where 1 = nominal compression at depth
        """
        # Implementation using Tait equation:
        # ρ(P,T,S) = ρ₀(T,S) / [1 - P / (B + n·P)]
        
        depth = depth_data['depth']  # meters
        temp = depth_data['temperature']  # °C
        salinity = depth_data['salinity']  # PSU
        
        # Convert depth to pressure (approx 10 MPa per 1000m)
        P = depth * 0.01007  # MPa
        
        # Tait equation parameters
        B = 305.0  # MPa (bulk modulus at zero pressure)
        n = 6.8     # dimensionless exponent
        
        # Surface density (simplified)
        rho0 = 1025.0 + 0.2 * salinity - 0.1 * temp
        
        # Density at depth
        rho = rho0 / (1 - P / (B + n * P))
        
        # Normalize (4.7% increase at Challenger Deep = 1.0)
        rho_increase = (rho - rho0) / rho0
        normalized = min(1.0, rho_increase / 0.047)
        
        return normalized
```

---

Testing Guidelines

Test Structure

```
tests/
├── unit/                    # Unit tests
│   ├── parameters/
│   │   ├── test_hcr.py
│   │   ├── test_nac.py
│   │   └── test_oflux.py
│   ├── models/
│   │   └── test_swarm.py
│   └── physics/
│       ├── test_tait.py
│       └── test_mackenzie.py
├── integration/             # Integration tests
│   ├── test_data_ingestion.py
│   └── test_hadex_pipeline.py
├── trenches/                # Trench validation
│   ├── test_challenger_deep.py
│   └── test_tonga_trench.py
└── fixtures/                # Test data
    ├── challenger_ctd.json
    └── sediment_cores.csv
```

Running Tests

```bash
# All tests
pytest

# Parameter tests
pytest tests/unit/parameters/ -v

# Trench validation
pytest tests/trenches/ -v --pressure-threshold 110

# With coverage
pytest --cov=hadex --cov-report=html
```

---

Data Contributions

New Data Source

When adding a new data source, include:

1. Source metadata (agency, vessel/station, location)
2. Data format specification (NetCDF, JSON, CSV)
3. Access method (API, FTP, public URL)
4. Update frequency (real-time, daily, expedition-based)
5. Quality control procedures
6. Validation against existing sources
7. Depth/pressure range coverage

Data Format Requirements

Parameter Source Format Required Fields
Hcr CTD profiles JSON/NetCDF depth, temperature, salinity, pressure
nac Acoustic surveys CSV sound_velocity, depth, time
Oflux Benthic landers CSV oxygen_concentration, depth, time
PEH Pressure sensors CSV pressure_amplitude, frequency, time
TTC ADCP/Multibeam NetCDF velocity, thickness, slope
CBL PMT detectors CSV intensity, wavelength, duration, time
Hts CTD profiles JSON temperature, depth, gradient
APD Swarm telemetry JSON position_x, position_y, position_z, time

---

Fieldwork Ethics

Any contribution involving fieldwork must:

1. Obtain all necessary permits for research in territorial waters and exclusive economic zones (EEZs)
2. Minimize environmental impact - avoid disturbing hadal ecosystems
3. Follow best practices for deep-sea sampling and observation
4. Share data openly with the scientific community
5. Acknowledge indigenous rights and traditional knowledge where applicable
6. Ensure safety of all personnel and equipment during deployments

Contact: fieldwork@hadex.space

---

Adding New Parameters

If you propose a new parameter for HADEX:

1. Literature review - Demonstrate physical relevance to hadal dynamics
2. Physical independence - Show correlation <0.3 with existing parameters
3. Measurement protocol - Define clear methodology and data source
4. Validation data - Provide dataset from hadal trenches
5. Weight proposal - Suggest initial weight (<10% typically for new parameters)
6. Computational cost - Estimate processing requirements
7. Pressure dependence - Show behavior across 0-110 MPa range

---

Reporting Issues

Bug Reports

Include:

· Clear title and description
· Steps to reproduce
· Expected vs actual behavior
· Environment details (OS, Python version)
· Logs or screenshots
· Data source and depth/timestamp if applicable

Feature Requests

Include:

· Use case description
· Expected behavior
· Scientific justification
· References to similar work
· Potential data sources
· Pressure/depth applicability

---

Contact

Purpose Contact
General inquiries gitdeeper@gmail.com
Code of Conduct conduct@hadex.space
Data contributions data@hadex.space
Scientific questions science@hadex.space
Fieldwork coordination fieldwork@hadex.space
Swarm robotics swarm@hadex.space

Repository: https://gitlab.com/gitdeeper8/HADEX
Dashboard: https://hadex.netlify.app
DOI: 10.5281/zenodo.18883858

---

🌊 The hadal zone is Earth's final frontier. HADEX illuminates the abyss.

Last Updated: March 2026
