██████╗ ██╗  ██╗██╗   ██╗███████╗██╗███╗   ███╗
██╔══██╗██║  ██║╚██╗ ██╔╝██╔════╝██║████╗ ████║
██████╔╝███████║ ╚████╔╝ ███████╗██║██╔████╔██║
██╔═══╝ ██╔══██║  ╚██╔╝  ╚════██║██║██║╚██╔╝██║
██║     ██║  ██║   ██║   ███████║██║██║ ╚═╝ ██║
╚═╝     ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝╚═╝     ╚═╝

An extensible framework for performing N-body simulations.

Overview

physim provides a framework for users to run N-body simulations. Users can build pipelines from the command line or from a configuration file.

Functionality can be added to physim with plugins. Developers can make these plugins with Rust and there is support for some elements to be written in languages with a C ABI. physim comes with a variety of useful elements which do things like render the simulation with OpenGL and perform gravity calculations on the entities in the simulation.

Please see the user manual for more information.

Installation

macOS

curl -L https://github.com/jhb123/physim/releases/latest/download/physim-macos.tar.gz \
  -o physim-macos.tar.gz && tar -xzf physim-macos.tar.gz && bash physim-macos/install.sh

Other platforms

You are required to build physim from source. Install Rust, and then run

cargo build -r

Running a simulation

physim simulations can be configured directly in the CLI. Each element is delimited by !, and the properties of the element can be configured as shown in the following example:

physim cube n=100000 seed=1 spin=1000 ! star mass=100000.0 radius=0.1 z=0.5 x=0.2 y=0.2 ! star mass=100000.0 radius=0.1 z=0.5 x=-0.2 y=-0.2 ! astro2 theta=1.5 e=0.5 ! verlet ! glrender ! global dt=0.00001 iterations=10000

Alternatively, simulations can be configured with a file with physim -f pipeline.toml. The pipeline above can be expressed in TOML as

[global]
dt = 0.00001
iterations = 1000

[elements]

[[elements.cube]]
n = 100000
seed = 1
spin = 1000

[[elements.astro2]]
theta = 1.5
e = 0.5

[[elements.star]]
mass = 100000.0
x=0.2
y=0.2
z=0.5
radius = 0.1

[[elements.star]]
mass = 100000.0
x=-0.2
y=-0.2
z=0.5
radius = 0.1

[[elements.verlet]]

[[elements.glrender]]

Encoding with FFMPEG

The following example shows how to use the stdout element from the glrender plugin with FFmpeg to encode a video.

physim cube n=100000 seed=1 spin=500 ! star mass=100000.0 x=0.1 y=0.1 radius=0.1 z=0.5 ! star mass=100000.0 x=-0.1 y=-0.1 radius=0.1 z=0.5 ! star mass=100000.0 x=-0.1 y=0.1 z=0.5 ! star mass=100000 x=0.1 y=-0.1 z=0.5 ! astro theta=1.3 ! verlet ! stdout zoom=1.5 resolution=1080p ! global iterations=10 | ffmpeg -y -f rawvideo -pixel_format rgba -video_size 1920x1080 -framerate 60 -i pipe:0 -vf "scale=in_range=full:out_range=full,format=yuv420p10le" -c:v libx265 -preset slow -pix_fmt yuv420p10le output.mp4

You can find more information in FFmpeg

Element documentation

By default, plugins will be loaded from the directory that physim is in. However, you can specify additional directories, each one separated by :, with the PHYSIM_PLUGIN_DIR environment variable. To determine what elements you have access to, run

# Brief summary of all available elements
physcan

# More details about an element e.g. 'cube'
physcan cube

Development

debug plugin

The debug plugin is for ad-hoc manual testing. It can serve as poorly written documentation of how to use most features of physim. It is not built by default as it does not have anything very useful outside of a development context in it. To build it, run

cargo build -p debug

cbindgen

Run cbindgen --lang c --crate physim-core --output physim.h to generate a header file which can be used to make a plugin in C.

Git

Commits should follow the conventional commits standard. The .gitmessage file provides guidance on this and it can be set as your template with

$ git config commit.template .gitmessage

We use the rebase strategy for pull requests.

Use pre-commit to keep the codebase free of common style issues.

Licence

MIT.

Roadmap

These features could result in Entity changing, so it is worth reiterating that this library is not in a stable form and backwards compatibility is not guaranteed.

• Bird flocking using the boids model.
• Calculation of gravitational potential using the fast multipole method.
• Gas simulation with the Lennard-Jones potential.
• Relativistic simulation using Einstein–Infeld–Hoffmann equations of motion.
• Element for rendering text as entities.
• General purpose test tools for pipeline and element testing.
• Improve use as a library.
• Electromagnetism.