April 11, 2023


This a brief manual to compile and run AR-CHAIN.


gfortran -O3 AR-CHAIN.f -o ARC.x

The executable ARC.x reads the input from an input file, which we call INP.ttt

Run the code

$ ./ARC.x < INP.ttt

Structure of the input file

  1.  a first line containing all the parameters of the run
  2.  a series of N lines containing the particles’ initial conditions in the format: mass, x, y, z, vx, vy, vz
  3.  a final line with as many 0s as the number of parameters in instruction

First line of input

The line must be as follows (this case is tailored to an EMRI-like binary):

0  2   1.d0    800.   0.e-3    0.0   1. 1.e-2 0.e0 456.99  O1  0 2  0.0 0.0
0.0 1.e-13  0  10000 /IWR,N,DELTAT,TMAX ,step,soft,cmet,Clight, out
file,Ixc,Nbh ,spin, EPS, ivelocity, KSMX !


IWR          id of the run -- nothing of interest
N            number of particles
DELTAT,TMAX  output frequency and integration time (in scaled units)
step         initial integration step (if set to 0, the code estimate this quantity on its own)
soft         softening parameter (in scaled units). Of course, this can be set to 0
cmet         a three-element vector that sets the integration method. Generally the choice (1 0.01 0) is good for EMRIs
Clight       speed of light in scaled units
outfile      name of the main output file, it contains time, (x, y, z) for all particles in scaled units, thus you have a total of 1 + 3N columns
Ixc          index that tells if exact output times are required,
               0 => no exact, output when t>tnext, (fast, but sometimes output interval too long)
               1 => exact time (not always accurate, but faster than the exact iteration)
               2 => exact iteration (time to tnext) (slower!)
Nbh          number of particles for which PN terms must be considered (these will be considered as the first Nbh lines in the input file)
spin         spin components of the heaviest BH in the sample, it must be placed in the first line (works well just with SMBHs and stellar objects, I'd say)
EPS          tolerance of the run, generally 1.E-12 is a good choice
ivelocity    index telling that there are v-dependent perturbations (=1) or not (=0). Set to 1 to include PN terms
KSMX         tells how many (maximum) integration steps the code is at most allowed to take between outputs

An example

This file contains an example of an EMRI

0  2   1.d1    8000.   0.e-3    0.0   1. 0.e0 0.e0 456.99  O1  0 2  0.0 0.0 0.0 1.e-13  0  10000 /IWR,N,DELTAT,TMAX ,step,soft,cmet,Clight, outfile,Ixc,Nbh ,spin, EPS, ivelocity, KSMX !
1.0 0.0 0.0 0.0 0.0 0.0 0.0
1.E-6 1.0 0.0 0.0 0.0 0.05 0.0
 0  0  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

where we set the

mass unit = 10^6 Msun
length unit = 0.01 pc

This implies a

velocity unit = 656 km/s (thus Clight  = 456.99)
time unit ~ 15 yr

The orbit has an initial semiax of 0.01 pc and eccentricity = 0.997, which are typical of an EMRI.

Additional information

Besides the output file produced by the code, AR-CHAIN prints in the terminal some conservation quantities (not exactly the energy conservation when PN are on, but close to), and it also produces some files where there are the orbital elements of all bodies with respect to the first body in the file. This is particularly well-suited for EMRIs, less for nearly equal-mass bodies.

These files are:

  • axes.dat: time, semimajor axis in scaled units of the orbit between i-th body and the first one
  • eccs.dat : time, eccentricity of the orbit between the i-th body and the first one
  • incs.dat: time, inclination of the orbit between the i-th body and the first one
  • omes.dat: time, argument of periapsis
  • Omes.dat: time, longitude of the ascending node
  • spin.dat: time, spin components of the first body
  • merge.dat: time, indexes of merging bodies

Relativistic terms

The PN terms are implemented in the main code in the routine “Relativistic terms” at line 1773. They are called A2, A2p5, A3, A3p5, B2, B3 etc..