Skip to main content
Version: Develop 🚧

Advanced Modelling in Memory

In the previous tutorial, we simply modelled the chemistry of a static cloud for 1 Myr. This is unlikely to meet everybody's modelling needs and UCLCHEM is capable of modelling much more complex environments such as hot cores and shocks. In this tutorial, we model both a hot core and a shock to explore how these models work and to demonstrate the workflow that the UCLCHEM team normally follow.

import uclchem
import matplotlib.pyplot as plt
import pandas as pd

The Hot Core​

Initial Conditions (Phase 1)​

UCLCHEM typically starts with the gas in atomic/ionic form with no molecules. However, this clearly is not appropriate when modelling an object such as a hot core. In these objects, the gas is already evolved and there should be molecules in the gas phase as well as ice mantles on the dust. To allow for this, one must provide some initial abundances to the model. There are many ways to do this but we typically chose to run a preliminary model to produce our abundances. In many UCLCHEM papers, we refer to the preliminary model as phase 1 and the science model as phase 2. Phase 1 simply models a collapsing cloud and phase 2 models the object in question.

To do this, we will use uclchem.model.cloud() to run a model where a cloud of gas collapses from a density of 102cm−310^2 cm^{-3} to our hot core density of 106cm−310^6 cm^{-3}, keeping all other parameters constant. During this collapse, chemistry will occur and we can assume the final abundances of this model will be reasonable starting abundances for the hot core.

# set a parameter dictionary for cloud collapse model
param_dict = {
    "endAtFinalDensity": False,  # stop at finalTime
    "freefall": True,  # increase density in freefall
    "initialDens": 1e2,  # starting density
    "finalDens": 1e6,  # final density
    "initialTemp": 10.0,  # temperature of gas
    "finalTime": 6.0e6,  # final time
    "rout": 0.1,  # radius of cloud in pc
    "baseAv": 1.0,  # visual extinction at cloud edge.
}
df_stage1_physics, df_stage1_chemistry, final_abundances, result = uclchem.model.cloud(
    param_dict=param_dict,
    return_dataframe=True,
)
df_stage1_chemistry
H#HH+@HH2#H2H2+@H2H3+HE...HOSO+#HS2@HS2H2S2+H2S2#H2S2@H2S2E-BULKSURFACE
05.000000e-011.000000e-301.000000e-301.000000e-300.2500001.000000e-301.000000e-301.000000e-301.000000e-300.1...1.000000e-301.000000e-301.000000e-301.000000e-301.000000e-301.000000e-301.000000e-301.823239e-041.000000e-301.000000e-30
15.000000e-015.685982e-159.674341e-184.369999e-240.2500001.798170e-159.479999e-181.381996e-247.975011e-250.1...1.000000e-301.000000e-301.000000e-301.000000e-301.000000e-301.000000e-301.000000e-301.823239e-045.753474e-247.485971e-15
25.000000e-015.609168e-149.674345e-174.159792e-220.2500001.773873e-149.479987e-171.315516e-227.800677e-230.1...1.000000e-301.000000e-301.000000e-301.000000e-301.018663e-301.000000e-301.000000e-301.823239e-045.476646e-227.384844e-14
35.000000e-015.601469e-139.674388e-164.146187e-200.2500001.771405e-139.479870e-161.311196e-207.796567e-210.1...1.000000e-301.000000e-301.000000e-301.000000e-301.037104e-301.000000e-301.000000e-301.823239e-045.458717e-207.374677e-13
45.000000e-015.599065e-129.674822e-154.143311e-180.2500001.771456e-129.478701e-151.310530e-187.795795e-190.1...1.000000e-301.000000e-301.000001e-301.000000e-301.055260e-301.000000e-301.000001e-301.823239e-045.455175e-187.372323e-12
..................................................................
2392.782454e-085.447687e-121.267702e-084.439699e-080.0400854.967814e-066.656903e-154.597508e-011.262364e-100.1...3.031539e-261.470339e-213.223446e-081.191161e-191.213303e-171.118699e-134.626349e-081.295096e-084.601412e-014.981617e-06
2402.783604e-085.447844e-121.266826e-084.439713e-080.0400854.967798e-066.656878e-154.597510e-011.263195e-100.1...2.743701e-261.339404e-213.223446e-081.081060e-191.101172e-171.014655e-134.626349e-081.294225e-084.601414e-014.981617e-06
2412.784612e-085.447982e-121.266057e-084.439726e-080.0400844.967784e-066.656857e-154.597511e-011.263924e-100.1...2.489475e-261.223754e-213.223446e-089.836525e-201.001964e-179.227183e-144.626350e-081.293460e-084.601415e-014.981617e-06
2422.785501e-085.448103e-121.265379e-084.439738e-080.0400844.967771e-066.656838e-154.597512e-011.264568e-100.1...2.263830e-261.121072e-213.223446e-088.970411e-209.137506e-188.410604e-144.626350e-081.292786e-084.601416e-014.981617e-06
2432.786288e-085.448211e-121.264778e-084.439748e-080.0400844.967759e-066.656821e-154.597513e-011.265139e-100.1...2.062682e-261.029487e-213.223446e-088.196884e-208.349652e-187.682017e-144.626350e-081.292189e-084.601417e-014.981617e-06

