Adding options to existing settings¶
This page will guide you through the process of adding new options to existing settings in COSMIC. This is a little simpler than adding a new setting, you can read more about how to do that here.
As an example, we will add a new option for how to handle black hole supernova kicks.
Summary checklist¶
Been here before and just making sure you’re not missing anything? Here’s a quick checklist:
src/cosmic/src: Add the new option to the relevant COSMIC code file and test your changes!docs/cosmic-settings.json: Add the new option to the JSON file
Code changes¶
First, we need to actually change the underlying COSMIC code to allow for this new option. Given that we’re
going to change black hole kicks work, this will happen in the src/cosmic/src/kick.f file.
Warning
The exact file that you need to change may differ depending on what option you change!
For example, if you were changing how mass transfer works, you’d need to change the src/cosmic/src/evolv2.f file instead.
If you’re not
familiar with the codebase, you may want to search the src/cosmic/src directory for any mention of the
setting to which you’re adding an option.
In our case, we want to add to the bhflag setting, which is used to determine how black hole supernova kicks are handled.
At the time of writing, this setting is used as follows:
src/cosmic/src/kick.f
1 ....
2
3 if(kw.eq.14.and.bhflag.eq.0)then
4 vk2 = 0.d0
5 vk = 0.d0
6 elseif(kw.eq.14.and.bhflag.eq.1)then
7 fallback = MIN(fallback,1.d0)
8 vk = MAX((1.d0-fallback)*vk,0.d0)
9 vk2 = vk*vk
10 elseif(kw.eq.14.and.bhflag.eq.2)then
11 vk = vk * mxns / m1n
12 vk2 = vk*vk
13 endif
14
15 ....
There are currently 4 options implemented for the bhflag setting, which are 0, 1, 2, and 3
(Note that the code snippet above only shows 0, 1, and 2 because 3 means that the black hole kick is not changed
from the value for neutron stars). You can see conditions for each which check that kw is 14 (which ensures
this is a black hole) and then set the kick velocity according to the bhflag value.
Let’s add a 5th option, which sets the black hole kick to double the value for neutron stars (this is of course a rather contrived example, but it serves to illustrate the process).
src/cosmic/src/kick.f
1 ....
2
3 if(kw.eq.14.and.bhflag.eq.0)then
4 vk2 = 0.d0
5 vk = 0.d0
6 elseif(kw.eq.14.and.bhflag.eq.1)then
7 fallback = MIN(fallback,1.d0)
8 vk = MAX((1.d0-fallback)*vk,0.d0)
9 vk2 = vk*vk
10 elseif(kw.eq.14.and.bhflag.eq.2)then
11 vk = vk * mxns / m1n
12 vk2 = vk*vk
13 elseif(kw.eq.14.and.bhflag.eq.4)then
14 vk = vk * 2.d0
15 vk2 = vk*vk
16 endif
17
18 ....
Documentation changes¶
Now we need to actual let COSMIC users that this new option exists. We’ll need to update this in a single place and this will propagate into the INI files and docs pages too (hurrah for structured data!)
Head over to the docs/cosmic-settings.json file and let’s add a new option to bhflag
docs/pages/inifile.rst
1 ....
2 {
3 "name": "bhflag",
4 "description": "Sets the model for how SN kicks are applied to BHs, where bhflag != 0 allows for velocity kick at BH formation",
5 "type": "dropdown",
6 "options-preface": "",
7 "options": [
8 {
9 "name": 0,
10 "description": "No BH kick"
11 },
12 {
13 "name": 1,
14 "description": "fallback-modulated kicks following <a class='reference external' href='https://ui.adsabs.harvard.edu/abs/2012ApJ...749...91F/abstract'>Fryer+2012</a>",
15 "default": true
16 },
17 {
18 "name": 2,
19 "description": "kicks decreased by ratio of BH mass to NS mass (1.44 Msun); conserves linear momentum"
20 },
21 {
22 "name": 3,
23 "description": "BH natal kicks are not decreased compared to NS kicks and are drawn from the same Maxwellian distribution with dispersion = <code>sigma</code> set above"
24 },
25 {
26 "name": 4,
27 "description": "A silly option that sets BH kicks to double the value for NSs"
28 }
29 ]
30 },
31 ....
Tip
If you’re confused about how to format your addition to the JSON file, check out cosmic-settings.json file explained to better understand this file.
This addition to the JSON file will then be used to update the Params.ini file and the config docs page with the new option.
And that’s it! You’ve successfully added a new option to an existing setting in COSMIC, nice job!