Content:
========

This directory contains a routine (written in MATLAB) for pre-processing
the spectral solar irradiance (ssi) data that has been recommended for use
in the Coupled Model Intercomparison Project (CMIP6; download from
http://solarisheppa.geomar.de/solarisheppa/cmip6) according to the spectral
resolution of the user's (chemistry) climate model.

The directory contains four files:
1. README:                      this file
2. CMIP6_SSI_integration_run.m: MATLAB run script finally to be executed
                                in order to start the pre-processing
3. example_spectral_bands.dat:  Textfile containing example definitions
                                of spectral bands used by your model
4. regrid_ssi.m:                MATLAB function used for integration
                                (usually not to be edited)


Motivation of this package:
===========================

CMIP6 recommended ssi data (download as netcdf-files from
http://solarisheppa.geomar.de/solarisheppa/cmip6) is provided in high
spectral resolution (1nm for 10-750nm range, 5nm for 750-5,000nm,
10nm for 5,000-10,000nm, 50nm for 10,000-100,000nm) as mean
irradiance over each bin.
Many (chemistry) climate models require integrated irradiances
for each spectral band, while the resolution of their radiation
(and/or photolysis) schemes is typically much lower.
This package provides an (hopefully) easy to use routine to
convert from one to another.
Given one of the available original input files (netcdf) downloaded
from http://solarisheppa.geomar.de/solarisheppa/cmip6, this routine
creates a new netcdf-file containing the integrated ssi for all
spectral bands (and all timesteps found in the input file) defined
by the user plus the fraction of these bands' irradiance (ssi_frac)
compared to the total solar irradiance (tsi). As a matter of
completeness, tsi is also written to the newly created file, though
of course only copied from the original file.


Requirements:
=============

Yes, this package is built with MATLAB. You may not like that, but
it is as it is. If you have no MATLAB installation available, you
have to build (or adapt) your own routine for this purpose.
A Python-based equivalent to this package might be provided at
http://solarisheppa.geomar.de/solarisheppa/cmip6 in the future,
but this is not for certain.

Currently, this package runs out-of-the-box only on unix platforms.
Other platforms require a little more changes than just adapting
paths and filenames. At least the automatic naming of the output
file (lines 53, 54, and 59) must be replaced by an equivalent or
explicitly stating the output filename.

The output file's format is netcdf. If you need another format
you will have to convert the output file, substitute the output part
of CMIP6_SSI_integration_run.m, or use your own routine for
pre-processing ssi data.


Usage of this package:
======================

1. Define your model's resolution in a textfile, strictly following
   this formatting:
   NO HEADER LINES, NO UNITS, NO CHARACTER DELIMITERS!!! Just
   - one line per spectral band
   - each line contains two floating point numbers:
     lower and upper edge of respective spectral band (in nanometers!!!)
     separated by blank space(s) or tabulator(s)
   See example_spectral_bands.dat as an example.

2. Adapt upper part (first 60 lines) of MATLAB run script
   CMIP6_SSI_integration_run.m by entering your paths and filenames.

3. Run CMIP6_SSI_integration_run.m
   - With a typical MATLAB installation on a unix/linux system this can be
     easily done by entering the following in a terminal (if you are in the
     directory where CMIP6_SSI_integration_run.m can be found):

     matlab -r CMIP6_SSI_integration_run

     Or without GUI (batch mode):

     matlab -nojvm -nodesktop -nodisplay -r CMIP6_SSI_integration_run


Author:
=======

The author of this script package is Tim Kruschke under the following
copyright:

* Copyright (c) 2016 by Tim Kruschke.
* Permission to use, copy, modify, and distribute this package or parts of
* it for any purpose without fee is hereby granted, provided that this
* entire notice is included in all copies of any scripts or software which
* is or includes a copy or modification of this package (or parts of it)
* and in all copies of the supporting documentation for such scripts or
* software.
* THIS PACKAGE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESSED OR IMPLIED
* WARRANTY. IN PARTICULAR, THE AUTHOR MAKES NO REPRESENTATION OR WARRANTY
* OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS
* FITNESS FOR ANY PARTICULAR PURPOSE.
* THE AUTHOR DOES NOT GRANT ANY SUPPORT FOR THIS SCRIPT PACKAGE.

However, constructive criticism and feedback that may help to improve this
package can be sent to Tim Kruschke (tkruschke[at]geomar.de)
