Compiling and testing Tonto

From Tonto Wiki
Jump to: navigation, search
From xkcd

If you just want to use Tonto, you have to compile it first.

But this is the starting point for developers too.

Read this before proceeding to Compiling a parallel version of Tonto !

Contents


Are you ready to get started?

Tonto is a Unix-based library which uses free tools.

Ensure you have these tools before starting.

Read on.

Linux

Make sure you install the following free tools:

  • subversion (svn)
  • gfortran, or another fortran compiler
  • perl
  • gmake
  • vim
  • exuberant ctags
  • Optionally: the blas and lapack libraries.
  • Optionally: the MPICH2, openmpi, LAM or some other parallel MPI library.

Many of these could already be installed.

If not, install them with your package manager.

Mac

Install the same free tools for Mac as for Linux above.

To do this you first need to install

Then, from the command line run the following commands to install the rest of the packages

  fink selfupdate
  fink index
  fink install svn
  fink install make
  fink install exuberant-ctags 

Perl should be installed by default; if not then you can install it using :

  fink install perl-system
 

To use vim install it using

  fink install vim

Vim is recommended since there is a built-in mode for Tonto.

Of course, you can use any other editor.

Windows with cygwin

First install the Unix-like cygwin environment.

During the install process you can select certain boxes which will install the required tools as described for Linux above.

To perform the commands listed below, you need to open a cygwin terminal.

The cygwin terminal is just Unix; just type the commands in the terminal to compile Tonto.

Download Tonto using svn, please!

Tonto is hosted on Sourceforge.

However, don't download the tarball, it is out of date!

Please do install subversion.

Then type the following to get the latest snapshot:

  svn checkout svn://svn.code.sf.net/p/tonto-chem/code/trunk/tonto tonto

This will get the tonto/ source directory.

Change directories into the tonto/ folder that you just downloaded:

  cd tonto

In what follows and in most of the wiki I'll assume that you're always starting in the tonto/ directory.

Quick compilation!

To compile Tonto, type :

  perl -w scripts/Makefile.pl
  make blas
  make lapack
  make

If you already have the blas and lapack libraries installed (this is recommended) and accessible to the environment skip the make commands for those, just type:

  perl -w scripts/Makefile.pl
  make

Thats it!

You should see that the Makefile.pl script recognised your compiler and operating system.

If not, read below.

How do I use a different fortran compiler?

The default compilation procedure above may not have used the fortran compiler that you wanted to use.

If you want to use a specific fortran compiler, type:

  perl -w scripts/Makefile.pl -fc=<insert-your-compiler-here>
  make

where you should replace <insert-your-compiler-here> with the command for your specific fortran compiler.

You should see that the Makefile.pl script recognised your compiler and operating system.

If not, keep reading.

What Fortran compilers do you recommend?

  • We recommend the free gfortran for fast Tonto executables.
  • The Intel compilers generally produce the fastest code but are free only for non-commercial use.
  • On the other hand, g95 produces slower executables but is fast-compiling and very good at error-detection for development.
  • The best compiler for debugging and detecting errors is the NAG fortran compiler but it isn't very fast, and it is commercial.

Where is the Tonto program?

If you've have successfully compiled Tonto -- congratulations!

You've made an executable called tonto in the platform-specific directory:

  <your-compiler-on-your-OS>/tonto

The platform-specific directory, <your-compiler-on-your-OS>, is comprised of the name of your compiler concatenated with your operating system.

For example, if you are using gfortran on a Linux platform, the tonto executable will be produced in the GNU-gfortran-on-LINUX directory

  GNU-gfortran-on-LINUX/fast/tonto

Apart from the executables, the platform-specific directory contains, err, other platform-specific and compiler-option-specific build information.

See The platform-specific directory for more information.

I'm a user: how do I set up Tonto?

Copy tonto to where you normally place your executables
e.g. copy it to ~/bin, or maybe /usr/local/bin

On Linux or Mac, you can remove the .exe suffix if you like.

  cp <your-compiler-on-your-OS>/tonto.exe ~/bin/tonto

On Windows you need to keep the .exe suffix

Now you can type tonto from anywhere to run the program

  tonto

Of course, you'll need to write an input file to get sensible results.

I'm a developer and tweaker: how do I set up Tonto?

Don't copy the tonto executable to your ~/bin directory.

That's because you can compile different versions of Tonto e.g. parallel or debug versions -- and you may want to run different executables at different times.

Because of the way the The platform-specific directory is named, you can have multiple Tonto executables corresponding to different compilers.

So you could use one compiler e.g. gfortran for production jobs and another e.g. g95 for debugging and checking.

On the other hand, Tonto executables made with the same compiler and different compile options will overwrite anything that's already in the platform-specific directory.

For more information:

What if my compiler/system is not recognised?

You will know if the build script has failed if you see mesages about unknown compilers and operating systems.

If it is only an unknown Fortran compiler, install one of the free ones and use the "Makefile -fc=<your-compiler-command" as described above with the full pathname of the compiler to be safe.

If your operating system is unrecognised you should use the platform-specific compiler options file closest to your own case as a template for your new system. Usually that means using a compiler options file with the same fortran compiler, or the same operating system, or more likely a combination of the two.

You will need to

  • Supply appropriate Fortran compile options to the FOPTNS macros
  • Appropriate Foo transltion options to the DEFS macro.
  • Add appropriate library directories using (usually the -L options) in the LIBS macro

See Compiling specific versions of Tonto for more information.

Finally, if you get it to work, please mail us so we can check it into the system.

If you not confident about all this, just e-mail us.

How do I run the test suite?

To run the test suite, type:

  make tests

You should see a majority of the test jobs passing:

 dylan@mars: make tests
 Running test suite
 Using the program "./GNU-gfortran-on-LINUX/run_molecule.exe".
 Running tests in directory "./tests":
 Test name                               Status
 ----------------------------------------------------------
 DZP                                     passed
 ublyp                                   passed
 rhf                                     passed
 rhf_1e_properties                       passed
 Roby_bond_indices                       passed
 Ar_atom_rhf_IOTC                        FAILED
 

It is not necessary for all test jobs to pass.

Some will fail for minor reasons.

Others will fail because they are still in a testing phase or their authors have not verified it works on all platforms.

But if all the test jobs fail, then you know there's a problem!

You should contact us to fix it but first make sure that it is not failing for a minor reason by reading below.

What if the test jobs fails?

Don't panic, it's probably OK.

If a job fails, change into the tests/<job-that-failed> directory.

E.g. in the above example where the Ar_atom_rhf_IOTC job failed, change into tests/Ar_atom_rhf_IOTC directory.

Then, using your favourite diff tool, compare all the files which have a .bad suffix with the original reference file without a .bad suffix:

  vimdiff stdout stdout.bad

Note that there may be several files with the .bad suffix, and you should compare them all to be safe.

You will know if the test job has failed for trivial reasons if the numbers produced are the same to several significant figures (typically a minimum of about five). Unfortunately, numbers such as 0.0 and 0.000 and -0.00 are all regarded as 'different' and will register a test failure at this time. (Would someone like to help modify the perform_tests.pl Perl script to make it more intelligent?).

For example, the image below shows a trivial error in the tests/ediis job when I changed the output format for the atomic number Z. It now displays as a real number rather than an integer

You can ignore differences in dates when the jobs were run and other details such as how long the job took, and how much memory was used: the comparison script also ignores these kinds of differences even though they show up in vimdiff.

Problems, bugs, and contributions?

Send me an email

If you can fix your own bugs, let me know too, and you can easily check the fixes back into sourceforge.