Calculation of Carbonate System (2004-11-09)



ReadMe file for csys3.m

This file contains instructions on how to run the MATLAB file with the user-interface (recommended) and without (for expert users only).  For either mode to work, both the csys3.m and equic.m files must be in the same folder (or directory).



Table of Contents:
---------------------------------------------------------------------

I)	INTERFACE MODE
	1)	Inputting a Small Set of Values
`		i)	Default Values
	2)	Inputting a Large Set of Values
		i)	Location of Input Data File
		ii)	Input File Format
		iii)	Order of Input Data
		iv)	Default values
		v)	Output File Format
		vi)	Order of Output File Data
		vii)	Location of Output Data File

II)	NON-INTERFACE MODE
	1)	Required System Variables
		i)	runUserInterface
		ii)	numOfInputs
		iii)	flag
		iv)	phflag
		v)	k1k2flag	
	2)	Inputting Values
		i)	TC, S, and P
		ii)	ph1, s1, hco31, co31, alk1, dic1, pco21
		
---------------------------------------------------------------------





---------------------------------------------------------------------
I) INTERFACE MODE

This mode allows the user to input values using a text-driven interface (nothing fancy) instead of going into the MATLAB code to edit the values themselves.  This mode is recommended for most users.



1)  Inputting a Small Set of Values *********************************
To run under this mode, answer no to the question 'Will data be retrieved from a file [Y/N]?'.  This will then allow the inputting of values via the user interface.  We recommend this mode for the inputting of five value sets or less since setting up a file for this many value sets would be time-consuming.

i)    Default Values ************************************************
If no value is given for any variable in this mode, the interface will assign a default value.  The following states the default value for each variable:
	Select Values Given 		->	pH and C02 given	[1]
	Select Scale			->	Total scale		[1]
	Select Equilibrium Constants	->	Mehrbach		[2]
	Temperature (Celcius)		->	25
	Salinity			->	35
	Pressure (bar)			->	0
	pH				->	8.2
	CO2 (µmol/kg)			->	10
	HCO3- (µmol/kg)			->	1750
	CO3-- (µmol/kg)			->	250
	ALK (µmol/kg)			->	2400
	DIC (µmol/kg)			->	2000
	pCO2 (µmol/kg)			->	365




2)  Inputting a Large Set of Values *********************************
To run under this mode, answer yes to the question 'Will data be retrieved from a file [Y/N]?'.  This will then allow the inputting of values via a file.  We recommend this mode for the inputting of value sets greater than five since inputting this many value sets via the interface would be time-consuming.

i)    Location of Input Data File ***********************************
The input file must lie in the same directory as the csys.m and equic.m files.

ii)   Input File Format *********************************************
The data contained in the input file must be delimited with tabs, spaces, or commas.  The program can take any file extension as long as the data within the file is delimited correctly and the file extension is included with the file name.

iii)  Order of Input Data *******************************************
The order of columns of data in the input file must correspond to the order of variables as listed in the Select Variables Given section of the interface.  The table below shows in what order the columns must be with respect to the selection made in the Select Variables Given section.
	Select Values Given = 1		->	1st - pH	2nd - CO2
	Select Values Given = 101	->	1st - pH	2nd - pCO2
	Select Values Given = 2		->	1st - CO2	2nd - HCO3
	Select Values Given = 3		->	1st - CO2	2nd - CO3
	Select Values Given = 4		->	1st - CO2	2nd - ALK
	Select Values Given = 5		->	1st - CO2	2nd - DIC
	Select Values Given = 6		->	1st - pH	2nd - HCO3
	Select Values Given = 7		->	1st - pH	2nd - CO3
	Select Values Given = 8		->	1st - pH	2nd - ALK
	Select Values Given = 9		->	1st - pH	2nd - DIC
	Select Values Given = 10	->	1st - HCO3	2nd - CO3
	Select Values Given = 11	->	1st - HCO3	2nd - ALK
	Select Values Given = 12	->	1st - HCO3	2nd - DIC
	Select Values Given = 13	->	1st - CO3	2nd - ALK
	Select Values Given = 14	->	1st - CO3	2nd - DIC
	Select Values Given = 15	->	1st - ALK	2nd - DIC

iv)   Default Values ************************************************
Under this mode, there are no default values for pH, CO2, HCO3-, CO3--, DIC, ALK, pCO2, Input Filename, and Output Filename.  If any of these are void of values, then the program will either not run or show an error message.  For all other values, the defaults are:
	Select Values Given 		->	pH and C02 given	[1]
	Select Scale			->	Total scale		[1]
	Select Equilibrium Constants	->	Mehrbach		[2]
	Temperature (Celcius)		->	25
	Salinity			->	35
	Pressure (bar)			->	0
	Delimiter Used			->	Comma			[1]

v)    Output File Format ********************************************
The delimiters used for this output file will be the same used in the input file.  The output file can have any name and any file extension; however it may not be properly formatted for that file extension.  For example, if an output file name has the extension '.xls', it will not be in Excel format and problems will occur in reading it.

vi)   Order of Output File Data *************************************
The columns for the results in the output file will be in the following order:  CO2, HCO3-, CO3--, DIC, ALK, pCO2, pH Total, pH Free.

vii)  Location of Output Data File **********************************
The output file will be created in the same directory as the csys.m and equic.m files.
------------------------------------------------------------------





------------------------------------------------------------------
I) NON-INTERFACE MODE
This mode involves going into the MATLAB file and manipulating the values of certain variables within the file.  It is important to manipulate only the values and not the names of these variables.  The system will not work correctly otherwise.




1)  Required System Variables
Besides the variables needed for calculating, certain system variables need values in order to run under this mode correctly.

i)	runUserInterface ********************************************
This variable, located on line 47, must be set to zero (0) in order for the program to run under the non-interface mode.

ii)	numOfInputs *************************************************
This value, located on line 76, must be set to the number of inputs that will be calculated.

iii)	flag ********************************************************
This value, located on line 77, indicates what variables the program will calculate.  A key is offered in lines 51-73.

iv)	phflag ******************************************************
This value, located on line 78, indicates what pH scale to use.  Zero (0) will display a total scale and one (1) will display a free scale.  Any other value will be unrecognized.

v)	k1k2flag ****************************************************
This value, located on line 79, indicates which equilibrium constant to use.  Zero (0) will use Roy et al. (1993) and one (1) will use Mehrbach et al (1973) as refit by Lueker et al. (2000) on total scale.  Any other value will be unrecognized.




2)  Inputting Values
These are the values that will be used for computation and can be found on lines 80-89.  Only the variables that will be calculated based on the value of the "flag" variable need to be changed.  All of the other variables on lines 80-89 will be ignored.

i)    TC, S, and P **************************************************
The TC (temperature in Celcius), S (salinity), and P (pressure in bar) can only accept one value regardless of the amount of data sets being inputted for calculation.

ii)   ph1, s1, hco31, co31, alk1, dic1, pco21 ***********************
The ph1 (pH), s1 (C02), hco31 (HCO3-), co31 (CO3--), alk1 (ALK), dic1 (DIC), and pc021 (pCO2) can accept multiple values.  The delimiter for these values are commas and the values must lie within brackets ([ ])