INVERTASTIC README
==================

-----------------
Copyright 2016 The University of Edinburgh

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. 
-----------------


About
-----------------

Invertastic is a utility for performing large-scale dense SPD matrix
inversions on parallel computers. For full details, please see

A. Gray, "Invertastic: Large-scale Dense Matrix Inversion", 
ARCHER Whitepaper available at www.archer.ac.uk/documentation/white-papers/

This software is openly available as a central package on the UK
ARCHER national supercomputing facility at /work/y07/y07/itastic

Options
----------------

Invertastic accepts the following arguments:

 --size <N>

 	specify size N for NxN square matrix to be inverted

[--check] 

 	if specified, the code will multiply the original matrix by
	the resulting inverse, compare this product (element-wise)
	with the expected identity matrix, and print the maximum
	deviation.


[--input <full path to input file>] 

	if specified, the code will read the input matrix from the
        specified file. The format should be binary with NxN 8-byte
        (double precision) entries and no headers. If not specified to
        allow performance benchmarking and testing the code will
        create an SPD matrix on-the-fly using random numbers.


[--output <full path to output file>] 

	if specified, the code will write the binary output matrix to
	the specified file. The format will be binary with NxN 8-byte
	(double precision) entries and no headers.


Compilation
----------------

Invertastic depends on MPI, PBLAS, BLACS, and ScaLAPACK libraries. The
Makefile is currently configured for the ARCHER UK national
supercomputing facility, using Intel MKL. To compile on ARCHER:

module swap PrgEnv-cray PrgEnv-intel
cd src
make clean
make

To configure for other machines, the Makefile should be edited to
specify the appropriate paths.



Execution
---------------

This distribution contains a sample job script, run_archer.sh, for running
invertastic on ARCHER using the PBS job submission system.