=====================================================
MARCHEMSPEC Matlab Wrapper

Technical notes prepared by David Carlisle of the 
Numerical Algorithms Group.

Version 1.00


Contact: Simon Clegg, s.clegg@uea.ac.uk.
=====================================================

Contents:

1.  Types

2.  Arguments, and Valid Calls

3.  Input Arguments

4.  Output Arguments

5.  Error Handling

6.  Array and String Lengths

7.  Debug Logging

8.  Supplied files

9.  Matlab Help Text

10. Matlab Examples



1. Types
========

Real:
matlab double array


Integer (int32) scalar:
On input int32, int64 or double value, i, is accepted if
i=floor(i) and is in int32 range.
This means you can use (for example) iCalc=2
(all numeric literals are double in Matlab).
On output, integers are always int32

Integer (int32) array:
No casting is performed, an error is raised if the parameter is not an
int32 array, eg [int32(1),2,3,4] (it is sufficient to just cast the first
element, as Matlab ensures all array elements have the same type.)

String scalar:
Single quoted strings 'abc' or (less efficiently) double quoted strings
"abc" are accepted on input. Output is always single quoted strings.
'abc' and "abc" are not the same type in Matlab.


String array:
A cell array of single quoted strings {'aa','bb'}.
A cell array is used as a Matlab standard [] array may not hold
'-strings of different lengths.


Matlab does not have 1D arrays so an array (1,2,3) may be stored as
a=[1,2,3] which is a 1x3 row or a=[1;2;3] which is a 3x1 column,
in either case the array may be indexed using a single index a(2) is 2.
1D arrays may be input in either order, but always output as column vectors.


2. Arguments, and Valid Calls
=============================
A check is made that the first argument is supplied and is a valid iCalc
integer. The input parameters are then checked for types, and the number
of output values are checked.

The valid forms are

[Outputs, NamesOutputs, cSpecies_out, mSpecies_out, ActCoeffs, NamesSpecies,iFail,iUser,User,strUser]
 =
MarChemSpec(1, tC, S, P, mH,               nSpecies,                      nOut, strFilesDirectory, strCovmxDirectory, iUser,User,strUser)
MarChemSpec(2, tC, S, P, mH, mTris,        nSpecies,                      nOut, strFilesDirectory, strCovmxDirectory, iUser,User,strUser)
MarChemSpec(3, tC,    P,            iConc, Species_in,                    nOut, strFilesDirectory, strCovmxDirectory, iUser,User,strUser)
MarChemSpec(4, tC, S, P, mH,               nSpecies,   iFix, ValuesFixed, nOut, strFilesDirectory, strCovmxDirectory, iUser,User,strUser)
MarChemSpec(5, tC,    P,            iConc, Species_in, iFix, ValuesFixed, nOut, strFilesDirectory, strCovmxDirectory, iUser,User,strUser)
MarChemSpec(6, tC, S, P, mH,               nSpecies,   iFix, ValuesFixed, nOut, strFilesDirectory, strCovmxDirectory, iUser,User,strUser)
MarChemSpec(7, tC,    P,            iConc, Species_in, iFix, ValuesFixed, nOut, strFilesDirectory, strCovmxDirectory, iUser,User,strUser)
MarChemSpec(*, tC, S, P, mH, mTris, iConc, Species_in, iFix, ValuesFixed, nOut, strFilesDirectory, strCovmxDirectory, iUser,User,strUser)

iUser,User,strUser are all optional and may be supplied in any order.
If not supplied, iUser=zeros(15,1,'int32'), User=zeros(15,1), strUser=''

Values of iCalc greater than 7 are passed to the underlying library to allow for future extensions
but currently raise an error (iFail code 100)


3. Input Arguments
==================

iCalc, Integer scalar

tC, double scalar

S, double scalar (iCalc = 1,2,4,6)

P, double scalar

mH, double scalar (iCalc = 1,2)

mTris double scalar (iCalc = 2)

iConc, Integer scalar (iCalc = 3,5,7)

nSpecies, Integer scalar (iCalc = 1,2,4,6)

Species_in (3,nSpecies), double array (iCalc = 3,5,7)

iFix, Integer scalar (iCalc > 3)

ValuesFixed (2,2), double array (iCalc > 3)

