oilspillsim 0.0.3

First package version of Oil Spill simulator

cpp_py_oil_simulator

A C++ oil spill simulator with Python bindings (pybind11). This repository provides a performant core simulator written in C++ and a small pybind11 wrapper so the simulator can be used from Python as the oilspillsim package.

Highlights

• Core numerical code uses Eigen for linear algebra (bundled under src/Eigen).
• Python bindings implemented in src/utils/pywrap/pywrap.cpp using pybind11.
• Minimal example and utilities live under src/ and utils/.

Quick install

Install using pip from the project root:

pip install .

This builds the extension module (oilspillsim) with pybind11. Ensure you have a C++ toolchain and CMake available on your platform.

Build (developer)

Build the native extension directly using the provided CMake and setuptools integration:

# from project root
pip install -e .

Or build with CMake in src/ (native build):

mkdir -p build && cd build
cmake ../src
cmake --build .

Usage (Python)

After installation the package exposes the oilspillsim extension module. Example (the exact API is defined in the pybind wrapper):

import oilspillsim

# Create simulator (example — check `src/utils/pywrap/pywrap.cpp` for real args)
sim = oilspillsim.oilspillsim("src/mapas/defuniak_map.csv")
sim.step()
density = sim.get_normalized_density()

Accessible functions (API)

The oilspillsim extension exposes a class named oilspillsim (C++ type SIMULATOR). Below is a concise summary of constructors, methods and read-only attributes provided by the pybind11 wrapper. For exact function signatures and default values see src/utils/pywrap/pywrap.cpp.

• Class: oilspillsim (C++: SIMULATOR)

  • Constructor:

    • oilspillsim(_filepath: str, **kwargs)
      • Create the simulator by loading a map from a file (CSV or supported format by the core).
    • oilspillsim(base_matrix: numpy.ndarray or Eigen::MatrixXi, **kwargs)
      • Create the simulator from an in-memory base matrix (map, usually a 2D array, 0 for obstacle 1 for valid position).

  • Contructor kwargs:

    • _dt: (float=10.0) internal time variable. Each time oilspillsim.step() is called, particles will move relative to this.
    • _kw: (float=0.5) wind gain. wind component affecting particles is weighted by this value
    • _kc: (float=1.0) current gain. current components affecting particles are weighted by this value.
    • _gamma: (float=1.0) brownian movement gain. Random movement due to particle intereffects are weighet by this value
    • _flow: (float=50.0) ammount of particles liberated to the environment normalized for _dt =1 at each sourcepoint
    • _number_of_sources: (int=3) ammount of sources that liberate oil to the environment
    • _max_contamination_value: (int=5) value to dictate maximun concentration of contamination per node. No more than "_max_contamination_value" particles can be present in the same node.
    • _source_fuel: (int=1000) maximum fuel a source can liberate to the environment, once a source liberates "_source_fuel" particles, it stops liberating
    • _random_seed: (int=-1) seed to relive experiments, leave to -1 to allways use a different seed
    • _triangular: (bool=False) special condition promoving a different particle behaviour where particles moves following a cross shape.

  • Main methods:

    • step()
      • Advance the simulation by one time step. The GIL is released during execution for performance.
    • reset(_seed: int = -1, Eigen::MatrixXi _source_points_pos)
      • Reset the simulation state. If _seed is provided the RNG is seeded for reproducibility. -1 used for random seed.
      • If _source_points_pos is provided, source points will take chosen position, otherwise seed source points will be taken
    • get_normalized_density(gaussian: bool = True) -> numpy.ndarray
      • Return the normalized density matrix (optionally smoothed using a Gaussian kernel if gaussian=True).

  • Read-only attributes (accessible from Python):

    • source_points — coordinates of contamination sources (list/array).
    • contamination_position — array containing all the discrete particles positions (list/array).
    • density — raw hydrocarbon density matrix (not normalized).
    • x, y — spatial coordinate vectors associated with the grid.
    • u, v — velocity fields (x/y components) used by the simulation to simulate currents (array).
    • wind_speed — wind speed value or field used in the model (array(2)).

Notes:

• For exact signatures and default values check src/utils/pywrap/pywrap.cpp.
• Exposed structures (for example Eigen matrices) are converted to/from NumPy arrays via pybind11/eigen.h.

Tests

There is a small test script used by CI in src/tests/test.py (also referenced in pyproject.toml) accesible from github. Run it with:

python src/tests/test.py

Contributing

Contributions and bug reports are welcome. Please open issues or pull requests on the GitHub repository: https://github.com/AloePacci/cpp_oil_simulator

Authors

Alejandro Casado Pérez — [e-mail]

Acknowledgements: Samuel Yanes Luis (help and guidance).

License

This project is provided under the terms in LICENSE.