244 rows × 335 columns

With that done, we now have a file containing the final abundances of a cloud of gas after this collapse: param_dict["abundSaveFile"] we can pass this to our hot core model to use those abundances as our initial abundances.

Running the Science Model (Phase 2)​

We need to change just a few things in param_dict to set up the hot core model. The key one is that UCLCHEM saves final abundances to abundSaveFile but loads them from abundLoadFile so we need to swap that key over to make the abundances we just produced our initial abundances.

We also want to turn off freefall and change how long the model runs for.

# change other bits of input to set up phase 2
param_dict["initialDens"] = 1e6
param_dict["finalTime"] = 1e6
param_dict["freefall"] = False

# freeze out is completely overwhelmed by thermal desorption
# so turning it off has no effect on abundances but speeds up integrator.
param_dict["freezeFactor"] = 0.0

# param_dict["abstol_factor"]=1e-18
# param_dict["reltol"]=1e-12

df_stage2_physics, df_stage2_chemistry, final_abundances, result = (
    uclchem.model.hot_core(
        temp_indx=3,
        max_temperature=300.0,
        param_dict=param_dict,
        return_dataframe=True,
        starting_chemistry=final_abundances,
    )
)

At T(=R1) and step size H(=R2), the
corrector convergence failed repeatedly
or with ABS(H) = HMIN.
In the above message, R1 = 0.7284459966846D+13 R2 = 0.5318067845400D+02 ISTATE -5 - shortening step at time 230520.88502676319 years

