ParaMagneticS

Stands for parallel magnetic field simulations. This repository offers a user friendly tool to efficiently simulate the magnetic field stemming from simple magnet geometries: cube and sphere. ParaMagneticS is implemented in C++ and allows to explore the magnetic field for a combination of magnets. The simulations are performed in a parallel manner to reduce the design iteration time for different magnet configurations.

Features

• Elementary magnets: Cubic and spherical magnets
• Easy and seamless workflow using a JSON parameter file
• Modern CMake practices
• Clean separation of library and executable code
• Integrated test suite
• Continuous integration via GitHub Actions
• Code coverage via codecov

Usage

Build and run with Docker (Recommended)

To build a Docker image of the ParaMagneticS toolkit, run the following command:

docker build -t paramagnetics .

The command above builds the docker image. To run a simulation using the built Docker image, run the followin command:

OMP_PROC_BIND=true;
docker run --rm \
           -v /full_dir_path_to_data_input:/app/data:ro \
           -v /full_dir_path_to_data_output:/app/output \
           paramagnetics

The /full_dir_path_to_data_input is the full directory to the input_data.json file (see Input Data section), it should contain a single file. The /full_dir_path_to_data_output is the directory in which the simulation results will be saved.

Build and run the standalone target

Use the compiling script compile.sh:

./compile.sh

or use the following command to build and run the executable target.

cmake -S standalone -B build/standalone -DCMAKE_BUILD_TYPE=Release -DKokkos_ENABLE_OPENMP=On -DCMAKE_CXX_COMPILER=g++
cmake -S test -B build/test -DCMAKE_BUILD_TYPE=Release -DKokkos_ENABLE_OPENMP=On -DCMAKE_CXX_COMPILER=g++
./build/standalone/Greeter --help

Build and run test suite

Use the following commands from the project's root directory to run the test suite.

cmake -S test -B build/test -DCMAKE_BUILD_TYPE=Release -DKokkos_ENABLE_OPENMP=On -DCMAKE_CXX_COMPILER=g++
cmake --build build/test -DCMAKE_BUILD_TYPE=Release -DKokkos_ENABLE_OPENMP=On -DCMAKE_CXX_COMPILER=g++
CTEST_OUTPUT_ON_FAILURE=1 cmake --build build/test --target test

# or simply call the executable: 
./build/test/GreeterTests

To collect code coverage information, run CMake with the -DENABLE_TEST_COVERAGE=1 option.

Input Data

The input data is a .json file that has the following format:

{
  "magnets": [
    {
      "id": 1,
      "type": "cuboid",
      "parameters": {
        "dimensions": [1, 1, 1],
        "magnetization": [0, 1, 0],
        "position": [0, 0, 0],
        "orientation": [1, 0, 0, 0] 
        }
    }
  ],
   "field_of_view": {
     "x": {
       "min": 2,
       "max": 4,
       "n": 3
    },
     "y": {
       "min": 0,
       "max": 3,
       "n": 4
    },
     "z": {
       "min": 0,
       "max": 10,
       "n": 11
    }
   }
}

Note that the orientation field in the JSON parameter file represents a quaternion.

Output Data

The main script generates a .csv file containing the values of the magnetic field resulting from the provided magnets in the input JSON file.

Build the documentation

The documentation is automatically built and published whenever a GitHub Release is created. To manually build documentation, call the following command.

cmake -S documentation -B build/doc
cmake --build build/doc --target GenerateDocs
# view the docs
open build/doc/doxygen/html/index.html

To build the documentation locally, you will need Doxygen, jinja2 and Pygments installed on your system.

Additional tools

The test and standalone subprojects include the tools.cmake file which is used to import additional tools on-demand through CMake configuration arguments. The following are currently supported.

Sanitizers

Sanitizers can be enabled by configuring CMake with -DUSE_SANITIZER=<Address | Memory | MemoryWithOrigins | Undefined | Thread | Leak | 'Address;Undefined'>.

Static Analyzers

Static Analyzers can be enabled by setting -DUSE_STATIC_ANALYZER=<clang-tidy | iwyu | cppcheck>, or a combination of those in quotation marks, separated by semicolons. By default, analyzers will automatically find configuration files such as .clang-format. Additional arguments can be passed to the analyzers by setting the CLANG_TIDY_ARGS, IWYU_ARGS or CPPCHECK_ARGS variables.

Ccache

Ccache can be enabled by configuring with -DUSE_CCACHE=<ON | OFF>.

References

• MagPyLib, repo

• MagTetris, repo

FAQ

Related projects and alternatives

• ModernCppStarter & PVS-Studio Static Code Analyzer: Official instructions on how to use the ModernCppStarter with the PVS-Studio Static Code Analyzer.
• cpp-best-practices/gui_starter_template: A popular C++ starter project, created in 2017.
• filipdutescu/modern-cpp-template: A recent starter using a more traditional approach for CMake structure and dependency management.
• vector-of-bool/pitchfork: Pitchfork is a Set of C++ Project Conventions.