Parameters Reference#

UCLCHEM models are controlled through a dictionary of parameters passed to model classes or functions. This page explains how to use parameters and provides quick reference.

Quick Start#

Parameters are passed as a dictionary to any UCLCHEM model:

import uclchem

# Create a cloud model with custom parameters
cloud = uclchem.model.Cloud(
    param_dict={
        "initialDens": 1e4,      # Initial density (cm⁻³)
        "initialTemp": 10.0,     # Initial temperature (K)
        "finalTime": 1e6,        # End time (years)
        "freefall": True,        # Enable freefall collapse
        "finalDens": 1e7,        # Final density for freefall
    },
    out_species=["CO", "H2O", "CH3OH"]
)

Any parameter not specified will use its default value.

Complete Parameter Reference#

All Fortran parameters are automatically documented at build time:

/api/fortran/index - Complete reference for all Fortran modules and parameters

This documentation is generated directly from the compiled code, ensuring it matches your installed version exactly.

Runtime Introspection#

You can also inspect parameters at runtime using the advanced API:

import uclchem

# Get all parameter values
settings = uclchem.advanced.GeneralSettings()

# Print all parameters from defaultparameters module
settings.defaultparameters.print_settings()

# Access individual parameters
print(settings.defaultparameters.initialdens.get())  # 100.0
print(settings.defaultparameters.finaltime.get())    # 5000000.0

# List all available Fortran modules
settings.list_modules()

PhysicalParameters - Density, temperature, radiation fields
TimeParameters - Simulation duration and freefall
ChemistryParameters - Desorption and freeze-out controls
AbundanceParameters - Initial elemental abundances
SolverParameters - ODE integration tolerances (advanced)
IOParameters - File paths for input/output
AdvancedParameters - Desorption physics (experts only)

See get_all_parameters() to get all current values programmatically.

Or browse the full API: /api/uclchem/parameters/index

Common Examples#

Basic Cloud Model#

# Static cloud at constant density
cloud = uclchem.model.Cloud(
    param_dict={
        "initialDens": 1e4,
        "initialTemp": 10.0,
        "finalTime": 1e6,
    }
)

Collapsing Cloud#

# Cloud undergoing freefall collapse
cloud = uclchem.model.Cloud(
    param_dict={
        "initialDens": 1e2,
        "finalDens": 1e7,
        "freefall": True,
        "freefallFactor": 1.0,
        "endAtFinalDensity": True,
    }
)

Custom Abundances#

# Cloud with custom carbon and oxygen abundances
cloud = uclchem.model.Cloud(
    param_dict={
        "initialDens": 1e4,
        "fc": 2.0e-4,  # Double carbon abundance
        "fo": 5.0e-4,  # Custom oxygen abundance
        "metallicity": 0.5,  # Scale all metals to 50% solar
    }
)

Controlling Desorption#

# Turn off non-thermal desorption
cloud = uclchem.model.Cloud(
    param_dict={
        "initialDens": 1e4,
        "desorb": False,  # Master switch
        # Or control individually:
        # "h2desorb": False,
        # "crdesorb": False,  
        # "uvdesorb": False,
    }
)

Tips and Best Practices#

Tip

Parameter names are case-insensitive: You can write initialDens, InitialDens, or INITIALDDENS - they all work!

Warning

Solver tolerances affect accuracy and speed:

Decrease reltol for higher accuracy (but slower)
If you get integration errors, see our troubleshooting guide

Note

Default values work for most cases: You only need to specify parameters you want to change. All others use sensible defaults from the source code.

Advanced Usage#

Saving and Loading Abundances#

# Save final abundances for later use
cloud1 = uclchem.model.Cloud(
    param_dict={
        "initialDens": 1e4,
        "finalTime": 1e6,
        "abundSaveFile": "my_abundances.dat"
    }
)

# Load those abundances as initial conditions for next stage
cloud2 = uclchem.model.Cloud(
    param_dict={
        "initialDens": 1e6,
        "abundLoadFile": "my_abundances.dat"
    }
)

Multiple Output Files#

# Generate multiple output files
cloud = uclchem.model.Cloud(
    param_dict={
        "initialDens": 1e4,
        "outputFile": "full_output.dat",      # All species, all timesteps
        "columnFile": "selected_species.dat",  # Just out_species
        "ratesFile": "reaction_rates.dat",     # Reaction rates
    },
    out_species=["CO", "H2O", "CH3OH"]
)