http://www.flaterco.com/xtide/files.html#experts


$Id: README 4154 2012-01-05 00:45:39Z flaterco $

    congen:  constituent generator.
    Copyright (C) 1997  David Flater.

    This program 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.

    This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.


Preface
-------

This README is intended to be read using a monospace font and the UTF-8
character encoding.  One can launch a suitable xterm with the following
command:

LANG=en_US.utf8 xterm -fn -misc-fixed-medium-r-normal--20-200-75-75-c-100-iso10646-1 &


Overview
--------

This is the README file for the Congen package.  The Congen package contains
three distinct pieces, each of which is documented in more detail below:

1.  libcongen, a C++ library for generating the speeds, equilibrium arguments,
and node factors of tidal constituents.

2.  congen, a command-line program for generating the speeds, equilibrium
arguments, and node factors of tidal constituents using text files for input
and output.

3.  diff_congen_output, a utility program used only for testing.

THIS PACKAGE IS AVAILABLE FROM:
http://www.flaterco.com/xtide/files.html#experts


Prerequisites
-------------

This package was tested with g++ version 4.4.3 and GNU sed version 4.1.5 under
GNU/Linux.

If libtcd is properly installed, the congen program will automatically be
linked with it and enabled to generate a TCD file in lieu of its usual text
format output.  libtcd can be obtained from
http://www.flaterco.com/xtide/files.html#libtcd .

If libtcd is absent, the congen program will still compile but the -tcd command
line option will be disabled.


Installation
------------

Congen is packaged with GNU automake, so all usual GNU tricks should work.
Help on configuration options can be found in the INSTALL file or obtained by
entering ./configure --help.

Normally, one should only need to do the following to compile and install the
library and client program:

bash-3.1$ ./configure
bash-3.1$ make
bash-3.1$ su
bash-3.1# make install

However, in the event that libtcd is installed in a nonstandard location, an
invocation such as the following might be required:

bash-3.1$ ./configure CPPFLAGS="-I/usr/local/libtcd/include" \
                      LDFLAGS="-L/usr/local/libtcd/lib"
bash-3.1$ make


libcongen
---------

libcongen is a C++ library for generating the speeds, equilibrium arguments,
and node factors of Darwin-style tidal constituents more or less as defined in
SP 98:

   Manual of Harmonic Analysis and Prediction of Tides.  Special Publication
   No. 98, Revised (1940) Edition (reprinted 1958 with corrections;
   reprinted again 1994).  United States Government Printing Office, 1994.

Additionally, libcongen provides limited support for approximating
Doodson-style tidal constituents within the infrastructure of the former.  The
Doodson approach is discussed in the following publication:

   Foreman, M.G.G., 1977.  Manual for Tidal Heights Analysis and Prediction.
   Pacific Marine Science Report 77-10, Institute of Ocean Sciences,
   Patricia Bay, Sidney, B.C. (2004 revision).

The Congen header file is intended to be self-documenting with regards to use
of the interface, assuming that one has access to SP 98 and a general
understanding of the subject matter.  Client programs should #include <Congen>
and link with -lcongen -lm.


congen
------

The congen program provides the functionality of libcongen using text files for
input and output.  This is the interface that was used exclusively through
congen version 1.5.

Usage: congen [-b year] [-e year] [-a1|-a2] [-tcd filename] [-sp98test]
              < congen_input.txt > output.txt

Years may range from 1 to 4000, but the Gregorian calendar is assumed in all
cases.

-b year   Sets the first year for which to generate output.  Default 1970.

-e year   Sets the last year for which to generate output.  Default 2037.

-a1       Calibrate speeds of constituents for 1900-01-01.  This is the default
          and it is necessary for compatibility with NOS.

-a2       Calibrate speeds of constituents for the beginning of the year that
          is midway between the first and last years.

-tcd filename  Instead of sending text format output to stdout, write the
               results as a TCD file.  Requires libtcd.

-sp98test   As a sanity check, generate tables from SP 98 and send to stdout.
            Make sure your terminal is using a monospace font, UTF-8, and at
            least 87 characters wide.

