MarEnv

Calculations pertaining to marine environment processes and properties, such as waves, wind, seafloor and ocean currents. Particularly aimed at facilitating syncronised environment representations between models within distributed simulations.

Contents

• What is this?
• Features
• Why should I use this?
• Getting started
• Contribute
• License

What is this?

When simulation models depending on a marine environment are distributed between multiple computers, several issues arise. Most notably, how can one keep time dependent processes, such as wave patterns, syncronised between exchange of information between models? This library seeks to solve this challenge by implementing predefined and deterministic environment models. This implementation includes methods for querying e.g. particle velocities, surface elevation for a given time and position. The main idea is that the environment is specified in terms of constant or slowly varying definitions, which the models feed their local marenv instance. Subsequent queries for e.g. particle velocities will then give the same results in the different models, without requiring further communication. These queries will then be valid and in sync until the environment is changed.

The current implementation does not include transitions between an existing and a new environment state, but this will be included in a future version.

Features

• [x] No dependencies
• [x] Open source and permissive license
• [x] Syncronised environment states
• [x] Wave models:
  • [x] Linear waves (Airy theory)
  • [x] Gerstner waves
• [ ] Wind
• [ ] Seafloor
• [ ] Effects on the environment from e.g. ships and structures.
• [ ] Syncronised transitions between environment states

Why should I use this?

The aim is for this implementation to be easy to use, with as few dependencies as possible and open source. It aims at providing a standard for the handling of marine environments in distributed simulations, but it should be well suited for use in other situations where marine environment calculations are needed. To support syncronised environments between computers and processes, a pseudorandom number generator is implemented.

Using the library

The Marine Environment Agent System provides a single API to query marine environmental conditions — combining waves, currents, and seafloor data in one call.

Conan is the preferred way of using this library. The package is usually consumed using the conan install command or a conanfile.txt.

1. Add remote to conan's package remotes:

   conan remote add sintef-public https://packages.smd.sintef.no

