add about, compiling, docker, and singularity

docs/about.md

@@ -0,0 +1,65 @@
+---
+layout: about
+title: About
+permalink: /
+---
+
+# MOFid
+{: .no_toc }
+
+A system for rapid identification and analysis of metal-organic frameworks.
+
+Please cite [DOI: 10.1021/acs.cgd.9b01050](https://pubs.acs.org/doi/abs/10.1021/acs.cgd.9b01050) if you use MOFid in your work.
+
+
+## Table of Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+## Objective
+
+Supplement the current MOF naming conventions with a canonical, machine-readable identifier to facilitate data mining and searches. Accomplish this goal by representing MOFs according to their nodes and linkers and topology.
+
+## Usage and Installation Instructions
+
+There are three main ways in which you can use MOFid.
+1. From your browser.
+2. By compiling the MOFid source code and running it locally.
+3. By using Singularity or Docker to run a pre-built image of the MOFid code locally.
+
+### Browser-based MOFid
+
+Visit [Web MOFid](https://snurr-group.github.io/web-mofid/) to quickly and easily run MOFid in your browser! No programming skills are required.
+
+### Compiling from Source
+
+See [Compiling]({{site.baseurl}}/compiling) for how to compile and run MOFid from source.
+
+### Containerized MOFid
+
+See [Singularity]({{site.baseurl}}/singularity) for how to run MOFid via a Singularity container.
+
+## Background and Troubleshooting
+
+Please read [this page](https://github.com/snurr-group/web-mofid/blob/master/README.md) for a detailed background and for important tips and tricks in troubleshooting problematic scenarios.
+## Credits
+
+This work is supported by the U.S. Department of Energy, Office of Basic Energy Sciences, Division of Chemical Sciences, Geosciences and Biosciences through the Nanoporous Materials Genome Center under award DE-FG02-17ER16362.
+
+The MOFid command line and web tools are built on top of other open-source software projects.
+
+* [Open Babel](https://github.com/openbabel/openbabel) cheminformatics toolkit
+* [Eigen](https://eigen.tuxfamily.org/index.php?title=Main_Page) as a dependency for Open Babel
+* [GoogleTest](https://github.com/google/googletest) C++ testing framework
+* [Make](https://www.gnu.org/software/make/), [CMake](https://cmake.org/), [Node.js](https://nodejs.org/en), and [Emscripten](https://emscripten.org/) for build infrastructure
+* [Systre](http://www.gavrog.org/) and [webGavrog](https://github.com/odf/webGavrog) to analyze crystal graph data and assign [RCSR topology symbols](https://rcsr.anu.edu.au/) for MOFs
+* [NGL Viewer](https://github.com/nglviewer/ngl) to visualize MOF structures and components on the website
+* [Kekule.js](https://partridgejiang.github.io/Kekule.js/) to draw molecule substructure queries in the SearchDB web tool
+
+You can find the source code for Jekyll at GitHub:
+[jekyll][jekyll-organization] /
+[jekyll](https://github.com/jekyll/jekyll)
+
+[jekyll-organization]: https://github.com/jekyll

docs/compiling.md

@@ -0,0 +1,32 @@
+---
+layout: default
+title: Compiling
+permalink: /compiling/
+---
+
+# Compiling
+{: .no_toc}
+
+## Table of Contents
+{: .no_toc .text-delta}
+
+1. TOC
+{:toc}
+
+## Requirements
+1. A Python environment is required. If you do not have a Python environment installed, we recommend downloading and installing [Anaconda](https://www.anaconda.com/distribution/#download-section). MOFid is compatible with Python 3.
+2. Make sure you have the following: a C++ compiler (the latest version of [GCC 10](https://gcc.gnu.org/gcc-10/) is recommended), [CMake](https://cmake.org/), and [GNU Make](https://www.gnu.org/software/make/). If running on Windows, we recommend using [Cygwin](https://www.cygwin.com/) and including the `cmake`, `make`, `wget`, `gcc-core`, `gcc-g++`, and `pkg-config` packages in addition to the default options during the installation process.
+3. Make sure you have the [Java Runtime Environment](https://www.java.com/en/download/) installed and included in your system's path. If unsure, try running `java` in the command line to see if it successfully calls Java.
+
+## Installation
+1. Run `make init` in the base `mofid` directory.
+2. Run `python set_paths.py` followed by `pip install .` in the base `mofid` directory.  If you encounter permissions errors (typically not with Anaconda), try running `pip install --user .`
+
+## Usage
+In a Python script, the user simply has to call the `run_mofid.cif2mofid(cif_path, output_path="Output")` function. The first argument is required and is the path to the MOF file. The second argument is optional and is the directory to store the MOFid decomposition information, which defaults to `Output` if not specified. An example of how to call MOFid is shown below.
+```python
+from mofid.run_mofid import cif2mofid
+cif_path = "/path/to/my/mof.cif"
+mofid = cif2mofid(cif_path)
+```
+The output of the `mofid.cif2mofid` function is a dictionary containing eight entries: the MOFid (`mofid`), MOFkey (`mofkey`), SMILES string (`smiles`, `smiles_nodes`, or `smiles_linkers`), topology (`topology`), catenation (`cat`), and basename of the CIF (`cifname`).

docs/docker.md

@@ -0,0 +1,54 @@
+---
+layout: default
+title: Docker
+permalink: /docker/
+---
+
+# Docker
+{: .no_toc}
+
+## Table of Contents
+{: .no_toc .text-delta}
+
+1. TOC
+{:toc}
+
+## Installation
+
+Installation instructions for [Docker](https://www.docker.com/) are beyond the scope of this document. Two potentially helpful links for Linux include the [installation](https://docs.docker.com/engine/install/ubuntu/) and [configuration](https://docs.docker.com/engine/security/rootless/) pages.
+
+
+1. Once Docker is set up, clone the MOFid repository.
+2. Build the container by running `docker build -t mofid path_to_mofid_repo`
+
+## Usage
+
+To start a shell within the Docker container, run `docker run -it mofid /bin/bash`
+
+To analyze a single MOF crystal structure...
+
+```bash
+# Configure paths in the first two lines, then run this block
+MOFID_IN_FILENAME="P1-Cu-BTC.cif"
+MOFID_IN_DIR="$PWD" # absolute path to parent directory, e.g. current directory via $PWD
+
+docker run \
+    --mount type=bind,source="$MOFID_IN_DIR",target="$MOFID_IN_DIR",readonly \
+    mofid \
+    python /mofid/Python/run_mofid.py "$MOFID_IN_DIR/$MOFID_IN_FILENAME" /mofid/TempOutput json
+```
+
+or to analyze an entire folder...
+
+```bash
+# Configure the paths in the first two lines, then run this block
+MOFID_IN_DIR="$PWD/Resources/TestCIFs"
+MOFID_OUT_DIR="$PWD/mofid_output"
+
+mkdir -p "$MOFID_OUT_DIR"
+docker run \
+    --mount type=bind,source="$MOFID_IN_DIR",target=/data,readonly \
+    --mount type=bind,source="$MOFID_OUT_DIR",target=/out \
+    mofid \
+    Scripts/run_folder.sh /data /out
+```

docs/singularity.md

@@ -0,0 +1,54 @@
+---
+layout: default
+title: Singularity
+permalink: /singularity/
+---
+
+# Singularity
+{: .no_toc}
+
+## Table of Contents
+{: .no_toc .text-delta}
+
+1. TOC
+{:toc}
+
+## Installation
+If you have access to a Linux machine or HPC cluster, it may be possible to run MOFid via [Singularity](https://apptainer.org/user-docs/master/quick_start.html), which packages the MOFid installer into a portable and reproducible environment. To get started, refer to documentation from your university or computing center ([example](https://kb.northwestern.edu/page.php?id=85614)) for help on singularity. There may be setup instructions specific to your compute environment. E.g. you may need to load modules or bind paths to set up Singularity.
+
+1. Download the pre-compiled Singularity container `mofid.sif` from the [most recent release](https://github.com/snurr-group/mofid/releases).
+2. Test your installation using `singularity test mofid.sif`. Your installation is successful if you receive the message `Results: 0 errors in 28 MOFs`.
+
+Alternatively, if you wish to use Docker see [docker.md](docker.md).
+
+## Usage
+The Singularity container wraps all of MOFid into a single package.
+
+As a command line tool...
+
+```bash
+# Analyzing a single MOF crystal structure
+./mofid.sif file path_to_mof.cif
+# alternatively: singularity run mofid.sif file path_to_mof.cif
+
+# Analyzing a folder
+./mofid.sif folder path_to_input_cif_folder path_to_mofid_output
+# By default, path_to_mofid_output is set to "Output/" in your current directory
+```
+
+or as part of a Python script...
+
+```python
+import json
+import sys
+import subprocess
+
+MOFID_SIF = "path_to_mofid.sif"
+MOF_CIF_TO_ANALYZE = "path_to_mof.cif"
+mofid_cmd = ["singularity", "run", MOFID_SIF, "file", MOF_CIF_TO_ANALYZE]
+mofid_run = subprocess.run(mofid_cmd, universal_newlines=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+sys.stderr.write(mofid_run.stderr)  # Re-forwarding C++ errors
+mofid_output = json.loads(mofid_run.stdout)
+```
+
+The `mofid_output` variable above is a dictionary containing eight entries: the MOFid (`mofid`), MOFkey (`mofkey`), SMILES string (`smiles`, `smiles_nodes`, or `smiles_linkers`), topology (`topology`), catenation (`cat`), and basename of the CIF (`cifname`).