In order to get GALAHAD working, here is what you need to do.
===========
PREPARATION
===========
[-1. If you are hoping for advice about installing GALAHAD
under Windows, see README.windows. If this isn't what you wanted,
try Dilipan Sebastiampillai's document lanb2win.pdf.]
0. You will definitely need the package auxiliary package ARCHDefs.
If you plan to use GALAHAD to solve problems written as .SIF
files, you will also need the package SiFDec. If, in addition,
you plan to use the CUTEst interfaces to the GALAHAD FILTRANE, QP,
least-squares, regularization and/or unconstrained minimization routines,
you will also need the package CUTEst. See
https://github.com/ralna/CUTEst/wiki
for details of how to obtain these. CUTEst is not necessary if you simply
wish to use LANCELOT B to solve problems written as .SIF files.
You should download the necessary packages ARCHDefs, SIFDecode and
CUTEst as described in the above Wiki, and set the environment variables
$ARCHDEFS, $SIFDECODE and $CUTEST as described - (see steps 0 and 1 in the
README that comes with SIFDecode/CUTEst for more details - i.e.,
for the C shell (csh):
setenv ARCHDEFS [full path to ./archdefs directory]
setenv SIFDECODE [full path to ./sifdecode directory]
setenv CUTEST [full path to ./cutest directory]
for the bourne again shell (bash)
export ARCHDEFS=[full path to ./archdefs directory]
export SIFDECODE=[full path to ./sifdecode directory]
export CUTEST=[full path to ./cutest directory]
** NOTE THAT YOU DO NOT NEED TO INSTALL THESE PACKAGES, AS THE GALAHAD
INSTALLATION WILL DO THIS FOR YOU IN A PROPERLY-INTEGRATED WAY **
If you plan to use the AMPL interface, you must have installed a working
version of the AMPL interface library, see
ftp://netlib.bell-labs.com/netlib/ampl/solvers.tar
This is not needed if you simply wish to use the GALAHAD packages
stand-alone or via the CUTEst/SIF interface.
There are now C interfaces to a large subset of GALAHAD packages.
See README.C for more details if you want this functionality.
[ 1. Do yourself a favour ... get GNU make:
http://www.gnu.org/software/make/make.html !
GALAHAD is designed to be installed by any variant of the make
program that we are aware of, but such are the incompatibilities
introduced by different vendors, we cannot be sure that make
will work properly on your system. However, if you have
GNU make (sometimes known as gmake), we have high confidence that
your installation will be trouble free. Fortunately GNU make is the
defualt version of make available with most modern operating systems]
2. *- Skip this step if GALAHAD has been downloaded directly using svn or git -*
Put the file
galahad.tar.gz
in a suitable directory for which the ./galahad
directory will be a sub-directory.
2. *- Skip this step if GALAHAD has been downloaded directly using svn or git -*
Issue the command
tar xzvf galahad.tar.gz]
4. Set the environment variable GALAHAD to point at the
./galahad directory, i.e.,
for the C shell (csh):
setenv GALAHAD [full path to ./galahad directory]
for the bourne again shell (bash)
export GALAHAD=[full path to ./galahad directory]
Make this a permanent setting by inserting this command
in your in your .cshrc/.bashrc file (or whichever shell resource file
is appropriate for you) and "source" the file. See
./galahad/doc/README.cshrc and ./galahad/doc/README.bashrc for
more details.
5. Preferably you should also download a subset of the HSL Archive packages,
ad02, ma27 and ma33, that are highly useful to GALAHAD. This is *NOT*
open source software, but the packages are available as a bundle,
WITHOUT CHARGE, by registering at
http://www.hsl.rl.ac.uk/download/hslarchive-galahad/latest
You will need to provide a valid email address, and once you have
registered you will be sent an email message providing a link
to the software as a file in either zip or tar.gz format.
Once you have downloaded this file, it should be uncompressed
in the directory ./ (The destination can be changed by editing the
environment variable $HSL_ARCHIVE in the file
$GALAHAD/src/makedefs/packages.default
see 8 below.)
Without these codes, your choice of key linear equation solvers is
severly restricted. In particular, if the default solver, ssids, is
not supported by yur compiler, you will be forced to use LAPACk
routines, and these may limit the size of problems that can be
solved.
6. If you are intending to use the AMPL interface, set the environment
variable AMPLDIR to point to the directory in which you have installed
the AMPL interface library i.e.,
setenv AMPLDIR [full path to the AMPL interface library directory]
for the bourne again shell (bash)
export AMPLDIR=[full path to the AMPL interface library directory]
Make this a permanent setting by inserting this command
in your in your .cshrc/.bashrc file (or whichever shell resource file
is appropriate for you) and "source" the file. Again, see
./galahad/doc/README.cshrc and ./galahad/doc/README.bashrc for
more details.
[ -*-NB-*- If you plan to use AMPL with the Lahey lf95, Fujistu frt or
Intel ifort compiler, change
extern void MAIN__( VOID );
to
extern int MAIN__( int, char** );
( *note* the double underscore)
somewhere around line 790 in $AMPLDIR/asl.h, as otherwise there will be
clashes between GALAHAD and AMPL C interfaces ]
Details on how to obtain demo (problem-size limited) or full versions
of AMPL are given in
https://ampl.com/try-ampl/download-a-free-demo/
7. Add the directory
$GALAHAD/bin
to your search path (preferably in your .cshrc or similar
file) so that you will be able to use the GALAHAD/CUTEst
interfaces. Again, see ./galahad/doc/README.cshrc or
./galahad/doc/README.bashrc for more details.
8. On installation the file
$GALAHAD/src/makedefs/packages.default
will be copied to
$GALAHAD/src/makedefs/packages
Before installation, you can examine (and edit if you wish) the
file to see how you might provide the source code for additional
external third-party packages, and to find instructions on how to
get them and where to put them.
================ IMPORTANT NEWS FOR POTENTIAL HSL USERS ==============
All the optional HSL software used by GALAHAD is available as a single
tar.gz or gzip file. These files may be DOWNLOADED WITHOUT CHARGE FOR
PERSONAL USE by any academic with a recognised academic email address.
See
http://www.hsl.rl.ac.uk/download/hsl-galahad/latest/d/
(or http://www.hsl.rl.ac.uk/download/hsl-galahad/latest/s/ for a
single precision version) for registration details. Once you have
registered you will be sent an email message providing a link
to the software as a file in either zip or tar.gz format; there may
be a delay in receiving the file, as it has to manually authorized
by the HSL manager.
Once you have downloaded this file, it should be uncompressed in a
convenient location, and we recommend that you choose the directory ./
** N.B. The file ./galahad/src/makedefs/packages.default
** MUST BE EDITED ** to activate the HSL packages.
Once GALAHAD has been installed, any further changes to optional
software should be recorded in the file ./galahad/src/makedefs/packages,
and GALAHAD recompiled so that the changes take effect (see 14 below).
9. You may also optionally provide binary code for a number of external
packages that might make GALAHAD run faster. These include the
BLAS ((basic linear algebra subprograms), LAPACK, MeTiS, PARDISO,
MKL PARDISO, PASTIX, MUMPS and WSMP. Don't worry if you cannot provide
thses; GALAHAD will compile non-optimised versions of the necessary ones
(BLAS, LAPACK) and provide dummy versions of the others. See
./galahad/doc/README.external for more details.
10. If you plan to use the (limited) Matlab interfaces, make sure that
the MATLAB environment variable points to your system Matlab directory,
and that $GALAHAD/src/matlab is on your Matlab path. See README.matlab
for more details.
11 If you are running on a Linux/OSX system, you may need to install the
Open-MPI Portable Hardware Locality (HWLOC) development package
https://www.open-mpi.org/projects/hwloc/
This is readily available in many Linux distributions, e.g., via
sudo apt-get install libhwloc-dev
on Debian/Ubuntu systems,
sudo rpm --install libhwloc-dev
for Redhat ones, or
brew install hwloc
for Macs under OSX.
You will also need to set environment variables OMP_CANCELLATION,
OMP_NESTED and OMP_PROC_BIND to TRUE, and OMP_MAX_ACTIVE_LEVEL to
the maximum number of parallel threads you wish to use.
Under the sh/bash shell, put
export OMP_CANCELLATION=true
export OMP_NESTED=true
export OMP_PROC_BIND=true
export OMP_MAX_ACTIVE_LEVELS=8
in your startup script, to use a maximum of 8 threads, and for csh/tcsh
setenv OMP_CANCELLATION true
setenv OMP_NESTED true
setenv OMP_PROC_BIND true
setenv OMP_MAX_ACTIVE_LEVELS 8
Check with your system administrator if you need help!
If it *really* is impossible to install libhwloc-dev, you should edit
the file $GALAHAD/src/spral/config.h and replace the line
#define HAVE_HWLOC 1
with
#undef HAVE_HWLOC
Alternatively, during the GALAHAD install (13 below), when you get to
the prompt
Would you like to review and modify the C compiler settings (y/N)?
answer y, and change the variable HWLOC to read
HWLOC='un'
Currently this is done automatically for ifort/icc and
gfortran/gcc to avoid compiler bugs
12. For Windows systems that use MSYS/MINGW, you will also need to set the
environment variable MSYS2 to point to the folder that contains the
Unix-style shell and commands, and MINGW64 to the folder that holds
ths commands relating to the GCC/Gfortran compilers. For example,
export MSYS2="/usr"
export MINGW64="/c/msys64/mingw64"
============
INSTALLATION
============
13. To install GALAHAD for a particular machine/os/compiler
combination, move into the $GALAHAD directory,
issue the command
$ARCHDEFS/install_optrove
and answer the questions as prompted. This command sets up
machine/os/compiler-specific files, and (optionally) compiles all
(or suitable sub-components) of GALAHAD (and SiFDec/CUTEst if required),
plus hooks into C and Python, and to Matlab.
You may issue the $ARCHDEFS/install_optrove command for as many
machine/os/compiler combinations as you wish to support, and you
will have access to each independently of the others.
On completion of the installation, please read the message that
gives full details of environment variables that need to be set.
14. To recompile the whole of GALAHAD, move into the directory
$GALAHAD/src
and issue the command
make -f $GALAHAD/makefiles/#
where # is a string of the form
machine.os.compiler
created during one of the installations described in 13 above.
If you want the single-precision version, the appropriate command is
make -f $GALAHAD/makefiles/# PRECIS=single
15. To recompile LANCELOT B, move into the directory
$GALAHAD/src/
and issue the command
make -f $GALAHAD/makefiles/# lancelotb
where # is as in 13 above. To recompile all the QP routines, or the
individual packages (say) QPA, QPB or PRESOLVE, the required commands are
make -f $GALAHAD/makefiles/# qp
make -f $GALAHAD/makefiles/# qpa
make -f $GALAHAD/makefiles/# qpb
make -f $GALAHAD/makefiles/# pre
To recompile the FILTRANE package and its dependencies, the required
command is
make -f $GALAHAD/makefiles/# filtrane
16. Both the makefiles and the run scripts use default values for a
variety of variables. If you wish to use non-default values, you
should edit the appropriate files
$GALAHAD/makefiles/#
and
$GALAHAD/bin/sys/#
Consult the file $GALAHAD/doc/README.non-defaults for some suggestions
=========
EXECUTION
=========
17. To run the QP codes qpa/qpb/qpc on the CUTEst example EXAMPLE.SIF
issue the command
sdgal # qpa [other options] EXAMPLE[.SIF]
or
sdgal # qpa [other options] EXAMPLE[.SIF]
or
sdgal # qpc [other options] EXAMPLE[.SIF]
where # is as in 14 above, from the directory containing the SIF file.
To rerun the most recently decoded example, issue the command
gal # qpa -n [other options]
or
gal # qpb -n [other options]
See README.SIF for more details.
18. To run/rerun LANCELOT B on the CUTE example EXAMPLE.SIF
issue the command
sdgal # lancelot [other options] EXAMPLE[.SIF]
where # is as in 14 above, from the directory containing the SIF file.
To rerun the most recently decoded example, issue the command
gal # lancelot [other options]
See README.SIF for more details.
19. To run/rerun FILTRANE on the CUTE example EXAMPLE.SIF
issue the command
sdgal # filtrane [other options] EXAMPLE[.SIF]
where # is as in 14 above, from the directory containing the SIF file.
To rerun the most recently decoded example, issue the command
gal # filtrane [other options]
See README.SIF for more details.
=======
TESTING
=======
20. To test that the installation of GALAHAD has been successful, you can
move into the directory
$GALAHAD/src
and issue the command
make -f $GALAHAD/makefiles/# tests
where # is as 14 above - for a single precision installation, the command is
make -f $GALAHAD/makefiles/# test PRECIS=single
To test LANCELOT, move into $GALAHAD/src/lancelot , and issue the same
command, to test the QP routines, do the same in the directory
$GALAHAD/src/all_qp , and to test the regularization packages and
the global optimization codes do the same from $GALAHAD/src/all_rq
and $GALAHAD/src/all_go respectively.
To test the C interfaces, again move into the directory
$GALAHAD/src
and issue the command
make -f $GALAHAD/makefiles/# test_all_ciface
21. If you are not using CUTEst, the GALAHAD link library for the
precision you compiled with is in $GALAHAD/objects/#/(precision)/
where (precision) is double or single, and # is as above.
You should add this to your LIBPATH environment variable,
and may then link the library with the -lgalahad compiler flag.
Access to optional auxiliary libraries is via
-lgalahad_hsl -lgalahad_spral -lgalahad_mkl_pardiso
-lgalahad_pardiso -lgalahad_wsmp -lgalahad_pastix -lgalahad_mumps
-lgalahad_mpi -galahad_umfpack -lgalahad_metis_dummy
-lgalahad_lapack -lgalahad_blas
as appropriate; any of these dummies may be replaced by their real
equivalents by using the proper library name, but note that
access to Metis 4 or 5 requires -lgalahad_metis4 or _metis5.
C versions may be accessed by additionally pre-pending
-lgalahad_c -lgalahad_hsl_c
to the previous list
=============
DOCUMENTATION
=============
22. Documentation for package "pack" is available as follows:
- Fortran. PDF documentation is in $GALAHAD/doc/"pack".pdf
- C. HTML documenation is available online from
https://ralna.github.io/galahad_docs/html/C .
There is also inferior PDF documentation in $GALAHAD/doc/"pack"_c.pdf
and a man page in $GALAHAD/man/man3/"pack"_c.3, with a
an introductory man page in $GALAHAD/man/man3/galahad_c.3
- Python. HTML documenation is online as
https://ralna.github.io/galahad_docs/html/Python .
- Julia. HTML documenation is online as
https://ralna.github.io/galahad_docs/html/Julia .
- Matlab. help is provided using hslp galahad_"pack" within Matlab
- general. An introductory paper is in $GALAHAD/doc/galahad.pdf
[23. If you like using graphical user-interfaces, why not try the GALAHAD
python GUI(see $GAHALAD/doc/README.gui for details). This has not
been updated in years, so is probably of limited use.]
====
NEWS
====
24. Refer to the GALAHAD WWW page
http://galahad.rl.ac.uk/galahad-www/
for updates/bug fixes/news.
================
REPORTING ISSUES
================
25. If you have issues that you would like to report, such as potential bugs
or extensons that might be useful, please use the issues page
https://github.com/ralna/GALAHAD/issues
and we will respond as quickly as we can.
Best of luck
Nick Gould
Dominique Orban
Philippe Toint
For GALAHAD productions
25 April 2002
From version 4.2, additionally with
Jari Fowkes
Alexis Montoison
This version, 5.1
5th January 2025