Skip to content
Permalink
Browse files

Merge pull request #126 from mlwright84/sphinxdoc

Added documentation with Sphinx and reStructuredText. The documentation is in a good state -- certainly better than the old documentation -- but there is still more work to be done.
  • Loading branch information...
mlwright84 committed Aug 11, 2018
2 parents 4639dc9 + 3a863d4 commit 94b0cf855578e7a3283f17a2f14552df79b86526
@@ -28,3 +28,4 @@ cmake-build-*
msgpack
RIVET.pro.user
moc_predefs.h
docs/_build
206 README.md
@@ -2,209 +2,7 @@

Program for the visualization and analysis of two-parameter persistent homology.

## Project Founders
Michael Lesnick
Matthew Wright
For documentation, see the <a href="http://rivet.online/" target="_blank" rel="noopener">RIVET Website</a>.
## Contributors
Madkour Abdel-Rahman
Bryn Keller
Phil Nadolny
Simon Segert
Alex Yu
Roy Zhao
RIVET is made available under the under the terms of the GNU General Public License, available <a href="https://www.gnu.org/licenses/gpl-3.0.en.html" target="_blank" rel="noopener">here</a>. The software is provided "as is," without warranty of any kind, even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for details.
## Dependencies
RIVET depends on the <a href="https://www.qt.io/" target="_blank" rel="noopener">qt,</a> <a href="http://www.boost.org/" target="_blank" rel="noopener">Boost</a>, and <a href="https://msgpack.org/index.html" target="_blank">MessagePack</a> libraries. In addition, RIVET now incorporates some code from <a href="https://bitbucket.org/phat-code/phat/src/master/" target="_blank">PHAT</a>.
## Requirements
Before starting to build RIVET, you will need to have the following installed:
* A C++ compiler (g++ or clang are what we use)
* CMake
* Qt 5
* Boost (version 1.58 or newer)
Below we give step-by-step instructions for installing these required dependencies and building RIVET on Ubuntu and Mac OS X. Building RIVET on Windows is not yet supported (we are working on this), but it is possible to build RIVET using the Bash shell on Windows 10.
## Building On Ubuntu
### Installing Dependencies
On Ubuntu, installation of dependencies should be relatively simple:
sudo apt-get install cmake qt5-default qt5-qmake qtbase5-dev-tools libboost-all-dev
### Building RIVET
After <a href="https://help.github.com/articles/cloning-a-repository/" target="_blank">cloning</a> to $RIVET_DIR:
cd $RIVET_DIR
mkdir build
cd build
cmake ..
make
cd ..
qmake
make
You may see compiler warnings during either of the `make` executions.
These can safely be ignored.
After this, you will have two executables built: the viewer (RIVET),
and the computation engine (rivet_console).
It is then necessary to move or symlink the console into the same folder
where the viewer was built. On Ubuntu and most other systems:
ln -s build/rivet_console
In the future, all these steps will be automated so that a single cmake build will create both executables, and put everything in the right place.
## Building On Mac OS X
### Installing Dependencies
First, ensure you have the XCode Command Line Tools installed by running:
# only needed if you've never run it before, (running it again doesn't hurt anything)
# installs XCode Command Line Tools
xcode-select --install
If a popup window appears, click the "Install" button, and accept the license agreement.
Next, install XCode from the App Store, if you've not done so already. You will also need accept the license agreement for XCode, which you can do from the command line by running:
sudo xcodebuild -license
To install the remaining packages, we recommend using the package manager [Homebrew](http://brew.sh/). To install Homebrew:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Now install cmake, qt5, and boost:
brew install cmake qt5 boost
Please note that, as of the time of writing, brew installs `qmake` in a version-specific folder under
/usr/local/Cellar/qt5/[my_version_#]/bin, and does not add it to your `PATH`. You can find
the folder where qt5 is installed using this command:

brew info qt5 | grep Cellar | cut -d' ' -f1

In fact, let's store that in a variable so we can use it below:

export QT_BASE=`brew info qt5 | grep Cellar | cut -d' ' -f1`

Finally, in order to ensure that qmake can find where boost is installed, add the following lines to the bottom of the file RIVET.pro, changing the paths in the last three lines, if necessary, to match the location and version of your copy of Boost.

CONFIG += c++11
QMAKE_CFLAGS += -std=c++11 -stdlib=libc++ -mmacosx-version-min=10.9
QMAKE_CXXFLAGS += -std=c++11 -stdlib=libc++ -mmacosx-version-min=10.9

LIBS += -L"/usr/local/Cellar/boost/1.63.0/lib"
INCLUDEPATH += "/usr/local/Cellar/boost/1.63.0/include"

LIBS += -L"/usr/local/Cellar/boost/1.63.0/lib" -lboost_random

### Building RIVET
After <a href="https://help.github.com/articles/cloning-a-repository/" target="_blank">cloning</a> to $RIVET_DIR:
cd $RIVET_DIR
mkdir build
cd build
cmake ..
make
cd ..
$QT_BASE/bin/qmake
make
You may see compiler warnings during either of the `make` executions.
These can safely be ignored.
After this, you will have two executables built: the viewer (RIVET.app),
and the computation engine (rivet_console).
It is then necessary to move or symlink the console into the same folder where the viewer was built:
cd RIVET.app/Contents/MacOS
ln -s ../../../build/rivet_console
In the future, all these steps will be automated so that a single cmake build will create both executables, and put everything in the right place.
### Troubleshooting
Our experience has been that if Homebrew is installed before XCode, then running qmake during the build process returns an error:
Project ERROR: Could not resolve SDK Path for 'macosx'
To solve the problem, try running:
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
## Building in the Bash Shell on Windows 10
First, ensure that you have the [Windows 10 Creators Update](https://support.microsoft.com/en-us/instantanswers/d4efb316-79f0-1aa1-9ef3-dcada78f3fa0/get-the-windows-10-creators-update). Then activate the [Windows 10 Bash Shell](https://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/). This will provide a Bash shell with Ubuntu 16.04 inside of Windows 10.
Open the Bash shell and install dependencies. Use the following command to install cmake, a compiler, and Qt5:
sudo apt-get install cmake build-essential qt5-default qt5-qmake qtbase5-dev-tools
The Ubuntu 16.04 repositories include Boost 1.58, but RIVET requires Boost 1.60 or newer. The following instructions install Boost 1.64 into `/usr/local/boost_1_64_0/`:
1. Download a compressed Boost file into your home directory:
cd ~
wget "https://dl.bintray.com/boostorg/release/1.64.0/source/boost_1_64_0.tar.bz2"
2. Unpack Boost to `/usr/local/`:
cd /usr/local
sudo tar xvjf ~/boost_1_64_0.tar.bz2
cd boost_1_64_0
3. Setup Boost:
sudo ./boostrap.sh --prefix=/usr/local
sudo ./b2
sudo ./b2 install
4. Return to home directory and delete the compressed Boost file.
cd ~
rm boost_1_64_0.tar.bz2
In order to use the RIVET viewer, you must install an X server such as [Xming](https://sourceforge.net/projects/xming/).
It is also necessary to set two environment variables, as follows:
export LD_LIBRARY_PATH=/usr/local/boost_1_64_0/stage/lib/:$LD_LIBRARY_PATH
export DISPLAY=:0
These environment variables will be reset when you close the Bash shell. To avoid having to run the two lines above when you reopen the shell, add these lines to the end of the file `~/.bashrc`.
You are now ready to build RIVET. Follow the instructions in the section of this readme under the heading [Building on Ubuntu: Building RIVET](https://github.com/rivetTDA/rivet/#building-rivet).
## Using RIVET
Information on how to use RIVET can be found on the <a href="http://rivet.online" target="_blank">RIVET website</a>.
TODO: Merge the documentation on the website and the content of this readme into a single document.
## Contributing
We welcome your contribution! Code, documentation, unit tests,
interesting sample data files are all welcome!
Before submitting your branch for review, please run the following from the
top level RIVET folder you cloned from Github:
```
clang-format -i **/*.cpp **/*.h
```
This will format the source code using the project's established source
code standards (these are captured in the `.clang-format` file in the
project root directory).
## Acknowledgements
This material is based upon work supported by the National Science Foundation under Grant Number 1606967. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.
Additional support has been been provided by the Institute for Mathematics and its Applications, Columbia University, Princeton University, St. Olaf College, and the NIH (grant U54-CA193313-01).
@@ -14,7 +14,7 @@ CONFIG += c++11 debug
QT += core gui \
widgets

TARGET = RIVET
TARGET = rivet_GUI
TEMPLATE = app

QMAKE_LIBDIR += /usr/local/lib #TODO: figure out how to generalize
@@ -36,7 +36,7 @@ std::unique_ptr<ComputationResult> from_istream(std::istream &file) {
m3.convert(arrangementMessage);

} else {
throw std::runtime_error("Expected a precomputed RIVET file");
throw std::runtime_error("Expected a RIVET module invariants file");
}
return from_messages(templatePointsMessage, arrangementMessage);
}
@@ -67,7 +67,7 @@ void ComputationThread::run()

bool ComputationThread::is_precomputed(const std::string &file_name)
{
std::cerr << "Checking if precomputed" << std::endl;
std::cerr << "Checking for a module invariants file" << std::endl;
std::ifstream file(file_name);
if (!file.is_open()) {
throw std::runtime_error("Couldn't open " + file_name + " for reading");
@@ -46,14 +46,14 @@ static const char USAGE[] =
rivet_console <input_file> --identify
rivet_console <input_file> --minpres [-H <dimension>] [-V <verbosity>] [-x <xbins>] [-y <ybins>] [--koszul]
rivet_console <input_file> [output_file] --betti [-H <dimension>] [-V <verbosity>] [-x <xbins>] [-y <ybins>] [--koszul]
rivet_console <precomputed_file> --bounds [-V <verbosity>]
rivet_console <precomputed_file> --barcodes <line_file> [-V <verbosity>]
rivet_console <module_invariants_file> --bounds [-V <verbosity>]
rivet_console <module_invariants_file> --barcodes <line_file> [-V <verbosity>]
rivet_console <input_file> <output_file> [-H <dimension>] [-V <verbosity>] [-x <xbins>] [-y <ybins>] [-f <format>] [--binary] [--koszul]
Options:
<input_file> A text file with suitably formatted point cloud, bifiltration, or
finite metric space as described at http://rivet.online/doc/input-data/
<precomputed_file> A precomputed RIVET file, as generated by this program by processing an
<module_invariants_file> A module invariants file, as generated by this program by processing an
<input_file>
-h --help Show this screen
--version Show the version
@@ -67,7 +67,7 @@ static const char USAGE[] =
--minpres Print the minimal presentation, then exit.
-b --betti Print dimension and Betti number information. Optionally, also save this info
to a file in a binary format for later viewing in the visualizer. Then exit.
--bounds Print lower and upper bounds for the module in <precomputed_file> and exit
--bounds Print lower and upper bounds for the module in <module_invariants_file> and exit
-k --koszul Use koszul homology-based algorithm to compute Betti numbers, instead of
an approach based on computing presentations.
--barcodes <line_file> Print barcodes for the line queries in line_file, then exit.
@@ -266,11 +266,11 @@ int main(int argc, char* argv[])

if (args["<input_file>"].isString()) {
params.fileName = args["<input_file>"].asString();
} else if (args["<precomputed_file>"].isString()) {
params.fileName = args["<precomputed_file>"].asString();
} else if (args["<module_invariants_file>"].isString()) {
params.fileName = args["<module_invariants_file>"].asString();
} else {
//This should never happen if docopt is doing its job and the docstring is written correctly
throw std::runtime_error("Either <input_file> or <precomputed_file> must be supplied");
throw std::runtime_error("Either <input_file> or <module_invariants_file> must be supplied");
}
docopt::value& out_file_name = args["<output_file>"];
if (out_file_name.isString()) {
@@ -419,7 +419,7 @@ int main(int argc, char* argv[])

if (barcodes || bounds) {
if (content.type != FileContentType::PRECOMPUTED) {
input_error("This function requires a precomputed RIVET file as input");
input_error("This function requires a RIVET module invariants file as input.");
return 1;
}
if (barcodes) {
@@ -431,7 +431,7 @@ int main(int argc, char* argv[])
}
} else {
if (content.type != FileContentType::DATA) {
input_error("This function requires a data file, not a precomputed RIVET file");
input_error("This function requires a data file, not a RIVET module invariants file.");
return 1;
}
content.result = computation.compute(*content.input_data, koszul);

0 comments on commit 94b0cf8

Please sign in to comment.
You can’t perform that action at this time.