Metadata-Version: 2.1
Name: gatiab
Version: 1.0.2
Summary: Gasous Absorption Transmissions at Instrument Averaged Bands
Author-email: Mustapha Moulana <mm@hygeos.com>
License: 
        # GATIAB SOFTWARE
        # TERMS OF USE
        
        
        *version 1.0, Last modified: October 17, 2024*
        
        
        **Quick Summary**
        The GATIAB software can be used for free for non-commercial purposes. If you
        want to use the software for commercial purposes, please contact us.
        
        -----
        
        
        The GATIAB SOFTWARE is a service made available by HYGEOS, a company organised
        and existing under the laws of France with an issued share capital of 84 850,- €
        with its registered office at 165 Avenue de Bretagne – Parc Euratechnologies
        – 59000 LILLE (France), registered at Lille Métropole under number 439 051 472,
        hereinafter referred to as “Hygeos” By using the GATIAB SOFTWARE, you are
        agreeing these Terms of Use.  Hygeos agrees to grant a license to the User on
        the Software and the User undertake to comply with these Terms of Use.  Before
        accepting These Terms of Use, the User made sure that:
        * The Software fits with its needs and expectations,
        * its information system has the necessary and sufficient technical
        specifications and requirements for the installation and the operation of the
        Software.
        
        The User is informed and accepts that Hygeos can amend or modify these Terms of
        Use at any moment. Any amendment or modification to these Terms of Use will be
        made available on https://github.com/hygeos/gatiab. The User undertakes to
        check regularly the last modified version Terms of Use in force made available
        on the HYGEOS git GATIAB repository at https://github.com/hygeos/gatiab 
        and recognizes and accepts to be bound by it.
        
        ## SECTION 1. DEFINITIONS
        “Terms of Use” shall mean the present document, and all modifications and
        additions to these documents made available to the User by publishing on
        https://github.com/hygeos/gatiab.
        
        “Effective Date” shall mean the date on which these Terms of Use enter in force
        between the User and Hygeos as defined in Section 4.
        
        “Contact Email” shall mean the email addresses identified in Section 17 by
        which notifications between the User and Hygeos can be done.
        
        “Software” shall mean the GATIAB SOFTWARE both in object code or source code
        format, including accompanying documentation, and any upgrades, enhancements
        and corrections made available on https://github.com/hygeos/gatiab
        or made by the User. The Software allows generating Gaseous Transmissions
        products from CKDMIP look-up tables and instrument relative spectral response.
        
        “Territory” shall mean geographic areas where these Terms of Use applies and
        identified in Section 3, which may be amended in writing upon mutual agreement
        of the Parties to include additional geographic areas.
        
        “User” shall mean the user of the Software who has accepted these Terms of Use.
        
        ## SECTION 2. RIGHT OF USE
        Subject to the terms and conditions of these Terms of Use, Hygeos grants to the
        User a personal, non-exclusive, non-transferable license to use the Software
        for the exclusive purpose of scientific research excluding any commercial
        purpose (hereinafter, the “Non-Commercial Purpose”).  The User may use the
        Software in its source code format for its own use, and may translate or modify
        the Software or incorporate them into other software. The User may not,
        however, transfer or sublicense the Software to any third party, in whole or in
        part, in any form, whether modified or unmodified. 
        
        ## SECTION 3. TERRITORY
        The right of use of the Software described in Section 2 above shall be granted
        for the country where the User is established.
        
        ## SECTION 4. TERM
        These Terms of Use shall enter in force upon the User has accepted these Terms
        of Use (the “Effective Date”). It shall be ended at any moment by one Party by
        notification through the Contact Email.
        
        ## SECTION 5. DELIVERY OF THE SOFTWARE 
        Hygeos will make available to the User the Software both in its source code
        form the Effective Date and no later than five (5) days after the Effective
        Date. The delivery shall be done by electronic means.
        
        Hygeos authorizes the User to use or modify the source code of the Software
        solely for the purpose to ensure the interoperability of the Software with its
        information system or to enhance the Software or for scientific research. The
        User shall notify Hygeos of each modification done by it to the source code of
        the Software.
        
        ## SECTION 6. COPIES 
        User may make copies of the Software both form as necessary for use by the User
        and for backup or archive purposes. The User agrees to maintain records of the
        location and use of each copy, in whole or in part, of the Software. Each copy
        of the Software is copyrighted by Hygeos. The User agrees to reproduce and
        apply the copyright notice and proprietary notice of Hygeos to all copies made
        hereunder, in whole or in part and in any form, of Software. 
        
        ## SECTION 7. SUPPORT AND MAINTENANCE 
        Hygeos will provide support and maintenance services according to this
        Section 7.  Hygeos will provide adequate online support for the first installation of
        the Software. Hygeos will also provide the following support and maintenance
        services:
        (i) If the User notifies Hygeos of a substantial program error
        respecting the Software, or Hygeos has reason to believe that error exists in
        the Software and so notifies the User, Hygeos shall at its own expense verify
        and attempt to correct such error within thirty (30) days after the date of
        notification. If the User is not satisfied with the correction, then the User
        may terminate these Terms of Use, without any indemnification to the User.
        (ii) In the case that the User has technical questions in the use of the
        Software, the User may submit those questions to Hygeos.
        
        ## SECTION 8. PRICES AND PAYMENTS
        These Terms of Use are subscribed for Non-Commercial Purpose as stated in
        Section 2, and the use of the Software to this end is granted free of charge.
        
        ## SECTION 9. OWNERSHIP 
        The original and any copies of the Software, made by the User, including
        translations, compilations, partial copies, modifications, and updates, are the
        exclusive property of Hygeos. 
        
        ## SECTION 10. PROPRIETARY RIGHTS 
        The User recognizes that Hygeos regards the Software as its proprietary
        information and as confidential trade secrets of great value. The User agrees
        not to provide or to otherwise make available in any form the Software, or any
        portion thereof, to any person other than employees of the User without the
        prior written consent of Hygeos.
        The User shall not disclose or copy to a third party the Software or any part
        thereof.
        The User further agrees to treat the Software with at least the same degree of
        care with which the User treats its own confidential information and in no
        event with less care than is reasonably required to protect the confidentiality
        of the Software. 
        
        ## SECTION 11. DATA
        The User is responsible of all data processed through the Software. Hygeos
        shall not assume any responsibility toward:
        * the ownership and rights on any data processed through the Software, and
        * the fitness, the accuracy, the quality, the completeness of any data
        processed through the Software.
        
        The User ensures that it has sufficient rights to use and process the data. The
        User warrants Hygeos against any claim from any third party regarding the data
        it processed through the Software, including but not limited to ownership,
        infringement, unfair competition. 
        
        ## SECTION 12. TERMINATION 
        Hygeos may terminate these Terms of Use if User is in default of any of the
        terms and conditions of these Terms of Use and fails to correct such default
        within ten (10) days after written notice thereof from Hygeos. 
        
        ## SECTION 13. TERMINATION CERTIFICATE 
        In the event of termination for whatever reason, the User shall:
        * immediately stop use of the Software,
        * provide on demand to Hygeos, within one (1) month, a certificate certifying
        that the original and all copies of the Software, in whole or in part and in
        any form, have been destroyed.
        
        After termination of these Terms of Use for whatever reason, provisions of
        Sections 9, 10, 11, 15 to 17, and 19 hereof shall survive. 
        
        ## SECTION 14. WARRANTY DISCLAIMER 
        The User acknowledges and accepts, the Software "AS IS." HYGEOS PROVIDES NO
        WARRANTIES AS TO THE FUNCTION OR USE OF THE SOFTWARE, WHETHER EXPRESS, IMPLIED,
        OR STATUTORY, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF
        MERCHANTABILITY OR FITNESS FOR PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
        QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH THE USER. HYGEOS DOES NOT
        WARRANT THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET USER’S
        REQUIREMENTS OR THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR
        ERROR FREE. 
        
        ## SECTION 15. PATENT AND COPYRIGHT INDEMNITY 
        Hygeos will defend at its own expense any action brought against the User to
        the extent it is based on a claim that the Software used within the scope of
        the right of use granted hereunder infringe a patent, copyright or other
        proprietary right of a third party. Hygeos will pay any costs, damages or
        attorney fees finally awarded against the User in such action which are
        attributable to such claim, provided Hygeos is promptly notified in writing of
        such claim, may control the defense and/or settlement of such claim, and is
        provided with all requested assistance, information and authority.
        
        In the event that the Software becomes, or in Hygeos’ opinion is likely to become, the
        subject of a claim of infringement of a patent, copyright or trade secret,
        Hygeos may at its option either secure the User’s right to continue using the
        Software, replace or modify the Software to make them not infringing. Hygeos
        shall have no liability for any claim of patent, copyright or trade secret
        infringement based on the use of the Software in any form other than the
        original, unmodified form provided to the User or the use of a combination of
        the Software with hardware, software or data not agreed by Hygeos where the
        used Software alone in their original, unmodified form would not constitute an
        infringement. The foregoing states the User's entire liability for infringement
        or claims of infringement of patents, copyrights or other intellectual property
        right. 
        
        ## SECTION 16. LIMITATION OF LIABILITY 
        HYGEOS’ ANNUAL LIABILITY TO USER UNDER ANY PROVISIONS OF THIS AGREEMENT FOR
        DAMAGES FINALLY AWARDED SHALL BE LIMITED TO THE AMOUNTS PAID IN THE YEAR
        CONCERNED BY THE USER TO HYGEOS. IN NO EVENT SHALL HYGEOS BE LIABLE FOR
        INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOSS OF USE,
        LOSS OF DATA AND LOSS OF PROFITS OR INTERRUPTION OF BUSINESS, HOWEVER CAUSED OR
        ON ANY THEORY OF LIABILITY. 
        
        ## SECTION 17. NOTICES 
        All notices in connection with this Agreement shall be in writing and may be
        given by registered mail or personally delivered at the address set forth on
        the front page. Notices by email shall be deemed effective if sent to the
        Hygeos’ and User’s Contact Email. 
        
        ## SECTION 18. SEVERABILITY 
        In the event any provision of these Terms of Use is determined to be invalid or
        unenforceable, the remainder of these Terms of Use shall remain in force as if
        such provision were not a part. 
        
        ## SECTION 19. GOVERNING LAW
        These Terms of Use shall be governed and interpreted by the laws of FRANCE and
        Lille shall be the appropriate venue and jurisdiction for the resolution of any
        disputes hereunder. Both Parties hereby consent to such personal and exclusive
        jurisdiction. 
        
        ## SECTION 20. NON-ASSIGNMENT 
        These Terms of Use and the right of use granted by it may not be assigned,
        sublicensed, or otherwise transferred by the User without the prior written
        consent of Hygeos.
        
        
        
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: Free for non-commercial use
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9.19
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.26.4
Requires-Dist: xarray>=2024.7.0
Requires-Dist: netcdf4>=1.7.1
Requires-Dist: scipy>=1.13.1
Requires-Dist: tqdm>=4.66.5

