DESPOTIC is a tool to Derive the Energetics and SPectra of Optically Thick Interstellar Clouds. It can perform a variety of calculations regarding the chemical and thermal state of interstellar clouds, and predict their observable line emission. DESPOTIC treats clouds in a simple one-zone model, and is intended to allow rapid, interactive exploration of parameter space.

In this Quickstart, we will walk through a basic interactive python session using DESPOTIC. This will work equally well from an ipython shell or in an ipython notebook.

The cloud Class

The basic object in DESPOTIC, which provides an interface to most of its functionality, is the class cloud. This class stores the basic properties of an interstellar cloud, and provides methods to perform calculations on those properties. The first step in most DESPOTIC sessions is to import this class:

from despotic import cloud

The next step is generally to input data describing a cloud upon which computations are to be performed. The input data describe the cloud’s physical properties (density, temperature, etc.), the bulk composition of the cloud, what emitting species it contains, and the radiation field around it. While it is possible to enter the data manually, it is usually easier to read the data from a file, using the Cloud Files format. For this Quickstart, we’ll use one of the configuration files that ship with DESPOTIC and that are included in the cloudfiles subdirectory of the DESPOTIC distribution. To create a cloud whose properties are as given in a particular cloud file, we simply invoke the constructor with the fileName optional argument set equal to a string containing the name of the file to be read:

gmc = cloud(fileName="cloudfiles/MilkyWayGMC.desp", verbose=True)

Note that, if you’re not running DESPOTIC from the directory where you installed it, you’ll need to include the full path to the cloudfiles subdirectory in this command. Also note the optional argument verbose, which we have set to True. Most DESPOTIC methods accept the verbose argument, which causes them to produce printed output containing a variety of information. By default DESPOTIC operations are silent.

Computing Temperatures

At this point most of the calculations one could want to do on a cloud are provided as methods of the cloud class. One of the most basic is to set the cloud to its equilibrium dust and gas temperatures. This is accomplished via the setTempEq method:


With verbose set to True, this command will produce variety of output as it iterates to calculate the equilibrium gas and dust temperatures, before finally printing True. This illustrates another feature of DESPOTIC commands: those that iterate return a value of True if they converge, and False if they do not.

To see the gas and dust temperatures to which the cloud has been set, we can simply print them:

print gmc.Tg
print gmc.Td

This shows that DESPOTIC has calculated an equilibrium gas temperature of 10.2 K, and an equilibrium dust temperature of 14.4 K.

Line Emission

Next we might wish to compute the CO line emission emerging from the cloud. We do this with the cloud method lineLum:

lines = gmc.lineLum("co")

The argument co specifies that we are interested in the emission from the CO molecule. This method returns a list of dict, each of which gives information about one of the CO lines. The dict contains a variety of fields, but one of them is the velocity-integrated brightness temperature of the line. Again, we can just print the values we want. The first element in the list is the \(J = 1 \rightarrow 0\) line, and the velocity-integrated brightness temperature is listed as intTB in the dict. Thus to get the velocity-integrated brightness temperature of the first line, we just do:

print lines[0][’intTB’]

This shows that the velocity-integrated brightness temperature of the CO \(J = 1 \rightarrow 0\) line is 79 K km/s.

Heating and Cooling Rates

Finally, we might wish to know the heating and cooling rates produced by various processes, which lets us determined what sets the thermal balance in the cloud. This may be computed using the method dEdt, as follows:

rates = gmc.dEdt()

This method returns a dict that contains all the heating and cooling terms for gas and dust. For example, we can print the rates of cosmic ray heating and CO line cooling via:

print rates["GammaCR"]
print rates["LambdaLine"]["co"]