The format of the input file for the congen program is defined below.  Please
see the included file congen_input.txt for numerous examples.

                                - Terminology -

(Vₒ+u)   Constituent argument at beginning of a tidal series
f        Node factor

V        Principal portion of constituent argument
T        Hour angle of mean sun
s        Mean longitude of moon
h        Mean longitude of sun
p        Mean longitude of lunar perigee
p₁       Mean longitude of solar perigee

u        Part of constituent argument depending upon variations in obliquity of
         lunar orbit
ξ        Longitude in moon's orbit of lunar intersection
ν        Right ascension of lunar intersection
ν′       Term in argument of lunisolar constituent K₁
2ν″      Term in argument of lunisolar constituent K₂
Q        Term in argument of constituent M₁
R        Term in argument of constituent L₂
Qᵤ       Term in argument of constituent M₁
N        Longitude of moon's node

r    (For Doodson satellite) Amplitude ratio vs. the main constituent
α    (For Doodson satellite) Phase correction vs. the main constituent

                         - Darwin-style constituents -

A Darwin-style constituent is specified as a line of this form:
  name  Basic   T s h p p₁ c   ξ ν ν′ 2ν″ Q R   f_formula

c is a constant term specified in degrees.  The other lettered fields give
coefficients of the astronomical terms defined above.

With the exception of "unity," for which we use 1, Congen and SP 98 Table 2
identify node factor formulas by their formula numbers in SP 98.  Users of
libcongen have the benefit of symbolic constants defined in the Congen header
file, but in congen input you must supply the number.

  f_1   = 1;
  f_Mm  = 73;
  f_Mf  = 74;
  f_O₁  = 75;
  f_J₁  = 76;
  f_OO₁ = 77;
  f_M₂  = 78;
  f_KJ₂ = 79;
  f_M₁C = 144;  // A71 in SP 98.
  f_M₃  = 149;
  f_M₁  = 206;  // Unique U.S. definition.
  f_L₂  = 215;
  f_K₁  = 227;
  f_K₂  = 235;

                        - Doodson-style constituents -

A Doodson-style constituent begins with a line of this form:
  name  Doodson   T s h p p₁ c   #-satellites
followed by additional lines that specify the indicated number of satellites,
possibly more than one per line.

Each satellite has the following form, which is identical to the format used in
the IOS tidal package's tide3.dat file:
      Δp -ΔN Δp₁ α r[RN]
(A capital letter 'R' and a digit are optionally suffixed to r.)

Please note:
  Consistent with IOS, ΔN is NEGATED.
  Consistent with IOS, α is specified in ROTATIONS, not degrees.
  Latitude-dependent satellites (those with RN) are IGNORED by congen.

Following is a complete example of a translation from IOS' tide3.dat.

Before:

      R2      2  2 -1  0  0 -1-0.50   2
      R2     0  0  2 .50 0.2535     0  1  2 .0  0.0141

After:

R2-IOS  Doodson   2 0 1 0 -1 180    2
             0  0  2 .50 0.2535     0  1  2 .0  0.0141

Note the differences in the V part of the record.  In Congen terms, the first
part of the record for each constituent in IOS' tide3.dat has the following
form:
   T  s+X  h-X  p  -N  p₁  -c (rotations)
where X is the trailing digit on the constituent name (e.g., for NO₁ X=1, for
M₂ X=2).  For H₁ (a special case), use X=2; for constituents without trailing
numbers, use X=0.

N is always zero.  So to get T, s, h, p, p₁, c as expected by Congen,
  Given       T       s+X       h-X    p     -N    p₁     -c (rotations)
  Do this    same  subtract X  add X  same  skip  same  multiply by -360
  To get      T        s         h     p           p₁      c (degrees)

                           - Compound constituents -

A compound constituent may be specified as a line of this form, providing
coefficients of the indicated constituents:
  name  Compound   O₁ K₁ P₁ M₂ S₂ N₂ L₂ K₂ Q₁ ν₂ S₁ M₁-DUTCH λ₂
