<commit_before>###########
Cyclus Core
###########

The core of the Cyclus nuclear fuel cycle simulator from the 
University of Wisconsin - Madison is intended to be a simulation 
framework upon which to develop innovative fuel cycle simulations. 

To see user and developer documentation for this code, please visit 
the `Cyclus Homepage`_.

*******
LICENSE
*******
::

    Copyright (c) 2010-2012, University of Wisconsin Computational Nuclear Engineering Research Group
     All rights reserved.
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
    
      - Redistributions of source code must retain the above copyright notice,
        this list of conditions and the following disclaimer.
      
      - Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
      
      - Neither the name of the University of Wisconsin Computational
        Nuclear Engineering Research Group nor the names of its
        contributors may be used to endorse or promote products derived
        from this software without specific prior written permission.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.

******************************
Building and Installing Cyclus
******************************

In order to facilitate future compatibility with multiple platforms, 
Cyclus is built using `CMake`_. A full list of the Cyclus package 
dependencies is show below:

====================   ==================
Package                Minimum Version   
====================   ==================
`CMake`                2.8            
`boost`                1.34.1
`libxml2`              2
`sqlite3`              3.7.10            
`Cyclopts`             0.1            
====================   ==================

As with all software, the build/install can be broken into two steps:

  #. building and installing the dependencies
  #. building and installing Cyclus

Installing Dependencies
=======================

This guide assumes that the user has root access (to issue sudo 
commands) and access to a package manager or has some other suitable 
method of automatically installing established libraries. This process
was tested using a fresh install of Ubuntu 12.10. 

Cyclopts
--------

Cyclopts is an optimization wrapper library used by Cyclus and is
part of the general Cyclus software suite. Detailed build/install
instructions are provided in the `Cyclopts readme`_. We assume that the 
user has successfully built and installed Cyclopts (and CMake) for 
the following discussion. 

All Others
----------

All other dependencies are common libraries available through package
managers. We provide an example using `apt-get`_. All required 
commands will take the form of:

.. code-block:: bash

  sudo apt-get install package

Where you will replace "package" with the correct package name. The
list of required package names are:

  #. libboost-all-dev
  #. libxml++2.6-dev
  #. libsqlite3-dev

So, for example, in order to install libxml++ on your system, you will
type:

.. code-block:: bash

  sudo apt-get install libxml++2.6-dev

Let us take a moment to note the Boost library dependency. As it 
currently stands, we in fact depend on a small subset of the Boost 
libraries:

  #. libboost-program-options-dev
  #. libboost-system-dev
  #. libboost-filesystem-dev

However, it is possible (likely) that additional Boost libraries will
be used because they are an industry standard. Accordingly, we suggest
simply installing libboost-all-dev to limit any headaches due to 
possible dependency additions in the future.

Installing Cyclus
=================

Assuming you have the dependencies installed correctly, it's pretty
straightforward to install Cyclus. We make the following assumptions
in this guide:

  #. there is some master directory in which you're placing all
     Cyclus-related files called .../cyclus
  #. you have a directory named .../cyclus/install in which you plan
     to install all Cyclus-related files
  #. you have acquired the Cyclus source code from the `Cyclus repo`_
  #. you have placed the Cyclus repository in .../cyclus/cyclus
  #. you have a directory named .../cyclus/cyclus/build in which 
     you plan to encapsulate all build-related files (they get in the
     way otherwise)
  #. you have installed Cyclopts using the CMAKE_INSTALL_PREFIX 
     variable set to ../cyclus/install (see the `Cyclopts readme`_)

