March 29, 2022

The files in this directory are part of the article

  "On the dynamics of coupled oscillators and
   its application to the stability of suspension bridges"
   by G. Arioli.

They contain the details of the proof of Lemmas 4,5,6,10,11,12,13,
written in the programming language Ada2005.

Some program-parts are purely numerical, producing approximate solutions
for certain equations that are used by other program-parts.

The proof itself is divided into declarations, procedures or functions, and main programs.
(Somewhat analogous to definitions, lemmas, and theorems.)
This includes the declaration of data types (Flts.Std.Balls, ...)
that correspond to the standard sets.
Procedures and functions that are centered around a given data type
are organized into

Packages
========
package (name)     declaration (file)       body (file)
-----------------------------------------------------------------
AddEtc              addetc.ads              addetc.adb
Bisection           bisection.ads           bisection.adb
Chebs               chebs.ads               chebs.adb
Check_Bifpt                                 check_bifpt.adb
Check_Branch                                check_branch.adb
Check_Fixpt                                 check_fixpt.adb
Eispack1            eispack1.ads            eispack1.adb
Eispack2            eispack2.ads            eispack2.adb
Flt_AddEtc          flt_addetc.ads
Flt_Matrices        flt_matrices.ads
Flt_Vectors         flt_vectors.ads
FltChains           fltchains.ads           fltchains.adb
Flts                flts.ads                flts.adb
Flts.Plotting       flts-plotting.ads       flts-plotting.adb
Flts.Std            flts-std.ads            flts-std.adb
Flts.Std.Balls      flts-std-balls.ads      flts-std-balls.adb
Flts.Std.EFuns      flts-std-efuns.ads      flts-std-efuns.adb
FltStr              fltstr.ads              fltstr.adb
Fun_Series          fun_series.ads          fun_series.adb
Generic_DFT         generic_dft.ads         generic_dft.adb
Globals             globals.ads
ImproveRoots        improveroots.ads        improveroots.adb
Integer_Subtypes    integer_subtypes.ads
Ints                ints.ads                ints.adb
IPowers             ipowers.ads             ipowers.adb
Linear              linear.ads              linear.adb
Linear.Contr        linear-contr.ads        linear-contr.adb
Logicals            logicals.ads            logicals.adb
Matrices            matrices.ads            matrices.adb
Matrices_More            matrices.ads            matrices.adb
MGeneric            mgeneric.ads            mgeneric.adb
MP_Arch             mp_arch.ads
MPFR                mpfr.ads
MPFR-Floats         mpfr-floats.ads         mpfr-floats.adb
MPFR-Floats-Balls   mpfr-floats-balls.ads   mpfr-floats-balls.adb
MPFR-Floats-EFuns   mpfr-floats-efuns.ads   mpfr-floats-efuns.adb
MultiScalars        multiscalars.ads        multiscalars.adb
Newton              newton.ads              newton.adb
Params              params.ads              params.adb
Params.Names        params-names.ads
Polynoms            polynoms.ads            polynoms.adb
Polynoms2           polynoms2.ads           polynoms2.adb
Polynoms.More       polynoms-more.ads       polynoms-more.adb
Pooling             pooling.ads             pooling.adb
Protected_Counters  protected_counters.ads  protected_counters.adb
QPowers             qpowers.ads             qpowers.adb
Quick_Sort          quick_sort.ads          quick_sort.adb
Rationals           rationals.ads           rationals.adb
Recycling           recycling.ads           recycling.adb
Reps                reps.ads
Roots               roots.ads               roots.adb
Rounding            rounding.ads
Rounding_FPU        rounding-fpu.ads        rounding-fpu.adb
Scalars             scalars.ads
ScalVectors         scalvectors.ads         scalvectors.adb
ScalVectors.RNum    scalvectors-rnum.ads    scalvectors-rnum.adb
Strings             strings.ads             strings.adb
Taylors1            taylors1.ads            taylors1.adb
Taylors1.Cheb       taylors1-cheb.ads       taylors1-cheb.adb
Taylors1.Cheb.Fix   taylors1-cheb-fix.ads   taylors1-cheb-fix.adb
Taylors2            taylors2.ads            taylors2.adb
Taylors2.Cheb       taylors2-cheb.ads       taylors2-cheb.adb
Taylors2.Cheb.Fix   taylors2-cheb-fix.ads   taylors2-cheb-fix.adb
Vectors             vectors.ads             vectors.adb
Vectors.More        vectors-more.ads        vectors-more.adb
Vectors.Ops         vectors-ops.ads         vectors-ops.adb
Vectors.Sorting     vectors-sorting.ads     vectors-sorting.adb
VGeneric            vgeneric.ads            vgeneric.adb

Main programs
============
program (name)      body (file)
-------------------------------
Run_All             run_all.adb
Plots               plots.adb

Other
===========================
file or directory   comment
---------------------------
README              this file
log                 log file
data                contains all approximate solutions
pics                contains data to make pictures

Floating point types and portability
====================================

The basic floating point types used is
Flts.Std.Rep (defined indirectly as Long_Long_Float) and MPFR.Floats.

Both types support controlled and correct rounding.

Long_Long_Float is specific to the gnat compiler.
It implements the IEEE 754 Extended 80 bit (64 bit mantissa) floating point format.

MPFloat is essentially the floating point type from the
multiple-precision floating-point library MPFR,
see MPFR_Floats, MPFR, and http://www.mpfr.org/
MPFR is written C, is free,
and distributed under the GNU Lesser General Public License.

Our package FPU_Rounding is specific to the x87 floating point processor.
For other processors this package will have to be changed appropriately.
We note that only two FPU rounding modes are being used:
"rounding up" for all rigorous estimates, and
"rounding to nearest" for numerical computations.

On systems that do not recognize "/" as path separator, the variables
Globals.Input_Dir, Globals.Output_Dir, and Globals.Tmp_Dir
will have to be adapted to the system's convention.

Compiling etc.
==============

With the gnat compiler (http://gcc.gnu.org/software/gnat/),
compiling the program Check_Branch is achieved with:

gnatmake -c -frounding-math run_all
gnatbind -E run_all.ali
gnatlink run_all.ali -lmpfr -lgmp -lm

Do not use any optimization flags.

Running
===================================

The syntax to run the main program run_all is
run_all NN SS
Here NN is the desired maximal number of concurrent tasks,
and SS is a number in (1,...,33) representing the solution to be checked.
If SS=0 is used, then the whole proof is ran.
A reasonable choice for NN is the number of CPU threads available.

The program Plots may be used to produce data to plot the graphs of the
solutions. THe syntax to run it is
plots SS LL
Here SS is a number in (1,...,33) representing the solution to be plotted,
and LL, a floating point number in [-1,1], represents the position along
the subinterval.
The running time of run_all on a Intel(R) Xeon(R) W-2295 CPU @ 3.00GHz
is less than two hours. The large majority of this time is used to verify
the case i=2 of Lemma 6.