User Guide#

Comprehensive guides covering UCLCHEM’s features, physics models, and parameters.

Guide Sections#

🌌 Physics Models

Understanding UCLCHEM’s different physics modules

Physics Models

⚙️ Parameters

Complete reference for all model parameters

Parameters Reference

🔬 Chemical Networks

How UCLCHEM handles gas-grain chemistry

Chemical Networks

🛠️ MakeRates

Creating and modifying chemical networks

MakeRates Guide

Physics Models

Troubleshooting

Overview#

UCLCHEM is designed to model the time-dependent chemistry of astrophysical environments. It solves the ordinary differential equations (ODEs) describing the evolution of chemical abundances under various physical conditions.

Key Concepts#

Hybrid Architecture: UCLCHEM combines Python (user interface) with Fortran (numerical computation) for both ease of use and performance.

Gas-Grain Chemistry: Models both gas-phase reactions and surface chemistry on dust grains.

Flexible Physics: Multiple physics modules support different astrophysical scenarios (clouds, cores, shocks).

Customizable Networks: Create specialized chemical networks with the MakeRates tool.

Quick Reference#

Physics Models#

Model	Function	Use Case
Cloud	`uclchem.model.cloud()`	Static or collapsing spherical clouds
Collapse	`uclchem.model.collapse()`	Specific collapse profiles (BE, filament, etc.)
C-Shock	`uclchem.model.cshock()`	Magnetohydrodynamic shocks
J-Shock	`uclchem.model.jshock()`	Discontinuous shocks

See Physics Models for details.

Common Parameters#

Parameter	Type	Description
`initialDens`	float	Initial gas density (cm⁻³)
`initialTemp`	float	Initial temperature (K)
`finalTime`	float	Simulation end time (years)
`freefall`	bool	Enable gravitational collapse
`zeta`	float	Cosmic ray ionization rate (s⁻¹)
`radfield`	float	UV radiation field (Habing units)

See Parameters for the complete list.

Workflow Overview#

A typical UCLCHEM workflow:

Choose a physics model - Select the appropriate model for your scenario
Set parameters - Define initial conditions and physical parameters
Run the model - Execute the simulation
Analyze results - Extract abundances, reaction rates, etc.
Iterate - Refine parameters or try different conditions

Best Practices#

Tip

Start with defaults: All parameters have sensible defaults. Override only what you need.

Tip

Check convergence: Monitor the success flag and consider adjusting solver tolerances if needed.

Tip

Document your models: Keep track of parameter choices for reproducibility.

Warning

Network modifications require reinstallation: After running MakeRates, always pip install . to recompile.

Getting Help#

Tutorials: See Tutorials for worked examples
API Reference: Check API docs for function details
GitHub: Report issues or ask questions on GitHub
Papers: Read published papers using UCLCHEM