Prerequisite

SOLVCON depends on the following packages:

gcc 4.3+
SCons 2+
Python 2.6 or 2.7 (2.7 is preferred)
Numpy 1.5+
LAPACK
NetCDF 4+
METIS 4.0.3+ (SOLVCON will download it for you on building) or SCOTCH 5.1+
Nose 1.0+
gmsh 2.5+
VTK 5.6+

The following command will install these packages on Debian/Ubunbu:

$ sudo apt-get install build-essential gcc scons liblapack-pic libnetcdf-dev
libnetcdf6 netcdf-bin libscotch-5.1 python2.7 python2.7-dev python-numpy
python-nose gmsh python-vtk

Note: For Debian Squeeze (6.0), you need also apt-get install python-profiler to install the built-in Python profiler.

Building document of SOLVCON requires the following packages:

Epydoc 3+
pygraphviz 1.1+
Sphinx 1.0+

which can be installed on Debian/Ubunbu by using the command:

$ sudo apt-get install python-epydoc python-pygraphviz python-sphinx

Another optional dependency is CUDA, which needs to be separately installed and configured. For using meshes with more then 35 million cells, SCOTCH-5.1 is recommended. METIS-4 has issues on memory allocation for large graphs.

Install

There are three steps to install SOLVCON:

Obtain the latest release from https://bitbucket.org/yungyuc/solvcon/downloads . Unpack the source tarball.
Get into the source tree and run SCons to build the binary codes:
```
$ cd $SCSRC
$ scons --download --extract
```
where $SCSRC indicates the root directory of unpacked source tree.
Install everything:
```
$ python setup.py install
```

The option --download used above lets the building script download necessary external source packages, e.g., METIS, from Internet. Option --extract extracts the downloaded packages.

Although not recommended, you can optionally install SOLVCON to your $HOME/.local directory. It is one of the workarounds when you don't have the root permission on the system. To do this, add the --user when invoking the setup.py script:

$ python setup.py install --user

SOLVCON is designed to work without explicit installation. You can simply set the $PYTHONPATH environment variable to point to the unpacked source distribution ($SCSRC). Compilation of binary code by using SCons is still required.

Development Version

To use the latest development version, you need to use Mercurial to access the source repository. Clone the repository:

$ sudo apt-get install mercurial
$ hg clone https://bitbucket.org/yungyuc/solvcon

and follow steps 2 and 3 in Install.

Rebuild/Reinstall

If you want to rebuild and reinstall, you can run:

$ cd $SCSRC
$ scons
$ python setup.py install

without using the options --download and --extract. If you want a clean rebuild, run scons -c before scons.

Unit Test

If you have Nose installed, you can run:

$ nosetests

inside the source tree for unit tests. To test the installed package, use the following command instead:

$ python -c 'import solvcon; solvcon.test()'

When testing the installed package, make sure your current directory does not have a sub-directory named as solvcon.

Because SOLVCON uses ssh as its default approach for remote procedure call (RPC), you need to set up the public key authentication for ssh, or some of the unit tests for RPC could fail. Some tests using optional libraries could be skipped (indicated by S), if you do not have the libraries installed. Everything else should pass.

Build and Install Dependencies (Optional)

SOLVCON depends on a number of external software packages. Although these dependencies should be taken care by OSes, it takes time to get the support personnels to install missing packages on a cluster/supercomputer. As such, SOLVCON provides a simple building system to facilitate the installation into a customizable location.

The $SCSRC/ground directory contains scripts to build most of the packages that SOLVCON depends on. The $SCSRC/ground/get script downloads the source packages to be built. The $SCSRC/ground/Makefile file has three default targets: binary, python, and vtk. The built files will be automatically installed into the path specified by the $SCROOT environment variable, which is set to $HOME/opt/scruntime by default. The $SCROOT/bin/scvars.sh script will be created to export necessary environment variables for the installed software, and the $SCROOT environment variable itself.

The $SCSRC/soil directory contains scripts to build gcc. The $SCROOT/bin/scgccvars.sh script will be created to export necessary environment variables for the self-compiled gcc. The enabled languages include only C, C++, and Fortran. The default value of $SCROOT remains to be $HOME/opt/scruntime, while the software will be installed into $SCROOT/soil. Note: (i) Do not use different $SCROOT when building $SCSRC/soil and $SCSRC/ground. (ii) On hyper-threading CPUs the NP environment variable should be set to the actual number of cores, or compilation of gcc could exhaust system memory.

$SCROOT/bin/scvars.sh and $SCROOT/bin/scgccvars.sh can be separately sourced. The two sets of packages reside in different directories and do not mix with each other nor system software. Users can disable these environments by not sourcing the two scripts.

Some packages have not been incorporated into the dependency building system described above. Debian or Ubuntu users should install the additional dependencies by using:

$ sudo apt-get install build-essential gcc gfortran gcc-multilib m4
 libreadline6 libreadline6-dev libncursesw5 libncurses5-dev libbz2-1.0
 libbz2-dev libdb4.8 libdb-dev libgdbm3 libgdbm-dev libsqlite3-0
 libsqlite3-dev libcurl4-gnutls-dev libhdf5-serial-dev libgl1-mesa-dev
 libxt-dev

These building scripts have only been tested with 64-bit Linux.

How to Use

SOLVCON installs a command-line script scg for users. The tool allows users to access pre-defined functionalities of SOLVCON, e.g., mesh conversion, log analysis, etc., by executing:

$ scg <command>

The best way to learn SOLVCON is to read the examples provided in the source package. These examples are in the $SCSRC/examples/ directory. The layout of the example directory is like:

examples/
|-- ...
|   |-- ...
|   `-- ...
|-- ...
|   |-- ...
|   |-- ...
|   |-- ...
|   `-- ...
`-- ...
    |-- ...
    `-- ...

Before running the examples, you need to obtain the supplemental data. When using the development version, users can simply go to $SCSRC and download the data by executing scons --get-scdata. When using the released source package, users should download the scdata tarball that matches the source version.

There is a go file in each of the example directories, which is the "driving script". Please read the docstring in the go scripts for more information.

SOLVCON Framework

SOLVCON is developed as a software framework in order to aid development of PDE solvers. A software framework is designed to mitigate complexity in software development. There are a lot of software frameworks developed for various purposes, e.g., MFC, Qt, wxWidgets for GUI programs, Django, Ruby on Rails for web apps, ACE, Twisted for network services, etc.

Developing code with a software framework is very different from the development of legacy scientific codes. In order to provide a pre-defined, well-organized structure of application programs, it is the framework runs your code, but not your code calls the framework. In other words, SOLVCON inverses the flow of control, such that PDE solvers can and must be implemented in a well-organized way. The concept of Inversion of Control (IoC) is worth an in-depth study.