============================ Solvers of Conservation Laws ============================ SOLVCON is a collection of `Python `__-based conservation-law solvers that use the space-time `Conservation Element and Solution Element (CESE) method `__. SOLVCON targets at solving problems that can be formulated as a system of first-order, linear or non-linear partial differential equations (PDEs) [Lax73]_: .. math:: \dpd{\bvec{u}}{t} + \sum_{\iota=1}^3 \mathrm{A}^{(\iota)}(\bvec{u})\dpd{\bvec{u}}{x_{\iota}} = \bvec{s}(\bvec{u}) where :math:`\bvec{u}` is the unknown vector, :math:`\mathrm{A}^{(1)}`, :math:`\mathrm{A}^{(2)}`, and :math:`\mathrm{A}^{(3)}` the Jacobian matrices, and :math:`\bvec{s}` the source term. - Visit the project page https://bitbucket.org/solvcon/solvcon - Report bugs and request features at https://bitbucket.org/solvcon/solvcon/issues?status=new&status=open - Ask questions in our `mailing list `__: solvcon@googlegroups.com Install ======= Please use the development version in the Mercurial_ repository:: hg clone https://bitbucket.org/solvcon/solvcon Released source tarballs can be downloaded from https://bitbucket.org/solvcon/solvcon/downloads, but the development version is recommended. Prerequisites +++++++++++++ SOLVCON itself depends on the following packages: - `gcc `_ 4.3+ - `SCons `_ 2+ - `Python `_ 2.7 - `Cython `_ 0.16+ - `Numpy `_ 1.5+ - `LAPACK `_ - `NetCDF `_ 4+ - `SCOTCH `_ 5.1+ - `Nose `_ 1.0+ - `gmsh `_ 2.5+ - `VTK `_ 5.6+ Building document of SOLVCON requires the following packages: - `pygraphviz `_ 1.1+ - `Sphinx `_ 1.1.2+ - `Sphinxcontrib issue tracker `__ 0.11 You will also need `Mercurial `_ (hg) to clone the development codebase. The following command will install the dependencies on Debian jessie: .. literalinclude:: ../../contrib/aptget.debian.jessie.sh On Ubuntu 12.04LTS please use: .. literalinclude:: ../../contrib/aptget.ubuntu.12.04LTS.sh Note: For Debian 6.x (squeeze), you need also ``apt-get install python-profiler`` for the Python built-in profiler. Build +++++ The binary part of SOLVCON should be built with SCons_:: cd $SCSRC scons where ``$SCSRC`` indicates the root directory of unpacked source tree. The source tarball supports distutils and can built alternatively:: python setup.py build_ext --inplace SOLVCON is designed to work without explicit installation. You can simply set the environment variable ``$PYTHONPATH`` to point to the source code, i.e., ``$SCSRC``. Note that the binary code is needed to be compiled. .. note:: The Python runtime will search the paths in the environment variable ``$PYTHONPATH`` for Python modules. See http://docs.python.org/tutorial/modules.html#the-module-search-path for detail. Run Tests +++++++++ Tests should be run with Nose_:: nosetests in the project root directory ``$SCSRC``. Another set of tests are collected in ``$SCSRC/ftests/`` directory, and can be run with:: nosetests ftests/* Some tests in ``$SCSRC/ftests/`` involve remote procedure call (RPC) that uses `ssh `_, so you need to set up the public key authentication of ssh. Manually Build Prerequisites (Optional) +++++++++++++++++++++++++++++++++++++++ On a cluster or a supercomputer, it is impossible for a user to use package managers (e.g., apt or yum) to install the prerequisites. It is also time-consuming to ask support people to install those packages. Building the required software manually is the most feasible approach to get the prerequisites. SOLVCON provides a suite of scripts and makefiles to facilitate the tedious process. The ``$SCSRC/ground`` directory contains scripts to build most of the software that SOLVCON depends on. The ``$SCSRC/ground/get`` script downloads the source packages to be built. By default, the ``$SCSRC/ground/Makefile`` file does not make large packages related to visualization, e.g., VTK. Visualization packages must be manually built by specifying the target ``vislib``. 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. Documentation ============= .. toctree:: :maxdepth: 2 tutorial Architecture Reference ++++++++++++++++++++++ .. toctree:: :maxdepth: 3 architecture inout system_modules Application Reference +++++++++++++++++++++ .. toctree:: :maxdepth: 2 app_linear Development Support +++++++++++++++++++ .. toctree:: :maxdepth: 1 python_style plan verification Other Resources +++++++++++++++ - Papers and presentations: - :doc:`pub_app` - `PyCon US 2011 talk `__: `slides `__ and `video `__ - Yung-Yu Chen, David Bilyeu, Lixiang Yang, and Sheng-Tao John Yu, "SOLVCON: A Python-Based CFD Software Framework for Hybrid Parallelization", *49th AIAA Aerospace Sciences Meeting*, January 4-7 2011, Orlando, Florida. `AIAA Paper 2011-1065 `_ - The CESE method: - The CE/SE working group: http://www.grc.nasa.gov/WWW/microbus/ - The CESE research group at OSU: http://cfd.solvcon.net/research.html - Selected papers: - Sin-Chung Chang, "The Method of Space-Time Conservation Element and Solution Element -- A New Approach for Solving the Navier-Stokes and Euler Equations", *Journal of Computational Physics*, Volume 119, Issue 2, July 1995, Pages 295-324. `doi: 10.1006/jcph.1995.1137 `_ - Xiao-Yen Wang, Sin-Chung Chang, "A 2D Non-Splitting Unstructured Triangular Mesh Euler Solver Based on the Space-Time Conservation Element and Solution Element Method", *Computational Fluid Dynamics Journal*, Volume 8, Issue 2, 1999, Pages 309-325. - Zeng-Chan Zhang, S. T. John Yu, Sin-Chung Chang, "A Space-Time Conservation Element and Solution Element Method for Solving the Two- and Three-Dimensional Unsteady Euler Equations Using Quadrilateral and Hexahedral Meshes", *Journal of Computational Physics*, Volume 175, Issue 1, Jan. 2002, Pages 168-199. `doi: 10.1006/jcph.2001.6934 `_ - :doc:`link` - :doc:`link_other` Bibliography ============ .. [Lax73] Peter D. Lax, *Hyperbolic Systems of Conservation Laws and the Mathematical Theory of Shock Waves*, Society for Industrial Mathematics, 1973. `ISBN 0898711770 `__. Appendices ========== Copyright Notice ++++++++++++++++ .. include:: ../../COPYING Release History +++++++++++++++ .. toctree:: :maxdepth: 2 history Indices and Tables ++++++++++++++++++ * :ref:`genindex` * :ref:`modindex` * :ref:`search` .. vim: set spell ft=rst ff=unix fenc=utf8: