some more docs

config/config_paper_1.yaml

@@ -0,0 +1,69 @@
+# Config File of chemcomp paper 1 (Schneider & Bitsch 2021a)
+# Can be used together with jobs/paper_1_disk.yaml, jobs/paper_1_growthtracks.yaml, jobs/paper_1_grid_thorngren.yaml
+# to generate the data of Fig. 2, 3, 4, 11, 12, 13, 14, 15
+
+# Take care of units here! Otherwise adapt in import_config.scale_units!
+# Physical parameters
+config_disk:
+  model:                        DiskLabDisk
+  M_STAR:                       1.0        # mass of central star in sun massses
+  ALPHA:                        5.0e-4     # Alpha viscosity
+  ALPHAHEIGHT:                  1.0e-4
+  M0:                           0.128       # needed for DiskLabDisk
+  R0:                           137         # needed for DiskLabDisk
+  DTG_total:                    0.02                              # Dust to gas ratios
+  static:                       False
+  evaporation:                  True
+  static_stokes:                False
+  tau_disk:                     1.0e4
+  begin_photoevap:              3.0  # Myr
+  temp_evol:                    False
+  evap_width:                   1.0e-3
+
+chemistry:
+  FeH: 0.0
+  use_FeH: False    # use FeH proxy fit according to Bitsch, Battestini 2020
+  C_frac: 0.0     # Fraction of C/H in C (will be reduced from CH4)
+
+config_planet:
+  model: BertPlanet
+  matter_removal: True
+  use_heat_torque: True
+  use_dynamical_torque: True
+  migration: True
+  M0_fact: 1
+  a_p: 30.0
+  t_0: 0.05      # time before planets start growing, total time: time_disk_0+t_0
+  rho_c: 5.5      # density of the core (g/cm**3)
+  r_in: 0.2
+  keep_peb_iso: True
+  use_pebiso_diffusion: False
+
+config_pebble_accretion:
+  u_frag:                       5.0       # m/s
+  epsilon_p: 0.5
+
+config_gas_accretion:
+  kappa_env:                    0.05
+  f_machida:                    1
+  f_disk_max:                   1.0
+
+config_planetesimal_accretion:
+  R_pla:                        50      # Planetesimal radius in km
+  rho_pla:                      1       # density of a single planetesimal (g/cm^3) = 1000 kg/m^3
+  stirring:                     1.0e-4
+  efficiency:                   0.00
+
+# modelling parameters
+defaults:
+  DEF_R_IN:                     0.1      # inner r boundary (in AU)
+  DEF_R_OUT:                    1000     # outer r boundary (in AU)
+  DEF_GRIDSIZE:                 500      # radial gridsize
+  DEF_LIN_SPACING:              False    # Spacing of radial grid
+  DEF_T_END:                    100      # Maximum simulation duration (in Myr), will cancel before if termination conditions are fulfilled
+
+output:
+  name:                        Bert
+  save_disk:                   True
+  save_interval:               5000  # time in years
+  save_disk_interval:          20

config/config_paper_2_Jupiter.yaml

@@ -0,0 +1,73 @@
+# Config File of the Jupiter model in chemcomp paper 2 (Schneider & Bitsch 2021b)
+# Can be used together with jobs/paper_2_Jupiter.yaml
+# to generate parts of the data for Jupiter in Fig. 4 and 5
+
+# Take care of units here! Otherwise adapt in import_config.scale_units!
+# Physical parameters
+config_disk:
+  model:                        DiskLabDisk
+  M_STAR:                       1.0        # mass of central star in sun massses
+  ALPHA:                        1.0e-4     # Alpha viscosity
+  ALPHAHEIGHT:                  1.0e-4
+  M0:                           0.0256       # needed for DiskLabDisk
+  R0:                           137         # needed for DiskLabDisk
+  DTG_total:                    0.015                              # Dust to gas ratios
+  static:                       False
+  evaporation:                  True
+  static_stokes:                False
+  tau_disk:                     1.0e4
+  begin_photoevap:              10.0  # Myr
+  temp_evol:                    False
+  evap_width:                   1.0e-3
+
+chemistry:
+  FeH: 0.0
+  use_FeH: False    # use FeH proxy fit according to Bitsch, Battestini 2020
+  C_frac: 0.2     # Fraction of C/H in C (will be reduced from CH4)
+
+config_planet:
+  model: BertPlanet
+  matter_removal: True
+  use_heat_torque: True #True
+  use_dynamical_torque: True
+  migration: False
+  M0_fact: 1
+  pebiso_start: True     # start with pebiso
+  M_end: 1
+  a_p: 5.0
+  t_0: 1.0      # time before planets start growing, total time: time_disk_0+t_0
+  rho_c: 5.5      # density of the core (g/cm**3)
+  r_in: 0.2
+  keep_peb_iso: True
+  solid_frac: 1.0
+  use_pebiso_diffusion: False
+  apply_gap_profile: True
+
+config_pebble_accretion:
+  u_frag:                       5.0       # m/s
+  epsilon_p: 0.5
+
+config_gas_accretion:
+  kappa_env:                    0.05
+  f_machida:                    1
+  f_disk_max:                   1.0
+
+config_planetesimal_accretion:
+  R_pla:                        50      # Planetesimal radius in km
+  rho_pla:                      1       # density of a single planetesimal (g/cm^3) = 1000 kg/m^3
+  stirring:                     1.0e-4
+  efficiency:                   0.00
+
+# modelling parameters
+defaults:
+  DEF_R_IN:                     0.1      # inner r boundary (in AU)
+  DEF_R_OUT:                    1000     # outer r boundary (in AU)
+  DEF_GRIDSIZE:                 500      # radial gridsize
+  DEF_LIN_SPACING:              False    # Spacing of radial grid
+  DEF_T_END:                    100      # Maximum simulation duration (in Myr), will cancel before if termination conditions are fulfilled
+
+output:
+  name:                        Bert
+  save_disk:                   False
+  save_interval:               500  # time in years
+  save_disk_interval:          20

doc/source/Configuration/Config-File.rst

@@ -1,6 +1,6 @@
 config.yaml
 ^^^^^^^^^^^
-.. Note:: The code is build to use cgs units! Either use cgs values or set unit conversion with `scale` in `chemcomp/helpers/import_config.py`
+.. warning:: The code is build to use cgs units internally. HOWEVER, most config entries come with a unit. If you want to introduce new parameters to the config file, either use cgs values or set unit conversion with `scale` in `chemcomp/helpers/import_config.py`.
 
 Example of unit conversion
 """"""""""""""""""""""""""

doc/source/Disk-Only.rst

@@ -0,0 +1,13 @@
+Disk only runs
+""""""""""""""
+If you want to use ``chemcomp`` to run a disk model and don't care about a planet, you may use the following settings:
+
+In the ``config_planet`` section:
+
+* Set ``model`` to ``NoAccretion``. This will introduce a passive planet that ends the simulation, once planted into the disk.
+* Set ``t_0`` to the value for how long you want to evolve the disk, before the planet ends the simulation.
+
+In the ``defaults`` section:
+
+* Set ``save_disk`` to ``True`` to make sure the disk is stored
+* Set ``save_interval`` and ``save_disk_interval`` to a reasonable interval for which you require the disk quantities to be stored

doc/source/FAQ.rst

@@ -5,6 +5,14 @@ How do I contribute?
 """"""""""""""""""""
 If you want to contribute feel free to create a pull request! This way others can profit from your contribution as well!
 
+How do I do a disk only run?
+""""""""""""""""""""""""""""
+Checkout the ``config/config_paper_1.yaml`` together with ``jobs/paper_1_disk.yaml`` for an example
+
+What happens, if I don't set a paramter
+"""""""""""""""""""""""""""""""""""""""
+A default value will be used in most cases. Make sure to set all parameters, so that you can be sure about its value!
+
 Where do I find a list of Parameters?
 """""""""""""""""""""""""""""""""""""
 Head over to the Configuration -> config.yaml

doc/source/Publications.rst

@@ -0,0 +1,33 @@
+Publications
+------------
+
+Original Publications
+^^^^^^^^^^^^^^^^^^^^^
+
+* `Schneider & Bitsch (2021a) <https://ui.adsabs.harvard.edu/abs/2021A&A...654A..71S>`_
+    How drifting and evaporating pebbles shape giant planets. I. Heavy element content and atmospheric C/O
+* `Schneider & Bitsch (2021b) <https://ui.adsabs.harvard.edu/abs/2021A&A...654A..72SS>`_
+    How drifting and evaporating pebbles shape giant planets. II. Volatiles and refractories in atmospheres
+* `Bitsch, Schneider & Kreidberg (2022) <https://ui.adsabs.harvard.edu/abs/2022A&A...665A.138B>`_
+    How drifting and evaporating pebbles shape giant planets. III. The formation of WASP-77A b and :math:`\tau` Boötis b
+
+Please cite `Schneider & Bitsch (2021a) <https://ui.adsabs.harvard.edu/abs/2021A&A...654A..71S>`_, if you use ``chemcomp`` in your work.
+
+Publications using ``chemcomp``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* `Bitsch et al. (2021) <https://ui.adsabs.harvard.edu/abs/2021A&A...649L...5B>`_
+    Dry or water world? How the water contents of inner sub-Neptunes constrain giant planet formation and the location of the water ice line
+* `Hühn & Bitsch (2023) <https://ui.adsabs.harvard.edu/abs/2023A&A...676A..87H>`_
+    How accretion of planet-forming disks influences stellar abundances
+* `Bitsch & Mah (2023) <https://ui.adsabs.harvard.edu/abs/2023arXiv230900509B>`_
+    Enriching inner discs and giant planets with heavy elements
+* `Mah & Bitsch (2023a) <https://ui.adsabs.harvard.edu/abs/2023A&A...673A..17M>`_
+    Forming super-Mercuries: Role of stellar abundances
+* `Mah & Bitsch (2023b) <https://ui.adsabs.harvard.edu/abs/2023A&A...677L...7M>`_
+    Close-in ice lines and the super-stellar C/O ratio in discs around very low-mass stars
+* `Savvidou & Bitsch (2023) <https://ui.adsabs.harvard.edu/abs/2023arXiv230903807S>`_
+    How to make giant planets via pebble accretion
+* `Danti, Bitsch & Mah (2023) <https://ui.adsabs.harvard.edu/abs/2023arXiv231002886D>`_
+    Composition of giant planets: the roles of pebbles and planetesimals
+
+And several more in preperation (last updated: 22.11.2023)

doc/source/Usage.rst → doc/source/Quick-Start.rst

@@ -40,3 +40,20 @@ Running chemcomp will create the following folders (if not existing) in the curr
    ├── zip_output          # Storage of the ziped output files
 
 If you want to know how to open and plot these files, head over to :ref:`Output`!
+
+Examples
+^^^^^^^^
+
+You can find a few examples in the ``jobs`` and ``config`` folder.
+These examples will help you to understand, how ``chemcomp`` has been used to create some figures in the original publications.
+
+These examples include:
+
+* ``jobs/paper_1_disk.yaml``
+    Job file, used to generate the disk models in the first chemcomp paper (Schneider & Bitsch 2021a)
+* ``jobs/paper_1_grid_thorngren.yaml``
+    Job file, used to generate the grid of planets to compare the heavy element content in the first chemcomp paper (Schneider & Bitsch 2021a)
+* ``jobs/paper_1_grid_thorngren.yaml``
+    Job file, used to generate the growthtracks of planets in the first chemcomp paper (Schneider & Bitsch 2021a)
+* ``jobs/paper_2_Jupiter.yaml``
+    Job file, used to generate Jupiter like planets for the second chemcomp paper (Schneider & Bitsch 2021b)

