From e280db3539f25f4c8795d95dbcd6f510e4f24bc2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vicente=20Mataix=20Ferr=C3=A1ndiz?= Date: Tue, 26 May 2026 10:10:01 +0200 Subject: [PATCH 1/3] [Doc] Extend the README with installation instructions --- README.md | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) diff --git a/README.md b/README.md index a01708c4..ac6ee20b 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,210 @@ The _CoSimIO_ supports pure sequential and mpi-parallel executions. Shared memor ## Memory Management Coupling requires frequent exchange of data. Therefore the _CoSimIO_ uses the memory provided by the including solvers/software-tools directly, without copying it to an auxiliar data structure. +## Installation + +### Manual Installation + +If you prefer not to use Spack, _CoSimIO_ can be built and installed manually using [CMake](https://cmake.org/). + +#### Prerequisites + +- A C++11 compatible compiler (GCC, Clang, MSVC, etc.) — see the full list [here](https://en.cppreference.com/w/cpp/compiler_support#cpp11) +- [CMake](https://cmake.org/) ≥ 3.15 +- _(Optional)_ An MPI implementation (e.g. [OpenMPI](https://www.open-mpi.org/), [MPICH](https://www.mpich.org/)) for `+mpi` support +- _(Optional)_ [Python](https://www.python.org/) ≥ 3.6 and [pybind11](https://github.com/pybind/pybind11) for Python bindings +- _(Optional)_ A Fortran compiler for the Fortran API + +--- + +#### 1. Clone the Repository + +```bash +git clone https://github.com/KratosMultiphysics/CoSimIO.git +cd CoSimIO +``` + +Or download a specific release tarball: + +```bash +wget https://github.com/KratosMultiphysics/CoSimIO/archive/refs/tags/v4.3.1.tar.gz +tar -xzf v4.3.1.tar.gz +cd CoSimIO-4.3.1 +``` + +--- + +#### 2. Configure with CMake + +Create a build directory and run CMake: + +```bash +mkdir build && cd build +cmake .. +``` + +The following CMake options are available to control what gets built: + +| CMake Option | Default | Description | +|---|---|---| +| `CO_SIM_IO_BUILD_C` | `ON` | Build the C API | +| `CO_SIM_IO_BUILD_PYTHON` | `OFF` | Build Python bindings | +| `CO_SIM_IO_BUILD_FORTRAN` | `OFF` | Build the Fortran API | +| `CO_SIM_IO_BUILD_TESTING` | `OFF` | Build the test suite | +| `CO_SIM_IO_BUILD_MPI` | `OFF` | Enable MPI communication | +| `CO_SIM_IO_STRICT_COMPILER` | `OFF` | Enable strict compiler warnings | + +For example, to enable MPI and Python bindings: + +```bash +cmake .. \ + -DCMAKE_BUILD_TYPE=Release \ + -DCO_SIM_IO_BUILD_MPI=ON \ + -DCO_SIM_IO_BUILD_PYTHON=ON +``` + +To specify a custom install prefix: + +```bash +cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install +``` + +> **Note:** The Fortran API depends on the C API. Always enable `CO_SIM_IO_BUILD_C=ON` when building with `CO_SIM_IO_BUILD_FORTRAN=ON`. + +--- + +#### 3. Build + +```bash +cmake --build . --config Release +``` + +To speed up compilation using multiple cores: + +```bash +cmake --build . --config Release -- -j$(nproc) +``` + +> On macOS, replace `$(nproc)` with `$(sysctl -n hw.logicalcpu)`. + +--- + +#### 4. Install + +```bash +cmake --install . +``` + +If a custom prefix was specified during configuration, the libraries and headers will be placed there. Otherwise the default system prefix (e.g. `/usr/local`) is used. + +--- + +#### 5. Verify the Installation + +After installation, confirm that the shared library is present: + +```bash +ls /path/to/install/lib/libCoSimIO* +``` + +If Python bindings were built, verify the module is importable: + +```bash +python3 -c "import CoSimIO; print('CoSimIO imported successfully')" +``` + +--- + +#### Platform-Specific Notes + +| Platform | Notes | +|---|---| +| **Linux** | Ensure `/path/to/install/lib` is on `LD_LIBRARY_PATH` | +| **macOS** | Ensure `/path/to/install/lib` is on `DYLD_LIBRARY_PATH` | +| **Windows** | Ensure `/path/to/install/bin` is on `PATH`; use the Visual Studio generator with `-G "Visual Studio 17 2022"` | + +### Installing with Spack + +This section describes how to install _CoSimIO_ using [Spack](https://spack.io/), a flexible package manager designed for HPC environments. First, make sure Spack is available in your environment: + +```bash +git clone --depth=1 https://github.com/spack/spack.git +source spack/share/spack/setup-env.sh +``` + +Then install _CoSimIO_ with the default configuration: + +```bash +spack install cosimio +``` + +--- + +### Variants + +The Spack package exposes several build variants that allow you to tailor the installation to your needs: + +| Variant | Default | Description | +|---|---|---| +| `+mpi` / `~mpi` | `~mpi` | Enable MPI-parallel communication | +| `+c` / `~c` | `+c` | Build the C API | +| `+python` / `~python` | `~python` | Build Python bindings (requires Python ≥ 3.6) | +| `+fortran` / `~fortran` | `~fortran` | Build the Fortran API (requires `+c`) | +| `+testing` / `~testing` | `~testing` | Build the test suite | +| `+strict` / `~strict` | `~strict` | Enable strict compiler warnings | + +> **Note:** The Fortran API is built on top of the C API. Enabling `+fortran` without `+c` is not allowed. + +#### Examples + +Install with MPI support: + +```bash +spack install cosimio+mpi +``` + +Install with Python bindings: + +```bash +spack install cosimio+python +``` + +Install with C, Fortran, and MPI support: + +```bash +spack install cosimio+c+fortran+mpi +``` + +Install a specific version: + +```bash +spack install cosimio@4.3.1 +``` + +--- + +### Loading the Package + +Once installed, load _CoSimIO_ into your environment with: + +```bash +spack load cosimio +``` + +--- + +### Dependencies + +Spack resolves all dependencies automatically. For reference, the following are pulled in depending on the chosen variants: + +| Dependency | When required | +|---|---| +| `cmake@3.15:` | Always (build only) | +| `mpi` | `+mpi` | +| `python@3.6:` | `+python` | +| `py-pybind11` | `+python` (build only) | +| Fortran compiler | `+fortran` | + ## Special Thanks To - [Boost](http://www.boost.org/) for the `intrusive_ptr` - [pybind11](https://github.com/pybind/pybind11) for exposing C++ to python From 6793151457cbeffabe59059d1506ec6705fc00e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vicente=20Mataix=20Ferr=C3=A1ndiz?= Date: Tue, 26 May 2026 11:17:47 +0200 Subject: [PATCH 2/3] Moving to `doc` --- docs/build_options.md | 186 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) diff --git a/docs/build_options.md b/docs/build_options.md index a20d3a37..936c3907 100644 --- a/docs/build_options.md +++ b/docs/build_options.md @@ -28,3 +28,189 @@ Building the CoSimIO with the following configuration: CO_SIM_IO_BUILD_FORTRAN: ON CO_SIM_IO_STRICT_COMPILER: ON ~~~ + +## Installation + +### Manual Installation + +If you prefer not to use Spack, _CoSimIO_ can be built and installed manually using [CMake](https://cmake.org/). + +#### Prerequisites + +- A C++11 compatible compiler (GCC, Clang, MSVC, etc.) — see the full list [here](https://en.cppreference.com/w/cpp/compiler_support#cpp11) +- [CMake](https://cmake.org/) ≥ 3.15 +- _(Optional)_ An MPI implementation (e.g. [OpenMPI](https://www.open-mpi.org/), [MPICH](https://www.mpich.org/)) for `+mpi` support +- _(Optional)_ [Python](https://www.python.org/) ≥ 3.6 and [pybind11](https://github.com/pybind/pybind11) for Python bindings +- _(Optional)_ A Fortran compiler for the Fortran API + +#### 1. Clone the Repository + +```bash +git clone https://github.com/KratosMultiphysics/CoSimIO.git +cd CoSimIO +``` + +Or download a specific release tarball: + +```bash +wget https://github.com/KratosMultiphysics/CoSimIO/archive/refs/tags/v4.3.1.tar.gz +tar -xzf v4.3.1.tar.gz +cd CoSimIO-4.3.1 +``` + +#### 2. Configure with CMake + +Create a build directory and run CMake: + +```bash +mkdir build && cd build +cmake .. +``` + +The following CMake options are available to control what gets built: + +| CMake Option | Default | Description | +|---|---|---| +| `CO_SIM_IO_BUILD_C` | `ON` | Build the C API | +| `CO_SIM_IO_BUILD_PYTHON` | `OFF` | Build Python bindings | +| `CO_SIM_IO_BUILD_FORTRAN` | `OFF` | Build the Fortran API | +| `CO_SIM_IO_BUILD_TESTING` | `OFF` | Build the test suite | +| `CO_SIM_IO_BUILD_MPI` | `OFF` | Enable MPI communication | +| `CO_SIM_IO_STRICT_COMPILER` | `OFF` | Enable strict compiler warnings | + +For example, to enable MPI and Python bindings: + +```bash +cmake .. \ + -DCMAKE_BUILD_TYPE=Release \ + -DCO_SIM_IO_BUILD_MPI=ON \ + -DCO_SIM_IO_BUILD_PYTHON=ON +``` + +To specify a custom install prefix: + +```bash +cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install +``` + +> **Note:** The Fortran API depends on the C API. Always enable `CO_SIM_IO_BUILD_C=ON` when building with `CO_SIM_IO_BUILD_FORTRAN=ON`. + +#### 3. Build + +```bash +cmake --build . --config Release +``` + +To speed up compilation using multiple cores: + +```bash +cmake --build . --config Release -- -j$(nproc) +``` + +> On macOS, replace `$(nproc)` with `$(sysctl -n hw.logicalcpu)`. + +#### 4. Install + +```bash +cmake --install . +``` + +If a custom prefix was specified during configuration, the libraries and headers will be placed there. Otherwise the default system prefix (e.g. `/usr/local`) is used. + +#### 5. Verify the Installation + +After installation, confirm that the shared library is present: + +```bash +ls /path/to/install/lib/libCoSimIO* +``` + +If Python bindings were built, verify the module is importable (defining properly the `PYTHONPATH`): + +```bash +python3 -c "import CoSimIO; print('CoSimIO imported successfully')" +``` + +#### Platform-Specific Notes + +| Platform | Notes | +|---|---| +| **Linux** | Ensure `/path/to/install/lib` is on `LD_LIBRARY_PATH` | +| **macOS** | Ensure `/path/to/install/lib` is on `DYLD_LIBRARY_PATH` | +| **Windows** | Ensure `/path/to/install/bin` is on `PATH`; use the Visual Studio generator with `-G "Visual Studio 17 2022"` | + +### Installing with Spack + +This section describes how to install _CoSimIO_ using [Spack](https://spack.io/), a flexible package manager designed for HPC environments. First, make sure Spack is available in your environment: + +```bash +git clone --depth=1 https://github.com/spack/spack.git +source spack/share/spack/setup-env.sh +``` + +Then install _CoSimIO_ with the default configuration: + +```bash +spack install cosimio +``` + +### Variants + +The Spack package exposes several build variants that allow you to tailor the installation to your needs: + +| Variant | Default | Description | +|---|---|---| +| `+mpi` / `~mpi` | `~mpi` | Enable MPI-parallel communication | +| `+c` / `~c` | `+c` | Build the C API | +| `+python` / `~python` | `~python` | Build Python bindings (requires Python ≥ 3.6) | +| `+fortran` / `~fortran` | `~fortran` | Build the Fortran API (requires `+c`) | +| `+testing` / `~testing` | `~testing` | Build the test suite | +| `+strict` / `~strict` | `~strict` | Enable strict compiler warnings | + +> **Note:** The Fortran API is built on top of the C API. Enabling `+fortran` without `+c` is not allowed. + +#### Examples + +Install with MPI support: + +```bash +spack install cosimio+mpi +``` + +Install with Python bindings: + +```bash +spack install cosimio+python +``` + +Install with C, Fortran, and MPI support: + +```bash +spack install cosimio+c+fortran+mpi +``` + +Install a specific version: + +```bash +spack install cosimio@4.3.1 +``` + +### Loading the Package + +Once installed, load _CoSimIO_ into your environment with: + +```bash +spack load cosimio +``` + +### Dependencies + +Spack resolves all dependencies automatically. For reference, the following are pulled in depending on the chosen variants: + +| Dependency | When required | +|---|---| +| `cmake@3.15:` | Always (build only) | +| `mpi` | `+mpi` | +| `python@3.6:` | `+python` | +| `py-pybind11` | `+python` (build only) | +| Fortran compiler | `+fortran` | From 3617e98186ab227af85495f1cfda755d616aed31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vicente=20Mataix=20Ferr=C3=A1ndiz?= Date: Tue, 26 May 2026 11:19:47 +0200 Subject: [PATCH 3/3] Revert README --- README.md | 204 ------------------------------------------------------ 1 file changed, 204 deletions(-) diff --git a/README.md b/README.md index ac6ee20b..a01708c4 100644 --- a/README.md +++ b/README.md @@ -56,210 +56,6 @@ The _CoSimIO_ supports pure sequential and mpi-parallel executions. Shared memor ## Memory Management Coupling requires frequent exchange of data. Therefore the _CoSimIO_ uses the memory provided by the including solvers/software-tools directly, without copying it to an auxiliar data structure. -## Installation - -### Manual Installation - -If you prefer not to use Spack, _CoSimIO_ can be built and installed manually using [CMake](https://cmake.org/). - -#### Prerequisites - -- A C++11 compatible compiler (GCC, Clang, MSVC, etc.) — see the full list [here](https://en.cppreference.com/w/cpp/compiler_support#cpp11) -- [CMake](https://cmake.org/) ≥ 3.15 -- _(Optional)_ An MPI implementation (e.g. [OpenMPI](https://www.open-mpi.org/), [MPICH](https://www.mpich.org/)) for `+mpi` support -- _(Optional)_ [Python](https://www.python.org/) ≥ 3.6 and [pybind11](https://github.com/pybind/pybind11) for Python bindings -- _(Optional)_ A Fortran compiler for the Fortran API - ---- - -#### 1. Clone the Repository - -```bash -git clone https://github.com/KratosMultiphysics/CoSimIO.git -cd CoSimIO -``` - -Or download a specific release tarball: - -```bash -wget https://github.com/KratosMultiphysics/CoSimIO/archive/refs/tags/v4.3.1.tar.gz -tar -xzf v4.3.1.tar.gz -cd CoSimIO-4.3.1 -``` - ---- - -#### 2. Configure with CMake - -Create a build directory and run CMake: - -```bash -mkdir build && cd build -cmake .. -``` - -The following CMake options are available to control what gets built: - -| CMake Option | Default | Description | -|---|---|---| -| `CO_SIM_IO_BUILD_C` | `ON` | Build the C API | -| `CO_SIM_IO_BUILD_PYTHON` | `OFF` | Build Python bindings | -| `CO_SIM_IO_BUILD_FORTRAN` | `OFF` | Build the Fortran API | -| `CO_SIM_IO_BUILD_TESTING` | `OFF` | Build the test suite | -| `CO_SIM_IO_BUILD_MPI` | `OFF` | Enable MPI communication | -| `CO_SIM_IO_STRICT_COMPILER` | `OFF` | Enable strict compiler warnings | - -For example, to enable MPI and Python bindings: - -```bash -cmake .. \ - -DCMAKE_BUILD_TYPE=Release \ - -DCO_SIM_IO_BUILD_MPI=ON \ - -DCO_SIM_IO_BUILD_PYTHON=ON -``` - -To specify a custom install prefix: - -```bash -cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install -``` - -> **Note:** The Fortran API depends on the C API. Always enable `CO_SIM_IO_BUILD_C=ON` when building with `CO_SIM_IO_BUILD_FORTRAN=ON`. - ---- - -#### 3. Build - -```bash -cmake --build . --config Release -``` - -To speed up compilation using multiple cores: - -```bash -cmake --build . --config Release -- -j$(nproc) -``` - -> On macOS, replace `$(nproc)` with `$(sysctl -n hw.logicalcpu)`. - ---- - -#### 4. Install - -```bash -cmake --install . -``` - -If a custom prefix was specified during configuration, the libraries and headers will be placed there. Otherwise the default system prefix (e.g. `/usr/local`) is used. - ---- - -#### 5. Verify the Installation - -After installation, confirm that the shared library is present: - -```bash -ls /path/to/install/lib/libCoSimIO* -``` - -If Python bindings were built, verify the module is importable: - -```bash -python3 -c "import CoSimIO; print('CoSimIO imported successfully')" -``` - ---- - -#### Platform-Specific Notes - -| Platform | Notes | -|---|---| -| **Linux** | Ensure `/path/to/install/lib` is on `LD_LIBRARY_PATH` | -| **macOS** | Ensure `/path/to/install/lib` is on `DYLD_LIBRARY_PATH` | -| **Windows** | Ensure `/path/to/install/bin` is on `PATH`; use the Visual Studio generator with `-G "Visual Studio 17 2022"` | - -### Installing with Spack - -This section describes how to install _CoSimIO_ using [Spack](https://spack.io/), a flexible package manager designed for HPC environments. First, make sure Spack is available in your environment: - -```bash -git clone --depth=1 https://github.com/spack/spack.git -source spack/share/spack/setup-env.sh -``` - -Then install _CoSimIO_ with the default configuration: - -```bash -spack install cosimio -``` - ---- - -### Variants - -The Spack package exposes several build variants that allow you to tailor the installation to your needs: - -| Variant | Default | Description | -|---|---|---| -| `+mpi` / `~mpi` | `~mpi` | Enable MPI-parallel communication | -| `+c` / `~c` | `+c` | Build the C API | -| `+python` / `~python` | `~python` | Build Python bindings (requires Python ≥ 3.6) | -| `+fortran` / `~fortran` | `~fortran` | Build the Fortran API (requires `+c`) | -| `+testing` / `~testing` | `~testing` | Build the test suite | -| `+strict` / `~strict` | `~strict` | Enable strict compiler warnings | - -> **Note:** The Fortran API is built on top of the C API. Enabling `+fortran` without `+c` is not allowed. - -#### Examples - -Install with MPI support: - -```bash -spack install cosimio+mpi -``` - -Install with Python bindings: - -```bash -spack install cosimio+python -``` - -Install with C, Fortran, and MPI support: - -```bash -spack install cosimio+c+fortran+mpi -``` - -Install a specific version: - -```bash -spack install cosimio@4.3.1 -``` - ---- - -### Loading the Package - -Once installed, load _CoSimIO_ into your environment with: - -```bash -spack load cosimio -``` - ---- - -### Dependencies - -Spack resolves all dependencies automatically. For reference, the following are pulled in depending on the chosen variants: - -| Dependency | When required | -|---|---| -| `cmake@3.15:` | Always (build only) | -| `mpi` | `+mpi` | -| `python@3.6:` | `+python` | -| `py-pybind11` | `+python` (build only) | -| Fortran compiler | `+fortran` | - ## Special Thanks To - [Boost](http://www.boost.org/) for the `intrusive_ptr` - [pybind11](https://github.com/pybind/pybind11) for exposing C++ to python