{ "cells": [ { "cell_type": "markdown", "id": "2c5bcfbe", "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": "5fbfb864", "metadata": { "execution": { "iopub.execute_input": "2026-06-19T14:32:26.006524Z", "iopub.status.busy": "2026-06-19T14:32:26.006336Z", "iopub.status.idle": "2026-06-19T14:32:26.789473Z", "shell.execute_reply": "2026-06-19T14:32:26.788523Z" } }, "outputs": [], "source": [ "import uclchem" ] }, { "cell_type": "markdown", "id": "7fde9de9", "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": "35f3a595", "metadata": { "execution": { "iopub.execute_input": "2026-06-19T14:32:26.791713Z", "iopub.status.busy": "2026-06-19T14:32:26.791381Z", "iopub.status.idle": "2026-06-19T14:32:30.934680Z", "shell.execute_reply": "2026-06-19T14:32:30.933795Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Model ran successfully\n" ] } ], "source": [ "# set a parameter dictionary for phase 1 collapse model\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)\n", "cloud.check_error()" ] }, { "cell_type": "markdown", "id": "3e7b86f2", "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_joined_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": "c90c200e", "metadata": { "execution": { "iopub.execute_input": "2026-06-19T14:32:30.936653Z", "iopub.status.busy": "2026-06-19T14:32:30.936459Z", "iopub.status.idle": "2026-06-19T14:32:30.962262Z", "shell.execute_reply": "2026-06-19T14:32:30.961365Z" } }, "outputs": [ { "data": { "text/html": [ "
| \n", " | Point | \n", "Time | \n", "Density | \n", "gasTemp | \n", "dustTemp | \n", "Av | \n", "radfield | \n", "zeta | \n", "dstep | \n", "parcel_radius | \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 | \n", "1.000000e-07 | \n", "10010.000467 | \n", "10.0 | \n", "10.0 | \n", "2.930679 | \n", "1.0 | \n", "1.0 | \n", "1.0 | \n", "0.0 | \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", "1.519714e-20 | \n", "5.704244e-13 | \n", "
| 1 | \n", "1 | \n", "2.000000e-07 | \n", "10010.000467 | \n", "10.0 | \n", "10.0 | \n", "2.930679 | \n", "1.0 | \n", "1.0 | \n", "1.0 | \n", "0.0 | \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.384650e-20 | \n", "1.083760e-12 | \n", "
| 2 | \n", "1 | \n", "4.000000e-07 | \n", "10010.000467 | \n", "10.0 | \n", "10.0 | \n", "2.930679 | \n", "1.0 | \n", "1.0 | \n", "1.0 | \n", "0.0 | \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", "1.813428e-19 | \n", "2.095576e-12 | \n", "
| 3 | \n", "1 | \n", "6.000000e-07 | \n", "10010.000467 | \n", "10.0 | \n", "10.0 | \n", "2.930679 | \n", "1.0 | \n", "1.0 | \n", "1.0 | \n", "0.0 | \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", "3.950986e-19 | \n", "3.134571e-12 | \n", "
| 4 | \n", "1 | \n", "8.000000e-07 | \n", "10010.000467 | \n", "10.0 | \n", "10.0 | \n", "2.930679 | \n", "1.0 | \n", "1.0 | \n", "1.0 | \n", "0.0 | \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", "6.925109e-19 | \n", "4.172658e-12 | \n", "
5 rows × 347 columns
\n", "