Under these assumptions **and** if you used a package manager to 
install coin-Cbc (i.e. it's installed in a standard location), the
Cyclus building and installation process will look like:

.. code-block:: bash

    .../cyclus/cyclus$ cd build
    .../cyclus/cyclus/build$ cmake ../src -DCMAKE_INSTALL_PREFIX=../../install -DCYCLOPTS_ROOT_DIR=../../install
    .../cyclus/cyclus/build$ make && make install

If you have installed coin-Cbc from source or otherwise have it 
installed in a non-standard location, you should make use of the CMake
COIN_ROOT_DIR variable. The otherwise identical process would look 
like:

.. code-block:: bash

    .../cyclus/cyclus$ cd build
    .../cyclus/cyclus/build$ cmake ../src -DCMAKE_INSTALL_PREFIX=../../install -DCYCLOPTS_ROOT_DIR=../../install -DCOIN_ROOT_DIR=/the/path/to/coin/install
    .../cyclus/cyclus/build$ make && make install

Now, run it with some input file, for this example, call it 
`input.xml`::

    .../cyclus/install/cyclus/bin$ ./cyclus input.xml

Debugging Build
^^^^^^^^^^^^^^^

Building the debug version of the core library requires an additional
CMake variable flag. Simply add the following to your cmake command:
::

  -DCMAKE_BUILD_TYPE:STRING=Debug

.. _`Cyclus Homepage`: http://cyclus.github.com
.. _`CMake`: http://www.cmake.org
.. _`apt-get`: http://linux.die.net/man/8/apt-get
.. _`Cyclopts readme`: https://github.com/cyclus/cyclopts
.. _`Cyclus repo`: https://github.com/cyclus/cyclus

**********************
The Developer Workflow
**********************

*Note that "blessed" repository refers to the primary `cyclus/core` repository.*

As you do your development, push primarily only to your own fork. Make a pull 
request to the blessed repository (usually the "develop" branch) only after:

  * You have pulled the latest changes from the blessed repository.
  * You have completed a logical set of changes.
  * Cyclus compiles with no errors.
  * All tests pass.
  * Cyclus input files run as expected.
  * (recommended) your code has been reviewed by another developer.

Code from the "develop" branch generally must pass even more rigorous checks<commit_msg>fixes readme?<commit_after>###########
Cyclus Core
###########

The core of the Cyclus nuclear fuel cycle simulator from the 
University of Wisconsin - Madison is intended to be a simulation 
framework upon which to develop innovative fuel cycle simulations. 

To see user and developer documentation for this code, please visit 
the `Cyclus Homepage`_.

*******
LICENSE
*******
::

    Copyright (c) 2010-2012, University of Wisconsin Computational Nuclear Engineering Research Group
     All rights reserved.
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
    
      - Redistributions of source code must retain the above copyright notice,
        this list of conditions and the following disclaimer.
      
      - Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
      
      - Neither the name of the University of Wisconsin Computational
        Nuclear Engineering Research Group nor the names of its
        contributors may be used to endorse or promote products derived
        from this software without specific prior written permission.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGE.

******************************
Building and Installing Cyclus
******************************

In order to facilitate future compatibility with multiple platforms, 
Cyclus is built using `CMake`_. A full list of the Cyclus package 
dependencies is show below:

====================   ==================
Package                Minimum Version   
====================   ==================
`CMake`                2.8            
`boost`                1.34.1
`libxml2`              2
`sqlite3`              3.7.10            
`Cyclopts`             0.1            
====================   ==================

As with all software, the build/install can be broken into two steps:

  #. building and installing the dependencies
  #. building and installing Cyclus

Installing Dependencies
=======================

This guide assumes that the user has root access (to issue sudo 
commands) and access to a package manager or has some other suitable 
method of automatically installing established libraries. This process
was tested using a fresh install of Ubuntu 12.10. 

Cyclopts
--------

Cyclopts is an optimization wrapper library used by Cyclus and is
part of the general Cyclus software suite. Detailed build/install
instructions are provided in the `Cyclopts readme`_. We assume that the 
user has successfully built and installed Cyclopts (and CMake) for 
the following discussion. 

All Others
----------

All other dependencies are common libraries available through package
managers. We provide an example using `apt-get`_. All required 
commands will take the form of:

.. code-block:: bash

  sudo apt-get install package

Where you will replace "package" with the correct package name. The
list of required package names are:

  #. libboost-all-dev
  #. libxml++2.6-dev
  #. libsqlite3-dev

So, for example, in order to install libxml++ on your system, you will
type:

.. code-block:: bash

  sudo apt-get install libxml++2.6-dev

Let us take a moment to note the Boost library dependency. As it 
currently stands, we in fact depend on a small subset of the Boost 
libraries:

  #. libboost-program-options-dev
  #. libboost-system-dev
  #. libboost-filesystem-dev

However, it is possible (likely) that additional Boost libraries will
be used because they are an industry standard. Accordingly, we suggest
simply installing libboost-all-dev to limit any headaches due to 
possible dependency additions in the future.

Installing Cyclus
=================

Assuming you have the dependencies installed correctly, it's pretty
straightforward to install Cyclus. We make the following assumptions
in this guide:

  #. there is some master directory in which you're placing all
     Cyclus-related files called .../cyclus
  #. you have a directory named .../cyclus/install in which you plan
     to install all Cyclus-related files
  #. you have acquired the Cyclus source code from the `Cyclus repo`_
  #. you have placed the Cyclus repository in .../cyclus/cyclus
  #. you have a directory named .../cyclus/cyclus/build in which 
     you plan to encapsulate all build-related files (they get in the
     way otherwise)
  #. you have installed Cyclopts using the CMAKE_INSTALL_PREFIX 
     variable set to ../cyclus/install (see the `Cyclopts readme`_)

Under these assumptions **and** if you used a package manager to 
install coin-Cbc (i.e. it's installed in a standard location), the
Cyclus building and installation process will look like:

.. code-block:: bash

    .../cyclus/cyclus$ cd build
    .../cyclus/cyclus/build$ cmake ../src -DCMAKE_INSTALL_PREFIX=../../install -DCYCLOPTS_ROOT_DIR=../../install
    .../cyclus/cyclus/build$ make && make install

If you have installed coin-Cbc from source or otherwise have it 
installed in a non-standard location, you should make use of the CMake
COIN_ROOT_DIR variable. The otherwise identical process would look 
like:

.. code-block:: bash

    .../cyclus/cyclus$ cd build
    .../cyclus/cyclus/build$ cmake ../src -DCMAKE_INSTALL_PREFIX=../../install -DCYCLOPTS_ROOT_DIR=../../install -DCOIN_ROOT_DIR=/the/path/to/coin/install
    .../cyclus/cyclus/build$ make && make install

Now, run it with some input file, for this example, call it 
`input.xml`::

    .../cyclus/install/cyclus/bin$ ./cyclus input.xml

Debugging Build
---------------

Building the debug version of the core library requires an additional
CMake variable flag. Simply add the following to your cmake command:
::

  -DCMAKE_BUILD_TYPE:STRING=Debug

.. _`Cyclus Homepage`: http://cyclus.github.com
.. _`CMake`: http://www.cmake.org
.. _`apt-get`: http://linux.die.net/man/8/apt-get
.. _`Cyclopts readme`: https://github.com/cyclus/cyclopts
.. _`Cyclus repo`: https://github.com/cyclus/cyclus

**********************
The Developer Workflow
**********************

*Note that "blessed" repository refers to the primary `cyclus/core` repository.*

As you do your development, push primarily only to your own fork. Make a pull 
request to the blessed repository (usually the "develop" branch) only after:

  * You have pulled the latest changes from the blessed repository.
  * You have completed a logical set of changes.
  * Cyclus compiles with no errors.
  * All tests pass.
  * Cyclus input files run as expected.
  * (recommended) your code has been reviewed by another developer.

Code from the "develop" branch generally must pass even more rigorous checks
{'fraction_non_alphanumeric': 0.10277703959606697, 'fraction_numerical': 0.004384799362211002, 'mean_word_length': 3.4496009459060004, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 12}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4953236', 'n_tokens_mistral': 4045, 'n_tokens_neox': 3714, 'n_words': 1826}