df_stage2 = pd.concat((df_stage2_physics, df_stage2_chemistry), axis=1)
df_stage2
TimeDensitygasTempdustTempAvradfieldzetadstepH#H...HOSO+#HS2@HS2H2S2+H2S2#H2S2@H2S2E-BULKSURFACE
00.000000e+001000000.010.00000010.000000193.8751.01.01.02.786288e-085.448211e-12...2.062682e-261.029487e-213.223446e-088.196884e-208.349652e-187.682017e-144.626350e-081.292189e-084.601417e-014.981617e-06
11.000000e-071000000.010.00000010.000000193.8751.01.01.02.786288e-085.448206e-12...2.062682e-262.028008e-193.223446e-088.196884e-208.349652e-187.682046e-144.626350e-081.292189e-084.601417e-014.981617e-06
21.000000e-061000000.010.00000010.000000193.8751.01.01.02.786288e-085.448166e-12...2.062682e-262.018742e-183.223446e-088.196884e-208.349652e-187.682307e-144.626350e-081.292189e-084.601417e-014.981617e-06
31.000000e-051000000.010.00000010.000000193.8751.01.01.02.786288e-085.447767e-12...2.062682e-262.017808e-173.223446e-088.196884e-208.349652e-187.684913e-144.626350e-081.292189e-084.601417e-014.981617e-06
41.000000e-041000000.010.00000310.000003193.8751.01.01.02.786288e-085.443612e-12...2.062682e-262.017639e-163.223446e-088.196885e-208.349652e-187.710978e-144.626350e-081.292189e-084.601417e-014.981617e-06
..................................................................
1899.601000e+051000000.0300.000000300.000000193.8751.01.01.02.624023e-062.543694e-30...6.347300e-161.000000e-301.000000e-305.819436e-142.228318e-081.000000e-301.000000e-302.302194e-088.300000e-296.775334e-23
1909.701000e+051000000.0300.000000300.000000193.8751.01.01.02.628702e-062.565091e-30...6.164580e-161.000000e-301.000000e-305.607756e-142.209859e-081.000000e-301.000000e-302.292692e-088.300000e-296.775334e-23
1919.801000e+051000000.0300.000000300.000000193.8751.01.01.02.633295e-062.586495e-30...5.982646e-161.000000e-301.000000e-305.402869e-142.191553e-081.000000e-301.000000e-302.283211e-088.300000e-296.775334e-23
1929.901000e+051000000.0300.000000300.000000193.8751.01.01.02.637800e-062.607905e-30...5.801697e-161.000000e-301.000000e-305.204638e-142.173399e-081.000000e-301.000000e-302.273747e-088.300000e-296.775334e-23
1931.000100e+061000000.0300.000000300.000000193.8751.01.01.02.642215e-062.629322e-30...5.621926e-161.000000e-301.000000e-305.012925e-142.155398e-081.000000e-301.000000e-302.264300e-088.300000e-296.775335e-23

194 rows × 343 columns

Note that we've changed made two changes to the parameters here which aren't strictly necessary but can be helpful in certain situations.

Since the gas temperature increases throughout a hot core model, freeze out is much slower than thermal desorption for all but the first few time steps. Turning it off doesn't affect the abundances but will speed up the solution.

We also change abstol and reltol here, largely to demonstrate their use. They control the integrator accuracy and whilst making them smaller does slow down successful runs, it can make runs complete that stall completely otherwise or give correct solutions where lower tolerances allow issues like element conservation failure to sneak in. If your code does not complete or element conservation fails, you can change them.

Checking the Result​

With a successful run, we can check the output. We first load the file and check the abundance conservation, then we can plot it up.

# phase2_df=uclchem.analysis.read_output_file("../examples/test-output/phase2-full.dat")
uclchem.analysis.check_element_conservation(df_stage2)

{'H': '0.002%', 'N': '0.000%', 'C': '0.000%', 'O': '0.000%'}

# df_stage2.rename(columns={"age":"Time", "density":"Density"}, inplace=True)
df_stage2.iloc[0]

Time 0.000000e+00 Density 1.000000e+06 gasTemp 1.000000e+01 dustTemp 1.000000e+01 Av 1.938750e+02 ...
#H2S2 7.682017e-14 @H2S2 4.626350e-08 E- 1.292189e-08 BULK 4.601417e-01 SURFACE 4.981617e-06 Name: 0, Length: 343, dtype: float64

species = ["CO", "H2O", "CH3OH", "#CO", "#H2O", "#CH3OH", "@H2O", "@CO", "@CH3OH"]
fig, [ax, ax2] = plt.subplots(1, 2, figsize=(16, 9))
ax = uclchem.analysis.plot_species(ax, df_stage2, species)
settings = ax.set(
    yscale="log",
    xlim=(1e2, 1e6),
    ylim=(1e-10, 1e-2),
    xlabel="Time / years",
    ylabel="Fractional Abundance",
    xscale="log",
)

ax2.plot(df_stage2["Time"], df_stage2["Density"], color="black")
ax2.set(xscale="log")
ax3 = ax2.twinx()
ax3.plot(df_stage2["Time"], df_stage2["gasTemp"], color="red")
ax2.set(xlabel="Time / year", ylabel="Density")
ax3.set(ylabel="Temperature", facecolor="red", xlim=(1e2, 1e6))
ax3.tick_params(axis="y", colors="red")

