avitase / libgravix2

A fast yet precise simulation of conservative, attractive forces acting on point-like particles embedded onto the surface of a unit sphere.

libgravix2 🌎🚀

A fast yet precise simulation of conservative, attractive forces acting on point-like particles embedded onto the surface of a unit sphere. The force fields are generated by static points that are embedded on the surface of the same unit sphere. We implement different symmetric and symplectic integrators and expose a simple C-API to generate and propagate particles.

This library is meant to be a physics engine for small games where, e.g., missiles fly in the gravitational force fields of planets in a curved universe. It is fast, lightweight, and lends itself perfectly to be spawned in many concurrent instances.

🚧 WORK IN PROGRESS 🚧

This is all work in progress and any help is highly appreciated. If you find any bugs or want to improve the documentation, please submit a pull request or open an issue. There are already open issues, and you can help to close them!

If you plan to contribute, please read the CONTRIBUTING guide.

Documentation

Find the documentation of our C-API here: avitase.github.io/libgravix2/

Furthermore, our C-API can easily be wrapped in high-level languages. For example, we provide a minimalistic Python binding here: avitase.github.io/libgravix2/py-bindings/ and use it to showcase a few simple applications in a Jupyter notebook.

How to build

This is a C library with (almost) no external dependencies, except for:

• C mathematical operations from math.h, e.g., libm.so.6
• Standard C library, e.g., libc.so.6
• that's all

Building is straightforward with cmake and its predefined CMake Presets:

libgravix2 $ cmake --preset=release
[...]
-- Configuring done
-- Generating done
-- Build files have been written to: build/release
libgravix2 $ cmake --build build/release

You'll now find the shared library under build/release/libgravix2.so. If you want to install the library system-wide, you can either copy this (and the other generated files) from the build directory manually or use CMake to install them automatically.

libgravix2 $ cmake --install build/release

If you prefer to find the files in non-default locations you have to set CMAKE_INSTALL_PREFIX during configuration, e.g.,

libgravix2 $ cmake --preset=release -DCMAKE_INSTALL_PREFIX=/some/path
libgravix2 $ cmake --build build/release                  # as before
libgravix2 $ cmake --install build/release                # as before

There are more configuration options that can be set during compilation either by passing them directly via -D to cmake (as shown before with CMAKE_INSTALL_PREFIX) or via a graphical tool, such as ccmake:

• CMAKE_BUILD_TYPE: Release (default) or Debug. If enabling unit tests, this has to be set to Debug.
• ENABLE_TESTING: On or Off (default). Generate unit tests and require a Debug build. Tests can be run with ctest after building.
• ENABLE_DOXYGEN: On or Off (default). Generate documentation and require a Doxygen installation.
• GRVX_POT_TYPE: 2D (default) or 3D.
• GRVX_N_POT: Approximation order of the force field. Only available if GRVX_POT_TYPE is set to 3D. (Default: 0)
• GRVX_TRAJECTORY_SIZE: Size of trajectory. (Default: 100)
• GRVX_INT_STEPS: Number of integration steps between trajectory points. (Default: 10)
• GRVX_MIN_DIST: Smallest allowed distance between missiles and planets. (Default: 1 degree.)
• GRVX_COMPOSITION_SCHEME: p2s1 , p4s3 , p4s5 , p6s9 or p8s15 (default).

Have a look into our documentation for more information about these options.

CMake package

We also export a CMake package upon installation to be used with the find_package command of CMake:

• Package name: libgravix2
• Target name: libgravix2::libgravix2

Example usage:

find_package(libgravix2 REQUIRED)

# Declare the imported target as a build requirement using PRIVATE, where
# project_target is a target created in the consuming project
target_link_libraries(
    project_target PRIVATE
    libgravix2::libgravix2
)

libgravix2's Issues

Enable code coverage

We already generate a coverage report of our C test suite but we don't do anything useful with this report. At least we should add a badge to the README.md.

Write fast, yet comprehensive unit tests

Currently, the unit tests for the C-API and for the Python binding are dummies. We should strive for a test suite with tests that run fast but cover the entire surface of the library. In a sense, approval tests might do the job here rather than testing each and every function. This test suite should also include various combinations of possible static/compile-time configurations.

Implement Higham's summation scheme

There are more educated ways to implement the integration step s.t. rounding errors cancel. See N. Higham, "The Accuracy of Floating Point Summation" (1993) for details.

Reduce texlive-full dependency in CI

For building the images of our documentation we need LuaLaTeX and a few other packages that come with Ubuntu's texlive-full installation. Presumably, we don't use 99% of the packages that come with full installation and we should try to reduce the size of this dependency, for example by using a fainer-grained package requirement.

Improve Jupyter Notebook

This notebook could be used to demonstrate the Python binding and the interaction with the API in general. However, the notebook itself should be thoroughly overhauled and good documentation inside the notebook should be added.

Improve formatting of Doxygen

The Doxygen documentation needs proper formatting. In particular, the width of the page should be limited and images should be centered. Ideally, a solution should work without external dependencies.

GIF needed for README

The README should open with a catchy GIF showing the propagation of a missile. Ideally, the animation should show the symmetric nature of the integrator, perhaps by simultaneously propagating the missile forward and backward in time.

Improve performance

As soon as we have approval tests (#1) we should investigate performance bottlenecks and improve the implementation.

Move heap allocation to stack allocation

Currently, orb_period does an unnecessary heap allocation here:

libgravix2/src/missile.c

Line 203 in f91d51f

PlanetsHandle planets = new_planets(1);

This can be removed by passing a pointer to a stack variable into PlanetsHandle.