pyreason 0.0.3

An explainable inference software supporting annotated, real valued, graph based and temporal logic

PyReason

An explainable inference software supporting annotated, real valued, graph based and temporal logic.

Check out the PyReason Hello World program if you're new, or want get get a feel for the software.

Table of Contents

1. Usage
2. Setup & Run
   • Setup & Run on the ASU Agave Cluster (interactive)
   • Setup & Run on the ASU Agave Cluster (sbatch)
   • Setup & Run on your Local System

1. Usage

To run pyreason you need 4 files:

1. A YAML file containing the pyreason rules
2. A YAML file containing the pyreason facts
3. A YAML file containing the pyreason labels
4. A YAML file containing the pyreason ipl (inconsistent predicate list)

The format of these files is very important. Please refer to the example YAML files provided when making your own rules/facts/labels/ipl.

2. Setup & Run

There are three ways of running PyReason:

1. interactive session (on the Agave cluster)
2. sbatch (on the Agave cluster)
3. locally

To Run pyreason, the required command line arguments are:

1. The path to a graphml file
2. The number of timesteps you want to run the diffusion
3. The path to the YAML rules file
4. The path to the YAML facts file
5. The path to the YAML labels file
6. The path to the YAML ipl file

For more optional command line arguments refer to (make doc) or type

python3 -m pyreason.scripts.diffuse -h

2.1 Setup & Run on the ASU Agave Cluster (interactive)

To create an Anaconda environment and activate it, and then clone the repository, type the following in your Agave terminal.

NOTE: This only needs to be done once. Once you've setup your environment you can run the interactive session directly.

module load anaconda/py3
conda create -n PYREASON
source activate PYREASON
git clone https://github.com/lab-v2/pyreason
cd pyreason
pip3 install -r requirements.txt

Now create an interavtive session with:

interactive -N 1 -n 45 -p htc -t 0-00:10:00

This starts an interactive session using 45 cores on one node for 10 minutes. You can change the time parameter based on your needs.

To run PyReason, type the following in your Agave terminal. Make sure you are in the top pyreason directory. Don't forget to replace the placeholders with the correct values.

python3 -m pyreason.scripts.diffuse --graph_path <path/to/graphml/file> --timesteps <number of timesteps to run> --rules_yaml_path <path/to/rules.yaml> --facts_yaml_path <path/to/facts.yaml> --labels_yaml_path <path/to/labels.yaml> --ipl <path/to/ipl.yaml>

2.2 Setup & Run on the ASU Agave Cluster (sbatch)

Open the run_on_agave.sh in a text editor, and modify the paths for the graph file, the rules file, the facts file, the labels file and the ipl file. Specify the number of timesteps to run for. Then in your Agave terminal, type:

sbatch run_on_agave.sh

This will submit a job to the cluster. You will be able to find the output of the program in the output folder.

2.3 Setup & Run on your Local System

Clone the repository and install the necessary packages to make pyreason run

git clone https://github.com/lab-v2/pyreason
cd pyreason
pip3 install -r requirements.txt

To run PyReason, type the following in your Agave terminal. Make sure you are in the top pyreason directory. Don't forget to replace the placeholders with the correct values.

python3 -m pyreason.scripts.diffuse --graph_path <path/to/graphml/file> --timesteps <number of timesteps to run> --rules_yaml_path <path/to/rules.yaml> --facts_yaml_path <path/to/facts.yaml> --labels_yaml_path <path/to/labels.yaml> --ipl <path/to/ipl.yaml>

BSD 3-Clause License

Copyright (c) 2022, Lab V2

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. 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.

3. Neither the name of the copyright holder 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.