CO H2O CH3OH #CO #H2O #CH3OH @H2O @CO @CH3OH

png

Here, we see the value of running a collapse phase before the science run. Having run a collapse, we start this model with well developed ices and having material in the surface and bulk allows us to properly model the effect of warm up in a hot core. For example, the @CO abundance is ∼10−4\sim10^{-4} and #CO is ∼10−6\sim10^{-6}. As the gas warms to around 30K, the #CO abundance drops drastically as CO's binding energy is such that it is efficiently desorbed from the surface at this temperature. However, the rest of the CO is trapped in the bulk, surrounded by more strongly bound H2O molecules. Thus, the @CO abundance stays high until the gas reaches around 130K, when the H2O molecules are released along with the entire bulk.

Shocks​

Essentially the same process should be followed for shocks. Let's run a C-type and J-type shock through a gas of density 104cm−310^4 cm^{-3}. Again, we first run a simple cloud model to obtain some reasonable starting abundances, then we can run the shocks.

# set a parameter dictionary for phase 1 collapse model

param_dict = {
    "endAtFinalDensity": False,  # stop at finalTime
    "freefall": True,  # increase density in freefall
    "initialDens": 1e2,  # starting density
    "finalDens": 1e4,  # final density
    "initialTemp": 10.0,  # temperature of gas
    "finalTime": 6.0e6,  # final time
    "rout": 0.1,  # radius of cloud in pc
    "baseAv": 1.0,  # visual extinction at cloud edge.
    # "abundSaveFile": "../examples/test-output/shockstart.dat",
}
df_stage1_physics, df_stage1_chemistry, final_abundances, result = uclchem.model.cloud(
    param_dict=param_dict,
    return_dataframe=True,
)

C-shock​

We'll first run a c-shock. We'll run a 40 km s −1^{-1} shock through a gas of density 10410^4 cm −3^{-3}, using the abundances we just produced. Note that c-shock is the only model which returns an additional output in its result list. Not only is the first element the success flag indicating whether UCLCHEM completed, the second element is the dissipation time of the shock. We'll use that time to make our plots look nicer, cutting to a reasonable time. You can also obtain it from uclchem.utils.cshock_dissipation_time().

# change other bits of input to set up phase 2
param_dict["initialDens"] = 1e4
param_dict["finalTime"] = 1e6
if "abundSaveFile" in param_dict:
    param_dict.pop("abundSaveFile")
# param_dict["abundLoadFile"]="../examples/test-output/shockstart.dat"
# param_dict["outputFile"]="../examples/test-output/cshock.dat"


df_stage2_physics, df_stage2_chemistry, dissipation_time, final_abundances, result = (
    uclchem.model.cshock(
        shock_vel=40,
        param_dict=param_dict,
        return_dataframe=True,
        starting_chemistry=final_abundances,
    )
)
# result,dissipation_time=result

Cannot have freefall on during cshock setting freefall=0 and continuing

The code completes fine. We do get a couple of warnings though. First, we're informed that freefall must be set to False for the C-shock model. Then we get a few integrator warnings. These are not important and can be ignored as long as the element conservation looks ok. However, it is an indication that the integrator did struggle with these ODEs under these conditions.

df_stage2 = pd.concat((df_stage2_physics, df_stage2_chemistry), axis=1)
uclchem.analysis.check_element_conservation(df_stage2)

{'H': '0.005%', 'N': '1.257%', 'C': '1.458%', 'O': '1.302%'}

# df_stage2.rename(columns={"age":"Time", "density":"Density"}, inplace=True)
species = ["CO", "H2O", "CH3OH", "NH3", "$CO", "$H2O", "$CH3OH", "$NH3"]

fig, [ax, ax2] = plt.subplots(1, 2, figsize=(16, 9))
ax = uclchem.analysis.plot_species(ax, df_stage2, species)
settings = ax.set(
    yscale="log",
    xlim=(1, 20 * dissipation_time),
    ylim=(1e-10, 1e-2),
    xlabel="Time / years",
    ylabel="Fractional Abundance",
    xscale="log",
)

