/pyfalcon

Python interface for the fast-multipole gravity solver falcON from NEMO

Primary LanguageC++

This is a simple Python interface and an AMUSE interface
for the fast-multipole gravity solver "falcON" (W.Dehnen, ApJL, 536, 9, 2000),
which is included in the NEMO stellar-dynamical toolbox:
https://teuben.github.io/nemo/

This package contains a stripped-down version of falcON, extracted from NEMO
and removing parts not directly relevant for the computation of gravity
(hence NEMO is not required for this package).
It provides two independent interfaces.

(==1==) The first is a pure Python extension module "pyfalcon".
It provides a single function, gravity(), which constructs the tree
and computes potential and accelerations for all particles or a subset of them.
As an example of usage, the program run.py implements a basic N-body simulation
code: reading the input snapshot (in NEMO format), performing an integration
loop with the leapfrog method, and writing the output snapshot(s).
To work with the NEMO I/O format from Python, it relies on the UNSIO library:
https://projects.lam.fr/projects/unsio/wiki  or
https://pypi.org/project/python-unsio/
If UNSIO is not available, it uses a slower fallback for text-to-NEMO conversion.
This example program is (nearly) equivalent to running the native gyrfalcON code,
except that it will save each output snapshot to a separate file.
But the very reason for this package's existence is the possibility of using
the gravity solver in other contexts, or augment it with extra features, such as
additional sources of gravity (e.g. an external potential) or custom on-the-fly
analysis tools performed during the simulation itself.

Note: the falcON code, as a general-purpose gravity solver, computes the forces
symmetrically and only at the particle locations. For instance, if you want
to determine the acceleration at an arbitrary point in space, you need to put
a particle there, and set its mass to a tiny but nonzero value; zero masses
are not allowed.

(==2==) The second is the module for the AMUSE stellar-dynamics framework:
https://amusecode.org/
It can be accessed via  amuse.community.falcon.interface.Falcon
(an instance of GravitationalDynamicsInterface), and works just as any other
gravitational dynamics code, using a simple leapfrog integration with
a constant shared timestep. It has the following tunable parameters:
timestep - global, shared timestep for the integration.
epsilon - the softening length (or epsilon_squared for a square of this number).
individual_epsilon - if set to True, use individual softening lengths for
each particle instead of the global value; these are taken from particle radii.

Installation.
(==1==) For the pure Python interface, run setup.py install, as usual.
UNSIO is recommended for the example program, but is not needed for the Python
extension module itself; neither is NEMO.
The package supports both Python 2.x and 3.x.
To test the code, prepare an N-body snapshot, e.g.:
mkplummer test_in 100000
and then run the example script with some parameters, similarly to gyrfalcON:
python run.py test_in test_out eps=0.05 kmax=4 step=1 tstop=5

(==2==) For the AMUSE interface, run "make amuse" or simply "make" (the latter
also installs the pure python interface). The module will be copied into
$(AMUSE_ROOT)/community/falcon/ , where AMUSE_ROOT is the root folder of
the AMUSE python package, i.e. amuse.__path__[0]
To test the interface, run amuse_example.py (integrate a simple Plummer sphere).