2. Using conanfile.txt in your project with cmake

   Add conanfile.txt:

   [requires]
   marenv/[>=0.0.1]@sintef/stable
    
   [options]
   marenv/*:shared=False   # default
   marenv/*:with_doc=True  # default
    
   [generators]
   CMakeDeps
   CMakeToolchain

   Insert into your CMakeLists.txt something like the following lines:

   cmake_minimum_required(VERSION 3.15)
   project(TheProject CXX)
    
   find_package(marenv CONFIG REQUIRED)
    
   add_executable(the_executor code.cpp)
   target_link_libraries(the_executor marenv::marenv)

   Install and build:

   conan install . -s build_type=<build_type> -pr:b=default

   where <build_type> is e.g. Debug or Release. You can now continue with the usual cmake commands for configuration and compilation, provided that you point to the toolchain file when running the cmake commands. For details on how to use conan, please consult Conan.io docs

Interfaces and their implementations

Marenv aims to provide a full set of interfaces, and a minimum set of implementations. This allows for proprietary implementations being used without its source code. Currently, the emphasis is placed on linear wave models. These create sea states by superpositioning of multiple wave components. There are three implementations:

• AiryWavesScalar implements the airy wave theory. This implementation favors few wave components.
• AiryWaves implements the airy wave theory using SIMD (Single Instruction Multiple Data). This implementation is more efficient for many wave components.
• GerstnerWaves implements Gerstner wave theory. These waves are more accurate, but they are also more computational demanding.

The seafloor implementation defines the depths as a combination of harmonic variations.

There are three implementations of ocean currents:

• ConstantCurrent defines a current independent of time and position.
• DepthVaryingCurrent defines a current varying with depth only.
• DepthVaryingCurrentField defines a current varying with both depth and position.

Basic Usage Example

#include <memory>
#include "EnvironmentAgent.hpp"
#include "WaveInterface.hpp"
#include "CurrentInterface.hpp"
#include "BathymetryInterface.hpp"
 
int main() {
    using namespace marenv::agent;
 
    // Create model instances
    std::shared_ptr<WaveInterface> wave = std::make_shared<MyWaveModel>();
    std::shared_ptr<CurrentInterface> current = std::make_shared<MyCurrentModel>();
    std::shared_ptr<BathymetryInterface> bathy = std::make_shared<MyBathymetryModel>();
 
    // Build environment
    EnvironmentAgent env;
    env.SetWaveAgent(wave);
    env.SetCurrentAgent(current);
    env.SetBathymetryAgent(bathy);
 
    // Query example
    double time = 12.0;
    double position[3] = {50.0, 100.0, -5.0};
    double velocity[3];
    env.GetParticleVelocity(time, position, velocity);
 
    std::cout << "Particle velocity: ("
              << velocity[0] << ", "
              << velocity[1] << ", "
              << velocity[2] << ")" << std::endl;
}

Coordinate system, directions and units

This library uses a right-handed coordinate system with the x-axis pointing East, the y-axis pointing North and the z-axis pointing Down. Depths are therefore positive below mean sea level. Note that the wave elevation is positive upwards. Wave elevation is not the z-position of the surface, but rather the local elevation of the surface.

The units used are SI units if nothing else is obvious from the naming of variables or functions.

Key Functions

Method	Description
GetSurfaceElevation()	Returns free-surface elevation (η).
GetParticleVelocity()	Returns total particle velocity (waves + currents).
GetPressure()	Returns dynamic pressure at depth.
GetSeadepth()	Returns seafloor depth at a position.
PointEnvironmentQuery()	Returns multiple quantities in one call.

Return Codes

All agent functions return a status from the AgentReturn enum:

Code	Meaning
AgentReturn::OK	Operation successful.
AgentReturn::OUT_OF_RANGE_INACCURATE	Query outside valid range — returned value may be approximate.
AgentReturn::NOT_APPLICABLE_NOT_SET	Data not applicable or not configured.
AgentReturn::ERROR_NOT_SET	Operation failed, no valid data available.
AgentReturn::NOT_IMPLEMENTED	Function not yet implemented in the agent.

Developing the library

Building this repository locally can be done with conan using the following commands.

1. To build into subfolder folder of repository (marenv).

   cd marenv
   conan build . -o marenv/*:with_doc=False -c tools.build:skip_test=False -b missing

   This builds the library without doc and tests into build (Windows) or build/<build_type> (Linux). Subsequent builds can be done using cmake commands.

2. To create a package in the local conan cache.

   cd marenv
   conan create . --user sintef --channel marenv -b missing -o marenv/*:shared=False

Package options

Option	Allowed values	Default value
shared	[True, False]	False
fPIC	[True, False]	True
with_doc	[True, False]	True

Code overview

The marenv::agent namespace defines abstract interfaces and a composite agent architecture for modeling and querying marine environment data.
Each physical aspect of the environment is represented by a dedicated interface:

Interface	Purpose
WaveInterface	Computes wave-induced quantities (e.g., surface elevation, velocities, pressures).
CurrentInterface	Provides current velocity fields.
BathymetryInterface	Represents seafloor geometry and material properties.
EnvironmentInterface	Unified interface combining waves, currents, and bathymetry.
EnvironmentAgent	Concrete class delegating calls to individual sub-agents.

Directory Structure

The most important part of the directory structure is shown below. The marenv/include/marenv directory contains the public API of the project.

marenv
├── include
│   └── marenv
│       ├── agent
│       ├── calc
│       ├── current
│       ├── seafloor
│       └── wave
├── src
│   ├── agent
│   ├── calc
│   ├── current
│   ├── seafloor
│   └── wave

Contribute

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate.

Development Guidelines

• Each new environment model should implement the relevant interface.
• Always return an appropriate AgentReturn value to indicate query validity.
• Use smart pointers (std::shared_ptr) for agent ownership.
• Extend EnvironmentAgent when combining additional phenomena (e.g., temperature, salinity).

License

MIT