ax2.plot(df_stage2["Time"], df_stage2["Density"], color="black")
ax2.set(xscale="log")
ax3 = ax2.twinx()
ax3.plot(df_stage2["Time"], df_stage2["gasTemp"], color="red")
ax2.set(xlabel="Time / year", ylabel="Density")
ax3.set(ylabel="Temperature", facecolor="red", xlim=(1, 20 * dissipation_time))
ax3.tick_params(axis="y", colors="red")

CO H2O CH3OH NH3 COCO H2O CH3OHCH3OH NH3

png

J-shock​

Running a j-shock is a simple case of changing function. We'll run a 10 km s −1^{-1} shock through a gas of density 10310^3 cm −3^{-3} gas this time. Note that nothing stops us using the intial abundances we produced for the c-shock. UCLCHEM will not check that the initial density matches the density of the abundLoadFile. It may not always be a good idea to do this but we should remember the intial abundances really are just a rough approximation.

By default UCLCHEM uses 500 timepoints for a model, but this turns out not be enough, which is why we increase the number of timepoints to 1500.

# TODO: maybe add a function/method to adjust the number of timepoints in UCLCHEM WITHOUT restarting the kernel

param_dict["initialDens"] = 1e3
param_dict["freefall"] = False  # lets remember to turn it off this time
param_dict["reltol"] = 1e-12

shock_vel = 10.0

df_jshock_physics, df_jshock_chemistry, final_abundances, result = uclchem.model.jshock(
    shock_vel=shock_vel,
    param_dict=param_dict,
    return_dataframe=True,
    starting_chemistry=final_abundances,
    timepoints=1500,
)

This time, we've turned off the freefall option and made reltol a little more stringent. The j-shock ends up running a bit slower but we get no warnings on this run.

df_jshock = pd.concat((df_jshock_physics, df_jshock_chemistry), axis=1)
# df_jshock.rename(columns={"age":"Time", "density":"Density"}, inplace=True)
uclchem.analysis.check_element_conservation(df_jshock)

{'H': '0.102%', 'N': '1.568%', 'C': '1.138%', 'O': '1.688%'}

df_jshock.shape

(1317, 343)

species = ["CO", "H2O", "CH3OH", "NH3", "$CO", "$H2O", "$CH3OH", "$NH3"]

fig, [ax, ax2] = plt.subplots(1, 2, figsize=(16, 9))
ax = uclchem.analysis.plot_species(ax, df_jshock, species)
settings = ax.set(
    yscale="log",
    xlim=(1e-7, 1e6),
    ylim=(1e-10, 1e-2),
    xlabel="Time / years",
    ylabel="Fractional Abundance",
    xscale="log",
)

ax2.plot(df_jshock["Time"], df_jshock["Density"], color="black")
ax2.set(xscale="log", yscale="log")
ax3 = ax2.twinx()
ax3.plot(df_jshock["Time"], df_jshock["gasTemp"], color="red")
ax2.set(xlabel="Time / year", ylabel="Density")
ax3.set(ylabel="Temperature", facecolor="red", xlim=(1e-7, 1e6))
ax3.tick_params(axis="y", colors="red")

CO H2O CH3OH NH3 COCO H2O CH3OHCH3OH NH3

png

That's everything! We've run various science models using reasonable starting abundances that we produced by running a simple UCLCHEM model beforehand. One benefit of this method is that the abundances are consistent with the network. If we start with arbitrary, perhaps observationally motivated, abundances, it would be possible to initiate the model in a state our network could never produce.

However, one should be aware of the limitations of this method. A freefall collapse from low density to high is not really how a molecular cloud forms and so the abundances are only approximately similar to values they'd truly have in a real cloud. Testing whether your results are sensitive to things like the time you run the preliminary for or the exact density is a good way to make sure these approximations are not problematic.

Bear in mind that you can use abundSaveFile and abundLoadFile in the same model run. This lets you chain model runs together. For example, you could run a c-shock from a cloud model as we did here and then a j-shock with the c-shock's abundances as the initial abundances.

Last updated on by Gijs Vermariën