Quickstart Guide#

This guide will walk you through running your first UCLCHEM model in less than 5 minutes.

Your First Model#

Let’s model a simple molecular cloud using UCLCHEM’s object-oriented interface:

Warning

Use if __name__ == "__main__": and indent the code by one level if you want to run it as a script.

import uclchem
    # Define model parameters
params = {
    "initialDens": 1e4,      # Initial density (cm^-3)
    "initialTemp": 10.0,     # Initial temperature (K)
    "finalTime": 1e6,        # Simulation duration (years)
    "freefall": False        # Static cloud (no collapse)
}

# Create and run a Cloud model
cloud = uclchem.model.Cloud(
    param_dict=params
)

# Check if the model ran successfully
cloud.check_error()

# Obtain your results as dataframes:
phys_df, chem_df = cloud.get_dataframes(joined=False)

# Access final abundances for requested species
print(f"Final time in years: {phys_df['Time'].iloc[-1]:.2e}")
print(f"Final CO abundance: {chem_df['CO'].iloc[-1]:.2e}")
print(f"Final H2O abundance: {chem_df['H2O'].iloc[-1]:.2e}")
print(f"Final CH3OH abundance: {chem_df['CH3OH'].iloc[-1]:.2e}")

Note

The first run may take a minute as Python imports the compiled Fortran modules.

Understanding the Model Object#

When you create a Cloud object, UCLCHEM automatically:

  1. Validates your parameters

  2. Runs the chemical model

  3. Stores all results in the object

Key attributes you can access:

  • cloud.success_flag - 0 if successful, negative if error

  • cloud.final_abundances - Dict of final abundances for all species

  • cloud.physics_array - All physical parameters vs time

  • cloud.chemical_abun_array - All species abundances vs time

Getting Time-Resolved Data#

The Cloud object provides methods to access and analyze your results:

import matplotlib.pyplot as plt

# Get results as a pandas DataFrame
df = cloud.get_dataframes()

# Plot CO abundance over time
fig, ax = plt.subplots(figsize=(8, 5))
ax.loglog(df['Time'], df['CO'])
ax.set_xlabel('Time (years)')
ax.set_ylabel('CO Abundance')
ax.set_title('CO Evolution in Static Cloud')
ax.grid(True, alpha=0.3)
plt.show()

Or use the built-in plotting method:

# Quick abundance plot
fig, ax = cloud.create_abundance_plot(
    species=["CO", "H2O", "$H2O", "CH3OH", "$CH3OH"],
    figsize=(10, 6)
)

Tip

The $ symbol gets total ice abundances. For example, $H2O gives the total H2O frozen on grains.

Checking Model Quality#

Always verify that your model conserved elements correctly:

# Check elemental conservation
cloud.check_conservation(element_list=["H", "C", "N", "O", "S"])

This prints the conservation error as a percentage. Values < 1% are generally acceptable. If conservation is poor, try adjusting the solver tolerances:

params = {
    "initialDens": 1e4,
    "initialTemp": 10.0,
    "finalTime": 1e6,
    "reltol": 1e-6,    # Tighter relative tolerance
    "abstol": 1e-12    # Tighter absolute tolerance
}

Different Physics Models#

UCLCHEM includes several physics model classes:

Cloud
cloud = uclchem.model.Cloud(...)

Static or collapsing spherical cloud

Collapse
collapse = uclchem.model.Collapse(...)

Specific collapse profiles (Bonnor-Ebert, filament, etc.)

CShock
shock = uclchem.model.CShock(...)

C-type magnetohydrodynamic shock

JShock
shock = uclchem.model.JShock(...)

J-type shock discontinuity

Key Parameters#

Here are the most commonly used parameters:

Parameter

Description

Typical Values

initialDens

Initial gas density (cm⁻³)

10² - 10⁶

initialTemp

Initial temperature (K)

10 - 300

finalTime

Simulation end time (years)

10⁴ - 10⁷

freefall

Enable gravitational collapse

True / False

reltol

ODE relative tolerance

1e-4 to 1e-8

Common Scenarios#

1. Static Cloud#

params = {
    "initialDens": 1e4,
    "initialTemp": 10.0,
    "finalTime": 1e6,
    "freefall": False
}

cloud = uclchem.model.Cloud(param_dict=params)

2. Collapsing Cloud#

Model chemistry during gravitational collapse:

params = {
    "initialDens": 1e2,
    "finalDens": 1e5,
    "initialTemp": 10.0,
    "finalTime": 1e6,
    "freefall": True  # Enable collapse
}

cloud = uclchem.model.Cloud(param_dict=params)

3. Multi-Phase Chemistry#

Chain models together using previous results:

# Phase 1: Cold cloud chemistry
cold_cloud = uclchem.model.Cloud(
    param_dict={"initialTemp": 10.0, "finalTime": 1e6}
)

# Phase 2: Use previous model's final abundances as starting point
warm_cloud = uclchem.model.Cloud(
    param_dict={"initialTemp": 50.0, "finalTime": 1e5},
    starting_chemistry=cold_cloud.next_starting_chemistry
)

4. Shock Chemistry#

Model chemistry in a C-type shock:

params = {
    "initialDens": 1e3,
    "initialTemp": 10.0,
    "shockVelocity": 20.0,  # km/s
    "finalTime": 1e5
}

shock = uclchem.model.CShock(param_dict=params)

Error Handling#

The model object provides built-in error checking:

cloud = uclchem.model.Cloud(param_dict=params)

# Check for errors
cloud.check_error()  # Prints detailed error message if success_flag < 0

# Or manually check the flag
if cloud.success_flag == 0:
    print("✓ Model ran successfully")
else:
    print(f"✗ Error code: {cloud.success_flag}")
    cloud.check_error()

Common error codes:

  • 0: Success

  • -1: DVODE integrator failed

  • -2: Negative abundances encountered

  • -4/-5: Integration tolerance issues

Saving and Loading Results#

Save model results to disk:

params = {
    "initialDens": 1e4,
    "initialTemp": 10.0,
    "finalTime": 1e6,
    "outputFile": "cloud_output.dat",        # All timesteps
    "abundSaveFile": "final_abundances.dat"  # Final abundances only
}

cloud = uclchem.model.Cloud(param_dict=params)

Load a previously saved model:

cloud = uclchem.model.Cloud(read_file="cloud_output.dat")
df = cloud.get_dataframes()

Next Steps#

Now that you’ve run your first model, explore:

📓 Tutorials

Detailed notebook tutorials with visualizations

Tutorials
🔧 Parameters

Complete parameter reference

Parameters Reference
🔬 Analysis

Analyze reaction pathways

Chemical Analysis
📖 API Docs

Full Python API reference

Python API

Tips for Success#

Tip

Start simple: Begin with default parameters and add complexity gradually.

Tip

Check convergence: If the integrator fails, try decreasing reltol and abstol.

Tip

Save your work: Use outputFile parameter to save results to disk.

Warning

Network changes: After running MakeRates to change your chemical network, you must reinstall UCLCHEM with pip install .