Getting Started

Installation

COPSS is based on the LIBMESH framework. It also requires PETSc for parallel linear equation solvers and SLEPc for scalable Eigenvalue computations. In order to achieve the best parallel performance of COPSS, we strongly suggest you to install the dependent libraries on a Linux cluster environment. Below are the instructions to install COPSS.

0. System environment preparation

• CMAKE (e.g., but not necessarily, version 3.6.2)

• GCC (e.g., but not necessarily, version 6.2)

• PYTHON (python 2)

• OPENMPI (e.g., but not necessarily, version 2.0.1)

1. Installing PETSc

• Download PETSC’s latest release ( version 3.7.4 or later ) from PETSc download page, or git clone PETSc repository and follow these steps:

  • mkdir $HOME/projects/

  • cd $HOME/projects/

  • git clone -b maint https://bitbucket.org/petsc/petsc petsc

• Configure PETSc:

  • cd $HOME/projects/petsc

  • ./configure --with-cc=mpicc --with-cxx=mpicxx --with-mpiexec=mpiexec --with-fc=mpif90 --download-fblaslapack --download-scalapack --download-mumps --download-superlu_dist --download-hypre --download-ml --download-parmetis --download-metis --download-triangle --download-chaco --with-debugging=0

  • And then follow the instructions on screen to install and test the package.

• Export environment variables: add the following lines to ~/.bashrc and execute source ~/.bashrc before next step. (/path/to/PETSC and PETSC_ARCH_NAME can be found on the screen after the installation.)

  • export PETSC_DIR=/path/to/PETSC

  • export PETSC_ARCH=PETSC_ARCH_NAME

• In case of any trouble, please refer to PETSC installation.

2. Installing SLEPc

• Download SLEPC’s latest release (version 3.7.3 or later) from SLEPc download, or git clone PETSc repository:

  • cd $HOME/projects/

  • git clone -b maint https://bitbucket.org/slepc/slepc slepc

• Configure PETSc:

  • cd $HOME/projects/slepc

  • ./configure

  • And then follow the instructions on screen to install the package

• Exporting environment variables: add the following codes to ~/.bashrc and source ~/.bashrc before next step. (/path/to/SLEPC and SLEPC_ARCH_NAME can be found on the screen post installation.)

  • export SLEPC_DIR=/path/to/SLEPC

  • export SLEPC_ARCH=SLEPC_ARCH_NAME

• Test the package (highly recommended bu not necessary)

  • make test

• In case of any trouble, please refer to SLEPC installation.

3. Installing LIBMESH

• Download LIBMESH’s latest release ( version 1.1.0 or later ) from LIBMESH download, or git clone PETSc repository:

  • cd $HOME/projects/

  • git clone git://github.com/libMesh/libmesh.git

• Build LIBMESH:

  • cd $HOME/projects/libmesh

  • ./configure -prefix=$HOME/projects/libmesh/libmesh-opt --enable-optional --enable-vtk  --enable-gzstream --enable-trilinos --disable-strict-lgpl --enable-laspack --enable-capnproto --enable-trilinos --enable-nodeconstraint --enable-perflog --enable-ifem --enable-petsc --enable-blocked-storage --enable-slepc --enable-unique-id --enable-unique-ptr --enable-parmesh 2>&1 | tee my_config_output_opt.txt (Read the configuration output, make sure PETSC and SLEPC are enabled).

  • And then follow the instructions on screen to install and test the package.

• Export environment variables: add the following codes to ~/.bashrc and source ~/.bashrc before next step. (/path/to/PETSC can be found on the screen after installation.)

  • export LIBMESH_DIR=/path/to/LIBMESH

• If you meet any trouble, please refer to LIBMESH installation, or reach out to LIBMESH community for help.

4. Install COPSS-hydrodynamics

• Download the latest COPSS codes

  • git clone https://bitbucket.org/COPSS/copss-hydrodynamics-public.git

• Add the path to COPSS to system environment: add the following code block to ~/.bashrc and source it prior to the next steps.

  • export COPSS_DIR="/path/to/copss" (notice: be careful not to include ‘/’ at the end)

  For example, in my system:

  • export COPSS_DIR="/scratch/midway2/jyli/bitbucket/MICCOM/copss/copss-hydrodynamics-private"

• Compiling the codes

  1. Manually compile the code by following steps

     • cd $COPSS_DIR/src/

     • make package=POINTPARICLE (for point particle systems)

     • make package=RIGIDPARTICLE (for rigid particle systems)

  2. Use auto compilation tool: the compilation tool is located at $COPSS_DIR/tools/compile.sh. To use it, depending on your purpose, execute one of the following commands:

     • cd $COPSS_DIR/tools/

     • bash compile.sh -h (For help)

     • bash compile.sh -p POINTPARTICLE (Compile PointParticle package)

     • bash compile.sh -a clean_first -p POINTPARTICLE (Compile POINTPARTICLE package after cleaning)

  3. To run a sedimentation example for rigid particles

     • cd $COPSS_DIR/examples/general_rigid_particle/sedimentation_benchmark/

     • bash run.sh

Build documentation

After building COPSS-Hydrodynamics successfully, you can further build the documentation in docs/ directory.

1. Doxygen

   The documentation built using Doxygen gives the code-level details, including the code structures, class inheritance, details of functions, etc. To compile the documentation, make sure [Doxygen](http://www.stack.nl/~dimitri/doxygen/) is ready to be used in the system, then:

   • cd $COPSS_DIR/docs/doxygen/

   • doxygen Doxyfile.bak

   then you can view the documentation in an IE browser:

   • google-chrome [path-to-copss]/docs/doxygen/html/index.html

2. Sphinx The documentation built using Sphinx gives the tutorial-level details, including features of the package, how to run a simulation, how to use a tool, etc. To compile Sphinx, make sure you have Sphinx ready, then:

   • cd $COPSS_DIR/docs/sphinx

   • make html

   then you can view the documentation in an IE browser:

   • google-chrome [path-to-copss]/docs/sphinx/build/html/index.html

   To modify Sphinx documentation, you need to write the documentation in one of the rst files, for example, if the documentation is about how to run a simulation, it should be written into:

   • $COPSS_DIR/docs/sphinx/source/tutorials.rst