calpy -- CALPUFF model managing module in Python

Introduction

CALPUFF is an advanced non-steady-state meteorological and air quality modeling system. Since its parameter file INP file (suffixed with ".inp") is old, ill-designed and hard-to-use, this python module provides functions to manage the INP file of CALPUFF model. This module needs python >= 3.6.

Usage

Clone this repository as your project directory. To run the example, run:

$ python3 example.py

Before running the program, you need to place your calpuff.exe into the exe/ directory and all related data to the data/ directory. To try the example, put your calmet.dat into the data/winter/ directory which is generated by CALMET model.

Explanation

The main idea is to use a class called InpGroup to operate the parameters by its methods. In the example below you will see operations like setting directory path, setting species information, setting source information and so on. In fact these operations just save the information into the data structure contained in the InpGroup class. When you call calpy.run_calpuff() function, it will output all the parameters to a file called calpuff.inp and run the calpuff.exe in the exe/ directory.

The information (i.e., data) should be stored in the csv files in data/ directory. As long as you set them right, calpy will do the things left, e.g., setting number of species and sources. If you need to do multiple tasks, you can create a sub-directory in data/ just like the example, where it uses a data/winter/ directory to place all the data files and set this prefix by InpGroup.set_data_dir("data/winter/"). See code below for details.

Limitation

The module is too simple for practical purposes. So you may need to understand this module before using it. It only support Lambert projection and use a base calpuff_template.inp file in the utils/ directory to set default parameters value. So you may need to alter to your own calpuff_template.inp file.

If you want to manage other preprocessors INP files, you may need to implement them yourself. Since CALPUFF model's INP file is the most complicated one, other INP files management is easy.

Summary

The project directory should be like:

.
├── calpy.py
├── clean.py
├── data
│   └── winter
│       ├── area_source.csv
│       ├── calmet.dat
│       ├── receptors_info.csv
│       ├── samples.csv
│       ├── source_emission.csv
│       ├── source_info.csv
│       ├── species_decay.csv
│       └── species_options.csv
├── exe
│   └── calpuff.exe
├── images
├── output
│   └── winter
├── utils
│   └── calpuff_template.inp
└── yourCode.py

Example

import calpy

params = {
    # CALMET file
    "metFile": "calmet.dat",
    # time -- Input Group 1
    "startYear": 2019, "startMonth":  1, "startDay":  23, "startHour":  0,
    "endYear":   2019, "endMonth":    1, "endDay":    23, "endHour":   12,
    "timeZone": "UTC+0000",
    "timeStep": 3600,  # no larger than 3600
    # lambert projection -- Input Grroup 4
    "lambertlat1": "25N",
    "lambertlat2": "40N",
    "centerLat0": "31N",
    "centerLon0": "120E",
    # grids -- Input Grroup 4
    "nx": 60, "ny": 60, "nz": 11, "cellsize": 1,
    "zface": [0, 20, 40, 80, 160, 320, 640,
		      1000, 1500, 2000, 2500, 3000],  # length should be `nz`+1
    "xorigin": -30, "yorigin": -30
}
group = calpy.load_calpuff()
group.set_data_dir("data/winter")
group.set_output_dir("output/winter")
group.set_exe_dir("exe/")
group.set_params(params)
group.load_species_options(unit="ug/m**3")
print("species:\n", group.speciesList)
group.load_species_decay()
# print("decay:\n", group.speciesDecay)
group.load_source_info()
# print("source:\n", group.sourceInfo)
group.load_source_emission(unit="g/s")
# print("emissn:\n", group.sourceEmiss)
group.load_receptors_info()
# print("receptors:\n", group.receptors)
#group.load_area_source()

calpy.run_calpuff(group, disp=True)  # run CALPUFF

times, samples = calpy.load_samples(group, timeZone="UTC+0800", filename="samples.csv")
timeseries = calpy.extract_receptors(group)
simulates = timeseries.get_simulates(times)  # get simulated concentrations of each receptors

# do something

This will load all the information set in data/winter/ and run the model. All the output of CALPUFF model will be put into output/winter/ directory.

There are example csv files in this repository. The first columns of source_info.csv and species_options.csv are "%process" which indicate whether to add the source or species into the INP file, 1 for yes and 0 for no.

Area source's csv file is too simple and crude for I didn't have time to re-design it. You may want to rewrite this part on your own.

clean.py is used to clean the annoying files created by CALPUFF.