% This file is part of KAFGA (KAppa Functional Group Analysis).
% Copyright (C) 2015 Markus D. Petters
%
% KAFGA is supplementary code to the following manuscript
% Petters, M. D., Kreidenweis, S. M., Ziemann, P. J.
% Prediction of cloud condensation nuclei activity for organic
% compounds using functional group contribution methods 
% Geoscientific Model Development, Manuscript number gmd-2015-172 
%
% KAFGA is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.

% KAFGA is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.

% You should have received a copy of the GNU General Public License
% along with KAFGA.  If not, see <http://www.gnu.org/licenses/>.
%

MATLAB source scripts are in src/
Model calculations graphed in Figs. 1-3 and Fig.1 supplement in
gmd-2015-172 are demonstrated in the example folders.

The most straightforward example is fs01:
Model input files
 - each compound is represented by a model input file in folder fs01comp
 - an input file consists of 4 columns and 9 rows
 - rows and columns correspond to main and subgroups, respectively
 - Specifically:

               Sub1        Sub2        Sub3        Sub4	
   Alkane      CH3	   CH2	       CH          C	
   Alcohol     OH	   ---	       ---         ---	
   Water       H2O	   ---	       ---         ---	
   Carbonyl    CH3C(=O)    CH2(C=O)    ---         ---	
   Aldehyde    H(C=O)	   ---	       ---         ---	
   Ether       CH3(O)	   CH2(O)      CH(O)       THF	
   Acid        C(=O)OH	   HC(=O)OH    ---	   ---	
   Nitrate     CH2(ONO2)   CH(ONO2)    C(ONO2)	   ---	
   Peroxide    CH2(OOH)    CH(OOH)     C(OOH)	   ---	

 - Example input file for ethanol CH3-CH2OH 
               1	   1	       0	    0	
               1           0	       0            0	
               0           0           0            0	
               0           0           0            0	
               0           0           0            0	
               0           0           0            0	
               0           0           0            0	
               0           0           0            0	
               0           0           0            0	
 - Input files for all compounds in gmd-2015-072 are provided in examples

 - A component input structure is needed. These are generated in the
   script, for example, fs01_compounds.m. The fields are: 'name':
   compound name, 'file': name of input text file (see above), 'sol'
   observed solubility', MS_obs: observed molecular weight, rho_obs:
   observed density, Cx, Hx, Ox, Nx: # of C, H, N, O atoms, D:
   diameter for which CCN activity is computed. Note that observed
   quantities are not needed for the model. To see an example for
   initialization/generation of model compounds without observations
   see the structure returned for f03_compounds().

Model execution and output.
 - For example model execution see file fs01.m
 - Multiple files can be present in the input directory
 - The output directory must exist. It is possible to combine them
   into a single directory
 - A file with interaction coefficients anm, located in src/txt can be
   specified at runtime. Current options are anm_standard and
   anm_revised. anm standard corresponds to standard UNIFAC,
   anm_revised to the coefficients used in gmd-2015-172
 - To execute now compounds, create a copy of for example f03 and
   rename it. If the copy is not in the example folder, the sourcepath
   needs to be changed in the execution file, as well as the src files
   main.m, load_coefficients.m and unifac.m
 - A summary output file is written. The file is appended each time
   the model runs. The file lists: filenamame (compound), # of C, # of H,
   # of O, # of N, molecular weight, predicted molar volume, flory
   huggins kappa, Raoult k, UNIFAC kappa (reported in the paper), water
   activity of saturated solution, molefraction of xw of phase bounary
   1,molefraction of xw of phase bounary 2.
 - The complete output is also saved as a .mat file for quick loading
 - An ASCII file (.out) is written that contains xw, xs, gamma_w, gamma_s
 - Example f02 contains an initialization script for serial and
   parallel execution. Parallel execution is not supported in
   Octave. Serial execution for f02 produces the same result in octave
   and matlab. Postprocessing in fs01 is not supported in
   Octave. 