Trailing zeroes may be omitted.

Congen uses compiled-in definitions of the indicated constituents to compute
the compound constituent, so each of the 13 may be specified in lazy fashion
using a coefficient of 1 for itself.

                                 - Comments -

Comment lines contain # in the first column.


diff_congen_output
------------------

The program diff_congen_output compares two congen outputs, which are assumed
to have been generated from the same or comparable input, and reports on
discrepancies between them.  It is not useful for anything but testing, so it
is not installed by 'make install.'

"Comparable input" means that the constituents must have the same names, be in
the same order, and have the same range of years.

diff_congen_output ignores the following amount of error:
  speeds:                   0 degrees/hour
  equilibrium arguments:  .01 degree
  node factors:         .0001

This corresponds to rounding differences in the last significant digit of
equilibrium arguments and node factors and zero tolerance for differences in
speeds.


UTF-8 sources
-------------

The source files in this package, as well as this README, use the UTF-8
character encoding to accurately reproduce the Greek letters and so forth that
were used in the original formulæ.  However, as of 2007 and g++ 4.2.0,
compiling a program that uses Unicode characters in identifiers is still
difficult and not very portable.  This distribution therefore uses a sed script
to automatically replace the Unicode characters in source files with plain
text; λ becomes lambda, Δ becomes DELTA, etc.

The source code as it was originally intended to look is in the utf8-src
subdirectory of the distribution.  For maximum readability, those wishing to
review the source code should read the sources in utf8-src on a UTF-8 enabled
terminal rather than the "mangled" versions that are built from them.  In
future years when 8-bit character sets are a distant memory, it may become
possible to make more direct use of the original sources.


Supporting materials
--------------------

The following may be downloaded from http://www.flaterco.com/xtide/files.html
under the headings "For experts only" and "Miscellaneous government
publications:"

  IHO list of constituents (2006 and 2003 versions), downloaded from
  http://www.iho.shom.fr/COMMITTEES/TC/Constituents.pdf.

  NAVO.xls, spreadsheet of constituent definitions contributed by Art Najjar
  of NAVO.

  seasonal_corrections.xls, a spreadsheet for approximating Sa and Ssa from
  Admiralty-style seasonal corrections.  Contributed by Art Najjar of NAVO.

Information on obtaining the IOS tidal package is at:
http://www.pac.dfo-mpo.gc.ca/sci/osap/projects/tidpack/tidpack_e.htm


Regression test
---------------

Congen 1.6 is a complete rewrite of Congen 1.5.

Comparing the 175 constituents in congen_input.txt rev. 2004-08-16, years 1 to
3999, versus the output from congen 1.5, the reported discrepancies are:

Argument of 2MS2K2 mismatch (max delta 0.02)
Argument of M2(KS)2 mismatch (max delta 0.02)
Argument of 2KM(SN)2 mismatch (max delta 0.02)
Node factor of OO1 mismatch (max delta 0.0002)
Node factor of KQ1 mismatch (max delta 0.0002)

The three constituents having equilibrium argument mismatches are the only
constituents having a coefficient of K₂ greater than one.  These minor
differences are attributable to the change in Congen 1.6 to a simpler formula
for computing 2ν″.

OO₁ and KQ₁ are the only constituents using formula 77 for their node factors.
In this case, the formulas being used are mathematically equivalent.  The only
distinguishing feature of formula 77 versus the others is a relatively small
divisor that apparently suffices to magnify floating point noise above the
threshold of significance.  Nevertheless, the change versus Congen 1.5 is minor
and negligible.

Output written directly to TCD may show occasional differences in the last
decimal place versus output that was first exported to text.  These negligible
differences appear because passing numbers directly to libtcd results in a
different rounding behavior than if they are first rounded to X digits by the
export to text.

Discrepancies between Congen results and those printed in SP 98 and its
supplement are orders of magnitude greater than the discrepancies discussed
above, yet there is still negligible impact on matching tide predictions versus
the National Ocean Service's published predictions.


(End of README)


http://www.flaterco.com/xtide/files.html#experts