# 5-steps procedure for eccentricity reduction with SGRID and BAM
(using BNSdata_rdot and BNSdata_ecc)

## Requirements 

   * SGRID static exe compiled on given machine (or on machine with same kernel version) `sgrid-<ompi>-<machine>`
   * SGRID parfile, e.g. `SGRIDPARFILE.par`.
   * SGRID parfile needs to have: `BNSdata_adjust = forcebalance always`
   * BAM, parfile, e.g. `BAMPARFILE.par`.
   * Python and script to compute eccentricity: EccRed.py

## Step 1: Run SGRID 

Use some script to start sgrid on your cluster, i.e. something like

``` 
./exe/sgrid SGRIDPARFILE
```

Several resolutions are computed. Push this simulation until the iterations
at the desired resolution is done. Assuming the target resolution is
28x28x24, you need to check the `BNSdata_properties.txt` log file:

```
login3.stampede(52)$ tail -n 50 SGRIDPARFILE_28_28_24/BNSdata_properties.txt 
sigm_00         -1.479863669769116097
sigm_10         -1.498449069126190913

================================================
Properties after final iteration are below:
q_def           h-1
================================================

BNS data properties (time = 0):
-------------------
n_list          2.8017482909335434 0.40716612377850164 0.49726504226752855 2.352941176470588
rho0_list       1.83976668e-04 8.11322219e-04 1.61880065e-03
kappa           8.94989354e-02
x_CM            -9.40874223826065917e-09
Omega           0.006642765475696818002
ecc             0
rdot            0
m01             1.467538154618045931
m02             1.467538154617764157
J_ADM           7.752941418606220658
M_ADM           2.678293738008048042
Jx_ADM          2.742075003134489846e-11
Jy_ADM          -3.201193979681814361e-09
Jz_ADM          7.752941418606220658
Px_ADM          -4.741787273355409055e-06
Py_ADM          2.817788780085095368e-10
Pz_ADM          -7.899615889918369015e-12

<many other lines...>
```

## Step 2: Backup SGRID data at current iteration

There is a bash script to do this in `scripts/`, example

```
./bckp_sgrid_data.sh SGRIDPARFILE_28x28x24 SGRIDPARFILE_28x28x24_ITER<iteration_number>
```

The script backups the `BNS_properties`, the parfile at the current
iteration and the data. It also makes some necessary changes to parfile and
checkpoint, in particular setting `iteration_parameters` to "no".

## Step 3: Run BAM 

Run BAM using the SGRID backupped data at current iteration as initial data.
The command is something like this:

```
<queue_bam_script> BAMPARFILE.par
```

where the relevant lines of `BAMPARFILE.par` are something like

```
BNSdataReader_sgrid_exe         = /absolute/path/to/sgrid
BNSdataReader_sgrid_datadir     = /absolute/path/to/SGRIDPARFILE_28x28x24_ITER<iter>
BNSdataReader_keep_sgrid_output = no
BNSdataReader_use_interpolator  = no
BNSdataReader_reset_EOS         = yes  
```

This needs to be run for about 2-3 orbits, in order to get enough output for
the eccentricity measure.

![BAM data: Proper separation vs. time](images/moving_puncture_distance_98.png)

## Step 4: Find new parameters from puncture track


### Python script EccRed.py

The script reads the BAM file containing the proper distance evolution, 

```
moving_puncture_distance.lxyz
```

To run it, you have to give some information.

   * filename of the proper distance file to analyze
   * Total Mass
   * Orbital frequency Omega, as you find at the **bottom** of `BNSData_properties.txt`, corresponding to the last iteration


Help for the python script `scripts/EccRed.py`, 

```
$ python EccRed.py -h
usage: EccRed.py [-h] [--Mass MASS] [--Omega OMEGA] [--tskip TIMESKIP]
                 [--dmin D_MIN]
                 file

Fit proper distance to d(t)=S0+A0*t+0.5*A1*t^2-(B/omega)cos(omega*t+phi). Then
estimate the changes drdot and decc needed in SGRID pars BNSdata_rdot and
BNSdata_ecc to reduce the measured eccentricity ecc.

positional arguments:
  file              pathname of distance file

optional arguments:
  -h, --help        show this help message and exit
  --Mass MASS       total mass of binary
  --Omega OMEGA     orbital angular velocity
  --tskip TIMESKIP  initial time interval to skip
  --dmin D_MIN      minimum d we read in

Example: EccRed.py bam0/moving_puncture_distance.lxyz4 --Mass 3 --Omega 0.007030695 --tskip 200 --dmin 31 > d.txt ; tgraph.py d.txt -c 1:3 d.txt
```

# Step 5: Create new SGRID parfile

Create a new parfile copying the current one and altering the `BNSdata_ecc`
and `BNSdata_rdot` parameters according to the fit. You need to **ADD** them
to those of the current parfile. For example, if the current parfile at
ITER0 was

```
BNSdata_ecc             =  0
BNSdata_rdot            =  0
```

you need to create parfile for ITER1 with 

```
BNSdata_ecc             =  -0.0000538883
BNSdata_rdot            =  -0.0135776
```

Restart from Step 1 and monitor the eccentricity you can stop if it does not
decreases or if it reaches 1e-4/1e-5.