Calculation of Carbonate System (09/2004, 04/2014)







ReadMe file for csysUI.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 csysUI.m and equic.m files must be 
in the same folder/directory.







Table of Contents:

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



I)	INTERFACE MODE

	1)	Input a Small Set of Values

`		i)	Default Values

	2)	Input 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)	ocdflag
		v)	phflag
		vi)	k1k2flag	

	2)	Input 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)  Input a Small Set of Values *********************************

To run under this mode, answer NO ('n') to the question 'Will data be 
retrieved from a file [Y/N]?'.  This will then allow the input of values 
via the user interface.  We recommend this mode for the input of about 
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 CO2 given	[1]

	Select CO2SYS comparison	->	No			[0]

	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)  Input a Large Set of Values *********************************

To run under this mode, answer YES ('y') to the question 'Will data be 
retrieved from a file [Y/N]?'.  This will then allow the input of values 
via a file.  We recommend this mode for the input of value sets greater than 
about five since input 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 CO2 given	[1]
	Select CO2SYS comparison	->	No			[0]
	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, the user may specify an
output file name with extension '.xls', but the file will not be in Excel format 
and problems may occur when reading it with Excel.



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 csysUI.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 must be set to zero (0) in order for the program to run 
under the non-interface mode.



ii)	numOfInputs *************************************************

This value must be set to the number of inputs that will be calculated.



iii)	flag ********************************************************

This value indicates what variables the program will calculate.


iv)	ocdflag *****************************************************

This value indicates if output will be calculated for comparison with
CO2SYS (V1.1 Matlab 09/2011). Requires phflag = 0 and k1k2flag = 1.



v)	phflag ******************************************************

This value indicates what pH scale to use.  Zero (0) will display pH on 
total scale and one (1) will display pH on free scale. Any other value will 
be unrecognized.



vi)	k1k2flag ****************************************************

This value 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)  Input Values

These are the values that will be used for computation.  
Only the variables that will be calculated based on the value 
of the "flag" variable need to be changed.  All other variables 
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 input 
for calculation.



ii)   ph1, s1, hco31, co31, alk1, dic1, pco21 ***********************

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