nOut, Integer scalar

strFilesDirectory, ' or " quoted string

strCovmxDirectory, ' or " quoted string

iUser, optional int32 array (row or column vector)

User, optional double array (row or column vector)

strUser, optional ' or " quoted string


4. Output Arguments
===================

Outputs (nOut,2), double array

NamesOutputs (nOut,1), cell array of ' quoted strings

cSpecies_out (3,nSpecies), double array

mSpecies_out (3,nSpecies), double array

ActCoeffs (3,nSpecies), double array

NamesSpecies (3,nSpecies), cell array of ' quoted strings

iFail, int32 scalar

iUser (:,1), int32 array (size 15 if not supplied on input)

User (:,1), double array (size 15 if not supplied on input)

strUser, ' quoted string (empty if not supplied on input)



5. Error Handling
=================

If parameters are of the wrong type, or out of range (eg nOut negative)
an exception is thrown and the library is not called.

If the engine returns iFail!=0 an Exception or Warning is given.
Currently give Warning if Ifail>100 (which is not used by the library)


Note if an exception is thrown no output parameters are returned so it
can be useful to classify some errors as warnings. These are highlighted
by the Matlab GUI (they are not simply printed as with printf)


6. Array and String Lengths
===========================
Sizes of input arrays and strings are dropped from the interface and
inferred from the supplied parameters. nOut is a required parameter,
nSpecies is required when Species_in is not supplied

The following sizes are set at compile time, but may be changed in
compile options. e.g.
-DNAMESOUTPUTSLEN=20
without changing the source

#define NERRMSG 50
#define ERRMSGLEN 120
#define NAMESOUTPUTSLEN 100
#define NAMESSPECIESLEN 20
#define DEFAULTLIUSER 15
#define DEFAULTLUSER 15

If preferred, the names lengths could be made input parameters, but they
only need to be an upper estimate the actual returned strings are
trimmed to the names output, these values just affect the size of the
buffer passed to the library.


7. Debug Logging
================
Before calling MarChemSpec you may set

MarChemSpecDebug=1

in the Matlab environment. This enables writing of a MarCharSpec.log file 
tracing input and output values from Fortran. (It is used as the input value 
for iFail in the underlying library.)

Setting MarChemSpecDebug=0, or clearing the variable, will disable this logging.


8. Supplied files
=================

Mex (Matlab C)
--------------

MarChemSpec.h
    C declaration of MarChemSpec from the underlying Fortran Library.
    
MarChemSpec_funs.c
MarChemSpec_funs.h
    Source for auxiliary functions, mostly mapping between Fortran and
    Matlab types.

MarChemSpecM.c

    Main source for Matlab wrapper

    Source for the main Matlab interface compile with build-mex.bat which is

    call mex -O  -I. -L.  -lMarChemSpec MarChemSpecM.c MarChemSpec_funs.c  -O
    move MarChemSpecM.mexw64 MarChemSpec.mexw64

    Note the source name changed to MarChemSpecM.c to avoid clashing
    intermediate files MarChemSpec.lib, MarChemSpec.exp from the
    Fortran compilation.
    
MarChemSpec.mexw64
    Windows mex file made by above



9. Matlab Help Text
===================

MarChemSpec.m
    Matlab file not used at run time as the mex is used in preference
    but contains a documentation string used by help MarChemSpec
    in Matlab.



10. Matlab Examples
===================

Below are listed the original files supplied by NAG (*not* included in the  
general distribution to users):

exception_ex1.m
    An erroneous call demonstrating an exception thrown by the wrapper.
    The underlying library is not called.

ifail100_ex1.m
    An erroneous value detected by the underlying library which reports iFail=100
    An exception is thrown by the wrapper with a message supplied by the library.

icalc1_ex1.m
  Example iCalc=1 call, with data as supplied by Simon Clegg

icalc2_ex1.m
  Example iCalc=2 call, with data as supplied by Simon Clegg

icalc3_ex1.m
  Example iCalc=3 call, with data as supplied by Simon Clegg

icalc4_ex1.m
  Example iCalc=4 call, with data as supplied by Simon Clegg

icalc5_ex1.m
  Example iCalc=5 call, with data as supplied by Simon Clegg


Text
====
Matlab-wrapper-technical-note.txt: this file.
