Skip to content

Commit f94d0f9

Browse files
Andrew-S-RosenAndrew-S-Rosen
authored
Updated README (#29)
1 parent 86d8bbd commit f94d0f9

File tree

5 files changed

+111
-158
lines changed

5 files changed

+111
-158
lines changed

‎README.md

Lines changed: 11 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,25 @@
11
# MOFid
22
A system for rapid identification and analysis of metal-organic frameworks.
33

4-
Check out [https://snurr-group.github.io/web-mofid/](https://snurr-group.github.io/web-mofid/) to quickly and easily run these tools in your browser! No programming skills required. If you wish to generate the MOFid for a large number of structures, see the Python-based interface described below.
5-
64
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.
75

86
## Objective
97
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 + linkers + topology
108

11-
## Installation
12-
If you have access to a Linux system or high performance computing cluster, it may be possible to run the MOFid code via [singularity](https://apptainer.org/user-docs/master/quick_start.html), which packages the mofid installer into a portable, 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. (For example, you may need to load modules or bind paths to set up singularity.)
13-
14-
1. Set up singularity and test your installation, e.g. `singularity exec library://ubuntu cat /etc/lsb-release`
15-
2. Download the pre-compiled singularity container from GitHub, e.g. via `wget -O mofid.sif https://github.com/snurr-group/mofid/releases/download/v1.1.0/mofid.sif`
16-
3. Test your installation using `singularity test mofid.sif`
17-
18-
See [additional details](https://github.com/snurr-group/mofid/blob/master/containers.md) about alternate installation methods, such as using [Docker](https://www.docker.com/resources/what-container) or compiling the Python package yourself.
19-
20-
## Usage
21-
The singularity container wraps all of the MOFid software into a single package.
22-
23-
As a command line tool:
24-
25-
```{bash}
26-
# Analyzing a single MOF crystal structure
27-
./mofid.sif file path_to_mof.cif
28-
# alternatively: singularity run mofid.sif file path_to_mof.cif
29-
30-
# Analyzing a folder
31-
./mofid.sif folder path_to_input_cif_folder path_to_mofid_output
32-
# By default, path_to_mofid_output is set to "Output/" in your current directory
33-
```
34-
35-
Or, as part of a Python script:
36-
37-
```{python}
38-
import json
39-
import sys
9+
## Usage and Installation Instructions
10+
There are three main ways in which you can use MOFid:
11+
1. From your browser.
12+
2. By compiling the MOFid source code and running it locally.
13+
3. By using Singularity or Docker to run a pre-built image of the MOFid code locally.
4014

41-
import subprocess
42-
# If using Python 2, you may need to install subprocess32 and import via:
43-
# import subprocess32 as subprocess
15+
### Browser-Based MOFid
16+
Visit [https://snurr-group.github.io/web-mofid](https://snurr-group.github.io/web-mofid/) to quickly and easily run MOFid in your browser! No programming skills are required.
4417

45-
MOFID_SIF = "path_to_mofid.sif"
46-
MOF_CIF_TO_ANALYZE = "path_to_mof.cif"
47-
mofid_cmd = ["singularity", "run", MOFID_SIF, "file", MOF_CIF_TO_ANALYZE]
48-
mofid_run = subprocess.run(mofid_cmd, universal_newlines=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
49-
sys.stderr.write(mofid_run.stderr) # Re-forwarding C++ errors
50-
mofid_output = json.loads(mofid_run.stdout)
51-
```
18+
### Compiling from Source
19+
See [compiling.md](compiling.md) for how to compile and run MOFid from source.
5220

53-
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`).
21+
### Containerized MOFid
22+
See [singularity.md](singularity.md) for how to run MOFid via a Singularity container.
5423

5524
## Background and Troubleshooting
5625
Please read the page [here](https://github.com/snurr-group/web-mofid/blob/master/README.md) for a detailed background and for important tips/tricks to help troubleshoot any problematic scenarios.

‎compiling.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
## Requirements
2+
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 both Python 2/3.
3+
2. Make sure you have the following: a C++ compiler, [`cmake`](https://cmake.org/), and access to GNU commands (such as `make`). These are all typically available on Linux machines. 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 Cygwin installation process.
4+
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.
5+
6+
## Installation
7+
1. Run `make init` in the base `/mofid` directory.
8+
2. Run `python set_paths.py` followed by `pip install .` in the base `/mofid` directory. If you encounter permissions errors (typically not with Anaconda), you may need to run `pip install --user .`
9+
10+
## Usage
11+
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 CIF. 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.
12+
```python
13+
from mofid.run_mofid import cif2mofid
14+
cif_path = '/path/to/my/mof.cif'
15+
mofid = cif2mofid(cif_path)
16+
```
17+
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`).

‎containers.md

Lines changed: 0 additions & 116 deletions
This file was deleted.

‎docker.md

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
## Docker
2+
3+
The initial containerization experiments for MOFid used [Docker](https://www.docker.com/resources/what-container). Installation instructions for Docker are highly system-dependent and beyond the scope of this document. For example, Windows users may need to set up WSL2 or VirtualBox. 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/) docs.
4+
5+
### Installation
6+
7+
1. Once Docker is set up, clone the MOFid repository.
8+
2. Build the container by running `docker build -t mofid path_to_mofid_repo`
9+
10+
### Usage
11+
12+
To start a shell within the Docker container, run `docker run -it mofid /bin/bash`
13+
14+
To analyze a single MOF crystal structure:
15+
16+
```{bash}
17+
# Configure paths in the first two lines, then run this block
18+
MOFID_IN_FILENAME="P1-Cu-BTC.cif"
19+
MOFID_IN_DIR="$PWD" # absolute path to parent directory, e.g. current directory via $PWD
20+
21+
docker run \
22+
--mount type=bind,source="$MOFID_IN_DIR",target="$MOFID_IN_DIR",readonly \
23+
mofid \
24+
python /mofid/Python/run_mofid.py "$MOFID_IN_DIR/$MOFID_IN_FILENAME" /mofid/TempOutput json
25+
```
26+
27+
Or, for analyzing an entire folder:
28+
29+
```{bash}
30+
# Configure the paths in the first two lines, then run this block
31+
MOFID_IN_DIR="$PWD/Resources/TestCIFs"
32+
MOFID_OUT_DIR="$PWD/mofid_output"
33+
34+
mkdir -p "$MOFID_OUT_DIR"
35+
docker run \
36+
--mount type=bind,source="$MOFID_IN_DIR",target=/data,readonly \
37+
--mount type=bind,source="$MOFID_OUT_DIR",target=/out \
38+
mofid \
39+
Scripts/run_folder.sh /data /out
40+
```
41+

‎singularity.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Singularity
2+
3+
## Installation
4+
If you have access to a Linux system or high-performance computing cluster, it may be possible to run the MOFid code via [singularity](https://apptainer.org/user-docs/master/quick_start.html), which packages the MOFid installer into a portable, 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. (For example, you may need to load modules or bind paths to set up singularity.)
5+
6+
1. Download the pre-compiled singularity container (`mofid.sif`) from the [most recent release](https://github.com/snurr-group/mofid/releases).
7+
2. Test your installation using `singularity test mofid.sif`. Your installation is successful if you receive the message `Results: 0 errors in 28 MOFs` at the end of the run.
8+
9+
Alternatively, if you wish to use Docker see [docker.md](docker.md).
10+
11+
## Usage
12+
The singularity container wraps all of the MOFid software into a single package.
13+
14+
As a command line tool:
15+
16+
```{bash}
17+
# Analyzing a single MOF crystal structure
18+
./mofid.sif file path_to_mof.cif
19+
# alternatively: singularity run mofid.sif file path_to_mof.cif
20+
21+
# Analyzing a folder
22+
./mofid.sif folder path_to_input_cif_folder path_to_mofid_output
23+
# By default, path_to_mofid_output is set to "Output/" in your current directory
24+
```
25+
26+
Or, as part of a Python script:
27+
28+
```{python}
29+
import json
30+
import sys
31+
32+
import subprocess
33+
34+
MOFID_SIF = "path_to_mofid.sif"
35+
MOF_CIF_TO_ANALYZE = "path_to_mof.cif"
36+
mofid_cmd = ["singularity", "run", MOFID_SIF, "file", MOF_CIF_TO_ANALYZE]
37+
mofid_run = subprocess.run(mofid_cmd, universal_newlines=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
38+
sys.stderr.write(mofid_run.stderr) # Re-forwarding C++ errors
39+
mofid_output = json.loads(mofid_run.stdout)
40+
```
41+
42+
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`).

0 commit comments

Comments
 (0)