Skip to content

Contributing

Guidelines for contributing to OASIS.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. Create a feature branch: git checkout -b feature/my-feature
  4. Make your changes
  5. Build and test: compile.bat or compile.sh
  6. Run the functional tests: cd examples && run_all_examples.bat
  7. Push your branch and open a Pull Request

Code Style

OASIS uses clang-format for consistent formatting. The configuration is in .clang-format at the repository root.

Key conventions:

  • 4-space indentation, no tabs
  • Allman brace style (opening braces on new lines)
  • 120-column line width limit
  • C++17 standard
  • No automatic include sorting

Format your code before committing:

clang-format -i src/**/*.cpp src/**/*.hpp

The .editorconfig file ensures consistent settings across editors (UTF-8, LF line endings, trailing whitespace trimming).

Project Structure

src/                    # C++ source code
├── Simulations/        # Simulation orchestrator
├── Bodies/             # Rigid body dynamics
├── Lines/              # Mooring lines
├── BCPs/               # Boundary condition points
├── Waves/              # Wave kinematics
├── Hydro/              # Hydrodynamic forces
├── ODE_solvers/        # Time integration
├── Spring/             # Spring elements
└── ...
examples/               # Functional test suite
docs/                   # MkDocs documentation
resources/              # Python utilities

See Code Structure for the full class hierarchy and simulation lifecycle.

Adding a New Subsystem

  1. Create a new directory under src/ with header and source files
  2. Add the source files to CMakeLists.txt in the SOURCES list
  3. Integrate with Simulation class:
    • Add pointer member(s) to Simulation.hpp
    • Add Read*ASCII() and Read*YAML() methods
    • Wire into LoadCase(), Initialize(), CalculateSystemDynamics(), and CloseCase()
  4. Add input format documentation to docs/user-manual/
  5. Create a functional test in examples/

Adding Input Format Support

Both ASCII and YAML readers must be implemented for every input file. The Simulation class uses function pointers to dispatch:

// In constructor, based on data_format:
pReadMyFeature = &Simulation::ReadMyFeatureASCII;  // or ReadMyFeatureYAML

Testing

The functional test suite in examples/ covers all subsystems. After making changes:

  1. Build in Release mode
  2. Run all examples: cd examples && run_all_examples.bat
  3. Verify output against expected results

There are currently no unit tests. The examples serve as integration tests.

Documentation

  • User documentation: MkDocs files in docs/
  • API documentation: Generated by Doxygen from source comments
  • Theory manual: LaTeX in docs/theory-manual/OASIS_TheoryManual.tex

Build the docs locally:

pip install mkdocs-material
mkdocs serve

Commit Messages

Use clear, concise commit messages:

Add viscoelastic material model for mooring lines

Implements spring-dashpot stiffness model (flag_stiffness=1) with
parameters EA, EA_d, and alpha. Includes ASCII and YAML readers.