# GATIAB
GATIAB (Gasous Absorption Transmissions at Instrument Averaged Bands). \
This module provides gaseous transmissions base on CKDMIP idealized Look-Up tables and sensor spectral response functions.

Mustapha Moulana  
[HYGEOS](www.hygeos.com)

-----------------------------------------


## CKDMIP data
The CKDMIP (the Correlated K-Distribution Model Intercomparison Project) Idealized Look-Up tables are necessary to use the gatiab module. See: Hogan et al. ->  https://gmd.copernicus.org/articles/13/6501/2020/

The CKDMIP documentation and data are available here: https://confluence.ecmwf.int/display/CKDMIP

## AFGL atmophere LUTs
The gatiab module needs afgl atmosphere profils. Those atmophere look-up tables can be dowloaded from SMART-G (Speed-up Monte Carlo Advanced Radiative Transfer Code using GPU) -> https://github.com/hygeos/smartg

The SMART-G makefile can be used:
```
$ make auxdata_atm
```

## Installation
The module can be installed using the following command:
```
$ pip install git+https://github.com/hygeos/gatiab.git
```

## Testing
Example of pytest.ini file:
```
[pytest]
addopts=
    --dir-ckdmip="/path/to/ckdmip/dir/"
    --dir-atm="path/to/atm/dir/"
    -s -v
```
Run the command `pytest tests/` to check that everything is running correctly.

