{ "cells": [ { "cell_type": "markdown", "id": "033c064b", "metadata": {}, "source": [ "# Running Your First Models with Objects\n", "\n", "In this notebook, we demonstrate the basic use of UCLCHEM's python module by running a simple model and then using the analysis functions to examine the output. Otherwise, it is identical to notebook 3." ] }, { "cell_type": "code", "execution_count": 1, "id": "d7e3396e", "metadata": { "execution": { "iopub.execute_input": "2026-01-27T12:59:41.049239Z", "iopub.status.busy": "2026-01-27T12:59:41.048988Z", "iopub.status.idle": "2026-01-27T12:59:42.371679Z", "shell.execute_reply": "2026-01-27T12:59:42.370934Z" } }, "outputs": [], "source": [ "import uclchem" ] }, { "cell_type": "markdown", "id": "549a6bcf", "metadata": {}, "source": [ "## A Simple Cloud\n", "\n", "UCLCHEM's `Cloud` class, models a spherical cloud of isothermal gas. We can keep a constant density or have it increase over time following a freefall equation. This model is generally useful whenever you want to model a homogeneous cloud of gas under constant conditions. For example, in the inner parts of a molecular cloud where Av $\\gtrsim$ 10 there are very few depth dependent processes. You may wish to model the whole of this UV shielded portion of the cloud with a single `Cloud` model.\n", "\n", "Due to the large number of parameters in a chemical model and the way fortran and python interaction, we find it is easiest to do parameter input through python dictionaries. In this block, we define param_dict which contains the parameters we wish to modify for this run. Every `uclchem.model` class accepts a dictionary as an optional argument. Every parameter has a default value which is overridden if that parameter is specified in this dictionary. You can find a complete list of modifiable parameters and their default values in [our parameter docs](/docs/parameters)." ] }, { "cell_type": "code", "execution_count": 2, "id": "1c6ea598", "metadata": { "execution": { "iopub.execute_input": "2026-01-27T12:59:42.373856Z", "iopub.status.busy": "2026-01-27T12:59:42.373549Z", "iopub.status.idle": "2026-01-27T12:59:45.441881Z", "shell.execute_reply": "2026-01-27T12:59:45.441108Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Model ran successfully.\n" ] } ], "source": [ "# set a parameter dictionary for phase 1 collapse model\n", "out_species = [\"SO\", \"CO\"]\n", "param_dict = {\n", " \"endAtFinalDensity\": False, # stop at finalTime\n", " \"freefall\": False, # don't increase density in freefall\n", " \"initialDens\": 1e4, # starting density\n", " \"initialTemp\": 10.0, # temperature of gas\n", " \"finalTime\": 1.0e6, # final time\n", " \"rout\": 0.1, # radius of cloud in pc\n", " \"baseAv\": 1.0, # visual extinction at cloud edge.\n", "}\n", "cloud = uclchem.model.Cloud(param_dict=param_dict, out_species=out_species)\n", "cloud.check_error()" ] }, { "cell_type": "markdown", "id": "a5ddfcc4", "metadata": {}, "source": [ "## Checking the output\n", "\n", "The code above produced the object `cloud` which holds the variables associated to the model that UCLCHEM calculated. Calling `cloud.success_flag` would exposes the variable `success_flag` which will be 0 if the model was run successfully, and negative if not. You can check an error value by calling cloud.check_error() to get a more detailed error message.\n", "\n", "Additionally, the `cloud` object holds the physical parameters and chemical abundance arrays calculated by UCLCHEM. These are stored in `cloud.physics_array` and `cloud.chemical_abun_array` respectively. If we wish to see just the abundances of the final time step, we can get that array with `cloud.next_starting_chemistry`, bearing in mind that the variable `cloud.starting_chemistry` contains the array of abundances that the model started with, if it was provided to the object.\n", "\n", "If `abundSaveFile` was added to the `param_dict`, then the final abundances of all species would be written to the file listed in `abundSaveFile`. If `outputFile` is added, then all abundances and physical parameters for all time steps will be written to the file `outputFile`.\n", "\n", "The UCLCHEM model classes have methods to reformat the output arrays into pandas dataframes, as well as having the option to read previously run model output files. To retrieve a pandas dataframe of a model we can call `cloud.get_dataframes(point = 0)` where the point optional input allows us to choose which point we wish to retrieve the dataframe for, if we ran a multipoint model. This method defaults the `point` value to 0 to retrieve the central point." ] }, { "cell_type": "code", "execution_count": 3, "id": "ecbe41da", "metadata": { "execution": { "iopub.execute_input": "2026-01-27T12:59:45.443733Z", "iopub.status.busy": "2026-01-27T12:59:45.443561Z", "iopub.status.idle": "2026-01-27T12:59:45.464726Z", "shell.execute_reply": "2026-01-27T12:59:45.464003Z" } }, "outputs": [ { "data": { "text/html": [ "
| \n", " | Time | \n", "Density | \n", "gasTemp | \n", "dustTemp | \n", "Av | \n", "radfield | \n", "zeta | \n", "dstep | \n", "H | \n", "H+ | \n", "... | \n", "@OCS | \n", "@C4N | \n", "@SIC3 | \n", "@SO2 | \n", "@S2 | \n", "@HS2 | \n", "@H2S2 | \n", "E- | \n", "BULK | \n", "SURFACE | \n", "
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | \n", "1.000000e-07 | \n", "10000.0 | \n", "10.0 | \n", "10.0 | \n", "2.92875 | \n", "1.0 | \n", "2.910002 | \n", "1.0 | \n", "0.5 | \n", "9.674388e-18 | \n", "... | \n", "1.000000e-30 | \n", "1.000000e-30 | \n", "1.000000e-30 | \n", "1.000000e-30 | \n", "1.000000e-30 | \n", "1.000000e-30 | \n", "1.000000e-30 | \n", "0.000182 | \n", "5.613460e-20 | \n", "7.478491e-13 | \n", "
| 1 | \n", "1.000000e-06 | \n", "10000.0 | \n", "10.0 | \n", "10.0 | \n", "2.92875 | \n", "1.0 | \n", "2.910002 | \n", "1.0 | \n", "0.5 | \n", "2.630577e-16 | \n", "... | \n", "1.000001e-30 | \n", "1.000001e-30 | \n", "1.000001e-30 | \n", "1.000001e-30 | \n", "1.000001e-30 | \n", "1.000001e-30 | \n", "1.000001e-30 | \n", "0.000182 | \n", "5.546864e-18 | \n", "7.434018e-12 | \n", "
| 2 | \n", "1.000000e-05 | \n", "10000.0 | \n", "10.0 | \n", "10.0 | \n", "2.92875 | \n", "1.0 | \n", "2.910002 | \n", "1.0 | \n", "0.5 | \n", "2.798139e-15 | \n", "... | \n", "1.000015e-30 | \n", "1.000015e-30 | \n", "1.000015e-30 | \n", "1.000015e-30 | \n", "1.000015e-30 | \n", "1.000015e-30 | \n", "1.000015e-30 | \n", "0.000182 | \n", "5.538897e-16 | \n", "7.428646e-11 | \n", "
| 3 | \n", "1.000000e-04 | \n", "10000.0 | \n", "10.0 | \n", "10.0 | \n", "2.92875 | \n", "1.0 | \n", "2.910002 | \n", "1.0 | \n", "0.5 | \n", "2.827256e-14 | \n", "... | \n", "1.000147e-30 | \n", "1.000147e-30 | \n", "1.000147e-30 | \n", "1.000147e-30 | \n", "1.000147e-30 | \n", "1.000147e-30 | \n", "1.000148e-30 | \n", "0.000182 | \n", "5.418362e-14 | \n", "7.347047e-10 | \n", "
| 4 | \n", "1.000000e-03 | \n", "10000.0 | \n", "10.0 | \n", "10.0 | \n", "2.92875 | \n", "1.0 | \n", "2.910002 | \n", "1.0 | \n", "0.5 | \n", "2.943250e-13 | \n", "... | \n", "1.001110e-30 | \n", "1.001110e-30 | \n", "1.001110e-30 | \n", "1.001110e-30 | \n", "1.000926e-30 | \n", "1.001081e-30 | \n", "1.001335e-30 | \n", "0.000182 | \n", "3.072463e-12 | \n", "5.530733e-09 | \n", "
5 rows × 343 columns
\n", "