# gsw_stabilise_SA_CT

    minimally adjusts both Absolute Salinity and Conservative
    Temperature to produce a stable water column
    (75-term equation)

## Contents

- USAGE:
- DESCRIPTION:
- INPUT:
- OUTPUT:
- EXAMPLE:
- AUTHOR:
- VERSION NUMBER:
- REFERENCES:

## USAGE:

    [SA_out, CT_out] = gsw_stabilise_SA_CT(SA_in,CT_in,p,{opt_1,opt_2})

## DESCRIPTION:

    This function stabilises a water column, this is achieved by minimally
    adjusting both the Absolute Salinity SA and Conservative Temperature CT
    values such that the minimum stability is adjusted to be atleast
    1/5th of the square of earth's rotation rate.

    When running versions of Matlab earlier than 2016b, this programme
    requires either Tomlab CPLEX or IBM CPLEX or the Optimization toolbox.
    For newer versions of Matlab, including 2016b, it requires either Tomlab
    CPLEX or IBM CPLEX. Note that if there are a up to several hundred bottles
    in the cast then Matlab's Optimization toolbox produces reasonable results,
    but if there are thousands of bottles in the cast or the best possible
    output is wanted then the CPLEX solver is required.  This programme will
    determine if a slover is available to the user, if there is more than one
    it will use first in the following order Tomlab, IBM, then Matlab.

    Note that the 75-term equation has been fitted in a restricted range of
    parameter space, and is most accurate inside the "oceanographic funnel"
    described in McDougall et al. (2003).  The GSW library function
    "gsw_infunnel(SA,CT,p)" is avaialble to be used if one wants to test if
    some of one's data lies outside this "funnel".

    Click for a more detailed description of adjusting salinities
    to produce a stablised water column

## INPUT:

    SA_in  =  uncorrected Absolute Salinity                         [ g kg-1 ]
    CT_in  =  uncorrected Conservative Temperature (ITS-90)          [ deg C ]
    p      =  sea pressure                                            [ dbar ]
           (ie. absolute pressure - 10.1325 dbar)

    OPTIONAL:
    opt_1 = Nsquared_lowerlimit                                        [ s-2 ]
    Note. If Nsquared_lowerlimit is not supplied, a default minimum
    stability of 1 x 10^-9 s^-2 will be applied.
    or,
    opt_1 =  longitude in decimal degrees                       [ 0 ... +360 ]
                                                         or  [ -180 ... +180 ]
    opt_2 =  latitude in decimal degrees north                 [ -90 ... +90 ]

    SA & t need to have the same dimensions.
    p may have dimensions 1x1 or Mx1 or 1xN or MxN, where SA & CT_in are MxN.
    opt_1 equal to Nsquared_lowerlimit, if provided, may have dimensions 1x1
    or (M-1)x1 or 1xN or (M-1)xN, where SA_in & CT_in are MxN.
    opt_1 equal to long & opt_2 equal to lat, if provided, may have
    Sdimensions 1x1 or (M-1)x1 or 1xN or (M-1)xN, where SA_in & CT_in are MxN.

## OUTPUT:

    SA_out =  corrected stabilised Absolute Salinity               [ g kg-1 ]
    CT_out =  corrected Conservative Temperature (ITS-90)           [ deg C ]

## EXAMPLES Note that the availibilty of the licence will choose which solver is used, it is not controllable by the calling command line.

## EXAMPLE 1 (using Tomlab CPLEX):

    SA = [34.7118; 34.8915; 35.0256; 31.0472; 34.7366; 34.7324;]
    CT = [28.7856; 28.4329; 22.8103; 10.2600;  6.8863;  4.4036;]
    p =  [     10;      50;     125;     250;     600;    1000;]

    [SA_out, CT_out] = gsw_stabilise_SA_CT(SA,CT,p)

    SA_out =

       34.7118
       34.8915
       34.6116
       31.4612
       34.7366
       34.7324

    CT_out =

       28.7856
       28.4329
       24.7758
        7.9461
        6.8863
        4.4036

## EXAMPLE 2 (using IBM CPLEX):

    SA = [34.7118; 34.8915; 35.0256; 31.0472; 34.7366; 34.7324;]
    CT = [28.7856; 28.4329; 22.8103; 10.2600;  6.8863;  4.4036;]
    p =  [     10;      50;     125;     250;     600;    1000;]
    N2_lowerlimit = 7.5e-8;

    [SA_out, CT_out] = gsw_stabilise_SA_CT(SA,CT,p,N2_lowerlimit)

    SA_out =

       34.7118
       34.8915
       34.4909
       31.5819
       34.7366
       34.7324

    CT_out =

       28.7856
       28.4329
       23.5097
        7.7167
        6.8863
        4.4036

## EXAMPLE 3 (using Matlab Optimization Toolbox):

    SA = [34.7118; 34.8915; 35.0256; 32.0472; 34.7366; 34.7324;]
    CT = [28.7856; 28.4329; 22.8103; 10.2600;  6.8863;  4.4036;]
    p =  [     10;      50;     125;     250;     600;    1000;]
    long = 180;
    lat = 10;

    [SA_out, CT_out] = gsw_stabilise_SA_CT(SA,CT,p,long,lat)

    SA_out =

       34.7118
       34.8915
       34.9499
       32.1229
       34.7366
       34.7324

    CT_out =

       28.7856
       28.4329
       22.9218
        9.9176
        6.8863
        4.4036

## AUTHOR:

    Paul Barker and Trevor McDougall                      [ help@teos-10.org ]

## VERSION NUMBER:

    3.06.3 (20th July, 2017)

## REFERENCES:

    Barker, P.M., and T.J. McDougall, 2017: Stabilising hydrographic
     profiles with minimal change to the water masses.
     J. Atmosph. Ocean. Tech.,

    IOC, SCOR and IAPSO, 2010: The international thermodynamic equation of
     seawater - 2010: Calculation and use of thermodynamic properties.
     Intergovernmental Oceanographic Commission, Manuals and Guides No. 56,
     UNESCO (English), 196 pp.  Available from the TEOS-10 web site.

    McDougall, T.J., D.R. Jackett, D.G. Wright and R. Feistel, 2003:
     Accurate and computationally efficient algorithms for potential
     temperature and density of seawater.  J. Atmosph. Ocean. Tech., 20,
     pp. 730-741.

    Roquet, F., G. Madec, T.J. McDougall and P.M. Barker, 2015: Accurate
     polynomial expressions for the density and specific volume of seawater
     using the TEOS-10 standard.  Ocean Modelling, 90, pp. 29-43.
     http://dx.doi.org/10.1016/j.ocemod.2015.04.002

    The software is available from http://www.TEOS-10.org