Advice-and-troubleshooting.md

 # Advice to obtain a converged solution
 In some situations it can be hard to obtain convergence with *Exo-REM*. The following advice are here to help you. They may not work all the time, so if you have any trouble left, you may want to send a mail to one of the maintainer.
 
+Summary:
+- [General advice](#general-advice)
+- [Cookbook when in trouble](#cookbook-when-in-trouble)
+- [What to do if you have reached convergence but your temperature profile contains oscillations ?](#what-to-do-if-you-have-reached-convergence-but-your temperature-profile-contains-oscillations?)
+
 Reminder: *Exo-REM* is not made to simulate highly-irradiated planets (equilibrium temperature > 2000 K) and non-H2 dominated atmopsheres (metallicity > 1000 times the solar metallicity).
 
 ## General advice
@@ -13,6 +18,19 @@ Reminder: *Exo-REM* is not made to simulate highly-irradiated planets (equilibri
 - Always have `n_burn_iterations` at least equal to `n_iterations`, unless you really have a hard time to find convergence.
 
 ## Cookbook when in trouble
-When you have trouble to reach convergence, you can do, in that order:
-1. Decrease `weight_apriori` roughly by one order of magnitude. If you crash, decrease by another order of magnitude. Repeat until you can reach the end of your run. Then, Increase `weight_apriori` again to 10. Repeat until you are satisfied.
-2. 
\ No newline at end of file
+When you have trouble to reach convergence (for example, if the ratio `J_int / J_th` oscillates or if the code crashes), you can do, in that order:
+
+1. Set `retrieval_flux_error_bottom = 1e-3` and `retrieval_flux_error_top = 1e-5`. Decrease `weight_apriori` roughly by one order of magnitude. If you crash, decrease by another order of magnitude. Repeat until you can reach the end of your run. Then, Increase `weight_apriori` again to 10. Repeat until you are satisfied.
+2. Increase `retrieval_flux_error_bottom`, but keep it lower than 1e-2. When satisfied, set it back to at must 1e-3 and redo a run.
+3. Increase `retrieval_flux_error_top`, but keep it lower than 1e-2. When satisfied, set it back to at must 1e-5 and redo a run.
+4. Find, or make-up a temperature profile that is close to what you expect, then use it as input.
+5. Decrease `n_burn_iterations` to roughly `n_iterations - n_non_adiabatic_iterations - 10`. You can replace 10 by whatever you feel is better. Set `chemistry_iteration_interval = 2` and `cloud_iteration_interval= 4`.
+6. Increase `chemistry_iteration_interval` and/or `cloud_iteration_interval= 4`. Increase `n_iterations` accordingly.
+
+## What to do if you have reached convergence but your temperature profile contains oscillations ?
+Even when you have a well-converged simulation, a temperature profile from *Exo-REM* will always have some oscillations in it. Most of the time, they will be insignificant. Sometimes they can be more important. However, most of the time this should not be worrying, and it can be very hard to get rid of them. Here is a list of things you can do to improve your profile:
+
+1. Decrease `retrieval_flux_error_bottom` and `retrieval_flux_error_top` down to roughly 1e-15 (fortran double precsion). Decrease a lot `weight_apriori` (consider 1e-15 as a high value). Set `retrieval_tolerance = 0`. Increase a lot `n_iterations` (50, or more) and `n_non_adiabatic_iterations` (20, or more).
+2. Increase `n_levels`. Do not forget to increase `retrieval_level_top` accordingly.
+3. Increase `smoothing_bottom` and `smoothing_top`, but not too much. Consider 1.5 as a soft upper limit.
+4. As a last resort, you can try to apply a sliding mean on your temperature profile, or any other smoothing method. Then, set  `n_iterations = 0` and use your modified temperature profile as input. Check if the ratio `J_int / J_th` is close to 1. If that is the case, you can safely use the outputs of your 0-iteration run.
\ No newline at end of file