## Exemples
```
from gatiab import ckdmip2od, Gatiab
import xarray as xr
import glob

# Specify the ckdmip and atmophere directory paths
dir_ckdmip = "path/to/ckdmip/dir/" 
dir_atm = "path/to/atm/dir/"

# First create optical depth LUTs of a given atmosphere
# wavenumber units -> cm-1
ds = ckdmip2od(gas='O3', dir_ckdmip=dir_ckdmip, dir_atm=dir_atm, atm='afglus',
               wvn_min = 4000., wvn_max=26000., save=True)

# Second we need the instrument spectral response
# Here we use the LUTs we have created for testing of Sentinel 3A OLCI
# Other SRF intruments -> https://nwp-saf.eumetsat.int/site/software/rttov/download/coefficients/spectral-response-functions/
rsrf_files = sorted(glob.glob("./tests/S3A_OLCI_rsrf/*.nc"))
nbands = len(rsrf_files)
rsrf = [] # iband list with relative spectral response as function of wavelength
srf_wvl = [] # iband list with wavelength in nanometer
for i in range (0, nbands):
    with xr.open_dataset(rsrf_files[i]) as ds:
        rsrf.append(ds['rsrf'].values)
        srf_wvl.append(ds['wvl'].values)

# Third compute the gas transmission as function of gas content, airmass, ground pressure and wavelength
gt = Gatiab(ds)
gt.print_gas_content() # print the standard afgl total column content of O3

gas_content = np.array([250., 300., 350.]) # in DU
air_mass = np.array([3., 4., 5.])
p0 = gt.od['P_hl'][-2:].data*1e-2 # ground pressure in hectopascal
ds_gt = gt.calc(gas_content, air_mass, p0, srf_wvl_r, rsrf_r)
print(ds_gt)
```
