Merge pull request #504 from chunliangmu/master [skip ci]

Added documentation for stellar relaxation

docs/user-guide/index.rst

@@ -8,6 +8,7 @@ This section contains the basic user guide for Phantom.
 
    config
    setups
+   relaxation
    infile
    qscript
    sweeps

docs/user-guide/relaxation.rst

@@ -0,0 +1,29 @@
+
+Stellar relaxation
+==================
+
+
+When mapping 1D profile from MESA to a 3D code such as Phantom, a relaxation procedure is required to ensure that the particles are in hydrostatic equilibrium.
+
+In phantom this is achieved by a process called ``relax-o-matic``
+(`Lau et al., 2022 <https://doi.org/10.1093/mnras/stac049>`_ - **please see its appendix C for full details of how it works**).
+
+
+To run ``relax-o-matic`` after setting up a star,
+just follow the instructions during setup (from ``phantomsetup``) and type ``yes`` when prompted "Relax star automatically during setup?";
+
+Then, modify the ``.setup`` file and fill in the relaxation options, which are pretty self-explanatory::
+
+	relax_star        =           T    ! relax star automatically during setup
+	tol_ekin          =   1.000E-07    ! tolerance on ekin/epot to stop relaxation
+	tol_dens          =       1.000    ! % error in density to stop relaxation
+	maxits            =        1000    ! maximum number of relaxation iterations
+	write_rho_to_file =           F    ! write density profile to file
+
+Run the ``phantomsetup`` again to start the auto relaxation process.
+You are now good to go!
+
+If interruptted during the relaxation, run ``phantomsetup`` again and it will pick up from where it left off automatically.
+
+If in doubt, you can always run the star in isolation for a few years to see if relaxation procedure worked.
+