Ginput: GGG meteorology and a priori VMR preprocessor

Copyright notice

Copyright (c) 2022, by the California Institute of Technology. ALL RIGHTS RESERVED. United States Government Sponsorship acknowledged. Any commercial use must be negotiated with the Office of Technology Transfer at the California Institute of Technology.

This software may be subject to U.S. export control laws. By accepting this software, the user agrees to comply with all applicable U.S. export laws and regulations. User has the responsibility to obtain export licenses, or other export authority as may be required before exporting such information to foreign countries or providing access to foreign persons.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of Caltech nor its operating division, the Jet Propulsion Laboratory, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Quickstart

• Make sure you have a Python installation with the conda package manager on your system. We currently recommend miniforge.
• Run make install
• Run ./run_ginput.py --help to see available subcommands
• For more detailed help, try man ginput after running make install. (If that doesn't work, try man man/build/man/ginput.1 from this directory or add man/build/man/ to your MANPATH).

For more install options, run make help.

Is it working correctly?

To check whether your installation is working, there are example .mod, .vmr, .map, and .map.nc files in ginput/testing/test_input_data that have been generated from both GEOS-FPIT and GEOS-FP. While TCCON uses GEOS-FPIT, it requires a data subscription, so you may prefer to use GEOS-FP.

To verify you have installed and are using ginput correctly, we recommend you generate at least the .mod and .vmr files for Lamont (site code "oc") on 1 Jan 2018 and compare against the pregenerated test files. Differences should be less than ~1%.

If you have GEOS FP-IT files available on your system, the script ginput/testing/test_input_data/geosfp-it/link_geos_fpit_files.sh will help link them to the correct location in this repo to run the automatic test case. cd to ginput/testing/test_input_data/geosfp-it/ and run ./link_geos_fpit_files.sh --help to see its usage. This requires the following files:

• The 8 model level assimilated quantity files for 2018-01-01 (GEOS.fpit.asm.inst3_3d_asm_Nv.GEOS5124.20180101*.nc4)
• The 8 2D assimilated quantity files for 2018-01-01 (GEOS.fpit.asm.inst3_2d_asm_Nx.GEOS5124.20180101*.nc4)
• The 8 model level chemistry files for 2018-01-01 (GEOS.fpit.asm.inst3_3d_chm_Nv.GEOS5124.20180101*.nc4)

To run the test, the easiest way is to activate the conda environment that ginput was installed in (ginput-auto-default if installed with make install) and run make test. This will take several minutes to run. If tests fail because the output .mod/.vmr/.map files do not match the expected, plots will be generated in ginput/testing/plots for you to inspect the differences and verify that they are reasonable.

Documentation

Man pages are created in man/build/man/ during installation and can be accessed with e.g. man man/build/man/ginput.1. These may also be added to your MANPATH so that e.g. man ginput works, but this is system dependent. Full documentation is provided at https://ginput.readthedocs.io/en/latest/.

Some additional documentation is provided on the TCCON wiki:

• Running ginput
• Code structure

These will be folded into the readthedocs instance in the future.

Terms of use

Ginput is licensed under the Apache license as of 8 Sept 2022. Prior to this date, it was licensed under the LGPL license. If you download this software after 8 Sept 2022, you agree to abide by the terms of the Apache license. The full legal terms are contained in LICENSE.txt file. For a short summary, please see here. If you have any questions about use, please contact us (contact information is below).

In addition to the Apache license, you should cite the ginput paper listed in the CITATION.cff file in any publications resulting from the use of ginput. Please also consider contacting us to let us know you are using ginput!

Python support

Only Python 3 is supported. Python 2 reached end-of-life on 1 Jan 2020. We also use the conda package manager in the install script, which is provided by, e.g. miniforge.

Contact

For assistance with ginput, contact Josh Laughner.