doc/source/index.rst

@@ -46,13 +46,21 @@ The physical model is in depth explained in `(Schneider & Bitsch 2021a) <https:/
    :caption: Contents
 
    Installation
-   Usage
+   Quick-Start
    Operating-Principle
    Configuration/Configuration
    Structure/Structure
+   Disk-Only
    Output
+   Publications
    FAQ
 
+Acknowledgments
+---------------
+* Aaron Schneider would like to thank Bertram Bitsch for his enormous support during the development of this code and for continuing to use the code together with his students.
+* Aaron Schneider would like to thank Cornelis Dullemond for providing the solver which (in adapted version) is used to solve the gas viscous disk equation and dust transport equation.
+* Aaron Schneider would like to thank everyone, who has already used chemcomp in their work and has contributed in fixing small bugs.
+
 Indices and tables
 ==================
 

jobs/paper_1_disk.yaml

@@ -0,0 +1,23 @@
+# Job file, used to generate the disk models in the first chemcomp paper (Schneider & Bitsch 2021a)
+
+par_1:
+  vals: [ 1.0e-3, 5.0e-4, 1.0e-4 ]
+  name: ALPHA
+  section: config_disk
+
+# the NoAccretion planet is a planet that does nothing, when it is planted into a disk.
+# It is therefore quite useful for disk only simulations
+par_2:
+  vals: [NoAccretion]
+  name: model
+  section: config_planet
+
+# setting t_0 to a value larger than the disk lifetime will prevent the planet to be planted
+par_3:
+  vals: [3.5]
+  section: config_planet
+  name: t_0
+
+double_disks: True # Do both, with evaporation and without evaporation and condensation
+save_disk: True  # output the disk quantities
+output_name: only_disk

jobs/paper_1_grid_thorngren.yaml

@@ -0,0 +1,25 @@
+# Job file, used to generate the grid of planets to compare the heavy element content in the first chemcomp paper (Schneider & Bitsch 2021a)
+# Varies over all the parameters specified in Table 5.
+par_1:
+  name: ALPHA
+  vals: [ 1.0e-4,5.0e-4,1.0e-3 ]
+  section: config_disk
+par_2:
+  name: DTG_total
+  vals: [0.01,0.015,0.02,0.025]
+  section: config_disk
+par_3:
+  name: begin_photoevap
+  vals: [1.0,2.0,3.0]
+  section: config_disk
+par_4:
+  name: a_p
+  vals: [1, 2, 3, 5, 10, 15, 20, 25, 30]
+  section: config_planet
+par_5:
+  name: t_0
+  arange: [ 0.05, 0.5, 0.1 ]
+  section: config_planet
+output_name: thorngren
+double_disks: True
+save_interval: 5e6  # make sure to only output final save for storage capacity reasons

jobs/paper_1_growthtracks.yaml

@@ -0,0 +1,15 @@
+# Job file, used to generate the growthtracks of planets in the first chemcomp paper (Schneider & Bitsch 2021a)
+
+par_1:
+  vals: [ 1.0e-3, 5.0e-4, 1.0e-4 ]
+  name: ALPHA
+  section: config_disk
+
+par_2:
+  vals: [3.0,10.0,30.0]
+  name: a_p
+  section: config_planet
+
+output_name: growth
+save_disk: True
+double_disks: True

jobs/paper_2_Jupiter.yaml

@@ -0,0 +1,14 @@
+# Job file, used to generate Jupiter like planets for the second chemcomp paper (Schneider & Bitsch 2021b)
+
+par_1:
+  vals: [ 1.0e-4,5.0e-4,1.0e-3 ]
+  name: ALPHA
+  section: config_disk
+
+par_2:
+  name: M0
+  vals: [ 0.0256, 0.0128, 0.00256 ]
+  section: config_disk
+
+output_name: Jup
+double_disks: False