py-graspi 0.0.1.0__tar.gz

py_graspi-0.0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.1
+Name: py-graspi
+Version: 0.0.1.0
+Summary: Utilize Python-igraph to produce similar functionality as GraSPI
+Author: Wenqi Zheng
+Author-email: wenqizhe@buffalo.edu
+Classifier: Programming Language :: Python
+Requires-Python: >=3.7
+Requires-Dist: igraph
+Requires-Dist: matplotlib
+Requires-Dist: numpy

py_graspi-0.0.1.0/README.md

@@ -0,0 +1,490 @@
+# py-graspi
+
+Python-Igraph is a graph-based library contender for the library that works with the GraSPI package. 
+
+This repository contains the implementation to test basic algorithm requirements that need to be met for this package to work similarly to GraSPI.
+The basic algorithm requirements include:
+  -  Construction of graphs
+  -  Graph Filtering
+  -  Determine the number of connected components
+  -  Determine the shortest path from the bottom boundary to all black vertices until the white vertices are met
+  -  Graph visualization
+  -  Computation of Descriptors
+
+## Installation
+First, you'd need to clone the repo by running the following command in your command line:
+```
+git clone git@github.com:wenqizheng326/graspi_igraph.git
+
+```
+**Note: You'd need git installed on your system first**
+<br />
+<br />
+  If you do not have git installed or run into issues with git, please visit: https://github.com/git-guides/install-git
+<br />
+<br />
+Next, you'd need to navigate to the cloned repo using terminal. An example would be:
+```
+
+cd /path/graspi_igraph
+```
+First, make sure you're on the memoryFix branch of the repo by running
+```
+git checkout memoryFix
+```
+Once navigated to the branch, downloads needed can be found in requirements.txt and can be installed by:
+
+```
+pip install -r requirements.txt
+```
+**Note: you must have Python and pip installed onto your system**
+<br />
+<br />
+  If you do not have Python installed, please visit: https://www.python.org/downloads/
+<br />
+<br />
+  If you do not have pip installed or are running into issues with pip, please visit: https://pip.pypa.io/en/stable/installation/
+<br />
+<br />
+  If there are any other issues with installation, please visit: https://python.igraph.org/en/stable/ 
+
+## Running memory tests
+To run memory tests, run the following command in terminal:
+```
+python main.py n dimension function
+```
+**Make sure of the following:**
+  -  Replace "n" with the size of the graph you want. Note: n should be between 1-1000 for 2D graphs and 1-100 for 3D graphs
+  -  Replace "dimension" with 2D or 3D to specify if you want a 2D or 3D graph
+  -  Replace "function" with either generate, filter, or shortest_path, to choose which function you want to test memory for
+ 
+<br />**An example of a correct command would be:**
+```
+python main.py 10 2D generate
+
+```
+## Outputs
+After running this command, you should see
+```
+
+Generating results
+```
+Followed by the memory usage and runtime results after some time.
+<br />
+<br />
+ The following will print:
+```
+Completed
+```
+To know that the tests have been completed
+## To Test Algorithms
+
+To **generate graphs**, call the generateGraph(_file_) function which takes in a input-file name
+  -  returns a graph
+```
+ig.generateGraph("2D-testFile/testFile-10-2D.txt")   # utilizing the test file found in 2D-testFiles folder as an example
+```
+
+To **filter graphs**, call filterGraph(_graph_) function which takes in a graph object 
+  -  can pass a graph generated by generateGraph(_file_)
+  -  returns a filtered graph
+```
+g = ig.generateGraph("2D-testFile/testFile-10-2D.txt")     # utilizing the test file found in 2D-testFiles folder as an example
+fg = ig.filterGraph(g)
+```
+
+To **determine the connected components** of the filtered graph, call connected_components() function
+```
+print(fg.connected_components())
+```
+The number of connected components can be found by taking the length of the result produced by the connected_components function 
+```
+print(len(fg.connected_components())) 
+```
+
+The **shortest path** between some meta-vertices to all specified vertices calling the function shortest_path(_fiteredGraph_, _specifiedVertices_, _metaVertex_, _fileName_)
+  -  stores the distance of the paths to from the _metaVertex_ to every single _specified Vertices_ in a text file called _fileName_
+
+Example:
+  - the example below finds the shortest path between all black vertices to the blue meta-vertex and stores it in the text file, black_to_blue_paths.txt
+```
+ig.shortest_path(fg,'black','blue',"black_to_blue_paths.txt")    #fg is a filtered graph object
+```
+
+### To get list of descriptors (WZ)
+
+A **descriptors stored in a dictionary** can be found by calling the function descriptors(_graph_)
+
+```
+ig.descriptors(g)      # g is a graph object
+```
+A **list of descriptors in a text file** can be found by calling the function descriptorsToTxt(_dictionary_,_filename_)
+```
+ig.descriptorsToTxt(dict,"descriptors_list.txt")
+```
+
+### To visualize graphs
+
+  -  for 2d graphs, call visual2D(_graph_)
+```
+g = ig.generateGraph("2D-testFile/testFile-10-2D.txt")     # utilizing the test file found in 2D-testFiles folder as an example
+ig.visual2D(g)
+```
+  -  for 3d graphs, call visual3D(_graph_)
+```
+g = ig.generateGraph("3D-testFile/testFile-10-3D.txt")     # utilizing the test file found in 2D-testFiles folder as an example
+ig.visual3D(g)
+Finally, the following message will be printed out:
+```
+
+## Testing from Command Line
+
+
+\*\*\*First and foremost make sure you are in the py-graspi directory. If not you may run into some errors\*\*\*
+
+In this GitHub Repo, all the tests are in the test directory. Furthermore, within this directory are two more directories: 2D-testFile and 3D-testFile.
+Inside these directories, some files hold information about either 2d or 3d graphs based on the directory name. 
+When running from command lines you will need to know the complete pathname of the test file you are trying to run.
+
+There are 2 type of input file formats: *.txt & *.graphe
+### _*.txt input format:_
+
+
+The command line input to run a graph creation for *.txt files will have the following format:
+```
+python graspi_igraph/igraph_testing.py {total pathname of test file} {2d or 3d}
+```
+If you have the same test directories as this GitHub Repo you should be able to run the following command line argument to output a 2D 10x10 graph.
+```
+python graspi_igraph/igraph_testing.py graspi_igraph/tests/2D-testFile/testFile-10-2D.txt 2d
+```
+### _*.graphe input format:_
+*.graphe input format is not that different, only extra parameter you need to input is a 'g' before the total pathname of the test file.
+
+The command line input to run a graph creation for *.graphe files will have the following format:
+````
+python graspi_igraph/igraph_testing.py g {total pathname of test file} {2d or 3d}
+````
+If you have the same test directories as this GitHub Repo you should be able to run the following command line argument to output a 2D 4x3 graph.
+```
+python graspi_igraph/igraph_testing.py g graspi_igraph/tests/2D-testFile/data_4_3.graphe 2d 
+```
+
+
+Python-Igraph is a graph-based library contender for the library that works with the GraSPI package. 
+
+This repository contains the implementation to test basic algorithm requirements that need to be met for this package to work similarly to GraSPI.
+The basic algorithm requirements include:
+  -  Construction of graphs
+  -  Graph Filtering
+  -  Determine the number of connected components
+  -  Determine the shortest path from some meta-vertices to all specified vertices
+  -  Provide a list of descriptors
+  -  Graph visualization
+
+## Installation
+Download the packages found in requirements.txt after you have set up your virtual environment. 
+Cone the repo by:
+```
+git clone https://github.com/owodolab/py-graspi.git
+```
+**Note: You'd need git installed on your system first**
+<br />
+<br />
+  If you do not have git installed or run into issues with git, please visit: https://github.com/git-guides/install-git
+<br />
+<br />
+Next, you'd need to navigate to the cloned repo using terminal. An example would be:
+```
+cd /path/py-graspi
+```
+Once navigated to the branch, access the following directory:
+```
+cd graspi_igraph
+```
+Next, the downloads needed can be found in requirements.txt and can be installed by:
+```
+pip install notebook
+```
+Install the graspi_igraph package by:
+```
+pip install graspi-igraph
+```
+Once installed, to utilize the package remember to import the package:
+```
+import graspi_igraph as ig
+```
+
+**Note: you must have Python and pip installed onto your system**
+<br />
+<br />
+  If you do not have Python installed, please visit: https://www.python.org/downloads/
+<br />
+<br />
+  If you do not have pip installed or are running into issues with pip, please visit: https://pip.pypa.io/en/stable/installation/
+<br />
+<br />
+  If there are any other issues with installation, please visit: https://python.igraph.org/en/stable/ 
+
+## Running All 33 Morphologies Tests (JZ)
+To run the morphologies tests, return to the previous directory of "/py-graspi" by running:
+```
+cd ..
+```
+Next, make sure you're on bash first by running:
+```
+bash
+```
+Next, run the following:
+```
+chmod +x run.sh
+```
+Finally, run the following: 
+```
+./run.sh <file_type>
+```
+Substitute <file_type> with either txt or pdf for the desired output type.
+## 33 Morphologies Output (JZ)
+After running the command, the automatic report generation will begin. 
+<br />
+<br /> 
+The following will print when the report generation begins:
+```
+Generating PDF (If on pdf mode)
+Generating Text Files
+```
+As the script is running, the following will print for which microstructure it is on
+```
+Executing <test_file>
+```
+After a few minutes, the following will print once the report has been created
+```
+Text Files Generated
+PDF Generated (If on pdf mode)
+```
+## Viewing 33 Morphologies Output (JZ)
+For text files, navigate to the results directory by using the following command:
+```
+cd graspi_igraph/results
+```
+Use the following command to view the list of text files generated:
+```
+ls
+```
+To view the result in each file, run the following command:
+```
+cat <result_file_name>
+```
+Replace <result_file_name> with any of the files outputted by "ls"
+<br />
+<br />
+If using pdf mode, the pdf should automattically open upon completion.
+<br />
+<br />
+If the pdf does not automatically pop up, use the following commands:
+### On Windows
+```
+start graspi_igraph/test_results.pdf
+```
+### On MacOS
+```
+open graspi_igraph/test_results.pdf
+```
+### On Linux
+```
+evince graspi_igraph/test_results.pdf
+```
+If evince is not installed, run this first:
+```
+sudo apt install evince
+```
+## To Test Algorithms
+
+To **generate graphs**, call the generateGraph(_file_) function which takes in a input-file name
+  -  returns a graph and a bool of whether it's a 2D graph
+```
+ig.generateGraph("2D-testFile/testFile-10-2D.txt")   # utilizing the test file found in 2D-testFiles folder as an example
+```
+
+To **filter graphs**, call filterGraph(_graph_) function which takes in a graph object 
+  -  can pass a graph generated by generateGraph(_file_)
+  -  returns a filtered graph
+```
+g, is_2D = ig.generateGraph("2D-testFile/testFile-10-2D.txt")     # utilizing the test file found in 2D-testFiles folder as an example
+fg = ig.filterGraph(g)
+```
+
+To **determine the connected components** of the filtered graph, call connected_components() function
+```
+print(ig.connectedComponents(fg))
+```
+The number of connected components can be found by taking the length of the result produced by the connected_components function 
+```
+print(len(ig.connectedComponents(fg))) 
+```
+
+The **shortest path** between some meta-vertices to all specified vertices calling the function shortest_path(_fiteredGraph_, _specifiedVertices_, _metaVertex_, _fileName_)
+  -  stores the distance of the paths to from the _metaVertex_ to every single _specified Vertices_ in a text file called _fileName_
+
+Example:
+  - the example below finds the shortest path between all black vertices to the blue meta-vertex and stores it in the text file, black_to_blue_paths.txt
+```
+ig.shortest_path(fg,'black','blue',"black_to_blue_paths.txt")    #fg is a filtered graph object
+```
+
+### To get list of descriptors (WZ)
+
+A **descriptors stored in a dictionary** can be found by calling the function descriptors(_graph_)
+
+```
+ig.descriptors(g)      # g is a graph object
+```
+A **list of descriptors in a text file** can be found by calling the function descriptorsToTxt(_dictionary_,_filename_)
+  -  _dict_ is a dictionary of descriptors that is returned by calling ig.descriptors(g)
+```
+ig.descriptorsToTxt(dict,"descriptors_list.txt") 
+```
+
+To test if descriptors are computed correctly, you can run the following script in the terminal to check.
+  -  make sure you are in the py-graspi directory after git cloning
+  -  if not in directory, in the terminal, run the command
+     ```
+     cd py-graspi
+     ```
+
+```
+python graspi_igraph/simple-test.py graspi_igraph/data/data_0.5_2.2_001900.txt
+```
+
+### To visualize graphs
+
+To visualize graphs, call visualize(_graph_, _is_2D_)
+  -  _graph_ is a graph object
+  -  _is_2D_ is a bool of whether a graph is 2D, also a return value when _generateGraph()_ is called
+```
+g, is_2D = ig.generateGraph("2D-testFile/testFile-10-2D.txt")     # utilizing the test file found in 2D-testFiles folder as an example
+ig.visual2D(g, is_2D)
+```
+
+## Testing from Command Line (Kevin)
+
+
+Now that we have cloned the REPO lets talk about testing.
+
+\*\*\*First and foremost make sure you are in te py-graspi directory. If not you may run into some errors\*\*\*
+
+In this GitHub Repo, all the tests are in the test directory. Furthermore, within this directory are two more directories: 2D-testFile and 3D-testFile.
+Inside these directories, some files hold information about either 2d or 3d graphs based on the directory name. 
+When running from command lines you will need to know the complete pathname of the test file you are trying to run.
+
+There are 2 type of input file formats: *.txt & *.graphe
+### _*.txt input format:_
+
+
+The command line input to run a graph creation for *.txt files will have the following format:
+```
+python graspi_igraph/igraph_testing.py {total pathname of test file}
+```
+If you have the same test directories as this GitHub Repo you should be able to run the following command line argument to output a 2D 10x10 graph.
+```
+python graspi_igraph/igraph_testing.py graspi_igraph/tests/2D-testFile/testFile-10-2D.txt 
+```
+### _*.graphe input format:_
+*.graphe input format is not that different, only extra parameter you need to input is a 'g' before the total pathname of the test file.
+
+The command line input to run a graph creation for *.graphe files will have the following format:
+````
+python graspi_igraph/igraph_testing.py -g {total pathname of test file} 
+````
+If you have the same test directories as this GitHub Repo you should be able to run the following command line argument to output a 2D 4x3 graph.
+```
+python graspi_igraph/igraph_testing.py g graspi_igraph/tests/2D-testFile/data_4_3.graphe
+```
+### _Running with Periodicity:_
+We include the option of running any test case with periodicity turned on ONLY for *.txt input files. This 
+is done with an added '-p' parameter. This parameter is added first before inputting the test case
+format.
+
+For example, for *.txt cases with periodicity turned on will look like the following:
+```
+python graspi_igraph/igraph_testing.py -p {total pathname of test file}
+```
+
+To test this out run the example test case above but with the added '-p' parameter
+to turn periodicity on.
+
+## Generate and Run Files for py-graspi API (ML)
+In order to generate an API using sphinx, you need to follow the installation of py-graspi:
+
+Cloning the repository:
+```
+git clone https://github.com/owodolab/py-graspi.git
+```
+
+**Make sure your current directory is py-graspi**
+
+In order to create an API with sphinx, you need to download sphinx with this command in the command line interface:
+```
+pip install sphinx
+```
+Additional dependencies needed for installed Sphinx Extension:
+```
+pip install sphinxcontrib-details-directive
+```
+Provides additional details (dropdowns) for each submodle listed.
+```
+pip install sphinx_rtd_theme
+```
+Uses the rtf theme for the API
+```
+pip install --upgrade setuptools
+```
+Used by python to handle resources and files
+
+In the command line interface, run this command:
+```
+sphinx-build -b html ./docs/source/ ./docs/ 
+```
+* **sphinx-build**: This is the main command for building Sphinx documentation. It generates documentation from reStructuredText (.rst) or Markdown (.md) source files.
+* **-b html**: This specifies the output format. Here, -b html tells Sphinx to build the documentation in HTML format, which is typically used for web-based documentation.
+* **./docs/source/**: This is the path to the source directory where Sphinx looks for the documentation source files. In this example, it’s in the source subdirectory inside docs.
+* **./docs/**: This is the output directory where the built HTML files will be saved. In this example, it’s the main docs folder. After running this command, you’ll find the generated HTML files here.
+
+In order to see the py-graspi API, run this command in the command line interface:
+
+**FOR WINDOWS:**
+```
+start docs/index.html
+```
+
+**FOR MACOS:**
+```
+open docs/index.html
+```
+This would create a local view. You can see the official API on Github pages at: https://owodolab.github.io/py-graspi/
+
+## 2D & 3D Morphologies Tests
+To run the 2d and 3d morphologies you will need to setup notebook and pip install the graspi_igraph package.
+
+First you will need to git clone the current repo, make sure that you are in the ""dev branch"":
+```
+git clone https://github.com/owodolab/py-graspi.git
+```
+Then, you will need to install the igraph package:
+```
+pip install graspi-igraph
+```
+Install jupyter notebook in order to view the test file:
+```
+pip install notebook
+```
+
+Finally, you will be able to use the command:
+```
+jupyter notebook
+```
+This will bring you into the testing filing on jupyter.
+Navigate to the directory 3d_2d_tests.
+Navigate to the file graspi_igraph_notebook.ipynb.
+
+On this file you will be able to run and view the 2d and 3d morphologies for subtask 4, card 104.

py_graspi-0.0.1.0/graspi_igraph/__init__.py

@@ -0,0 +1,4 @@
+from .csvFileMaker import *
+from .igraph_testing import *
+from .testFileMaker import *
+from .descriptors import *

py_graspi-0.0.1.0/graspi_igraph/bugfix_descriptors.py

@@ -0,0 +1,46 @@
+import igraph_testing as ig
+import matplotlib.pyplot as plt
+from mpl_toolkits.mplot3d import Axes3D
+import numpy as np
+import os
+import descriptors
+import sys
+
+def main():
+
+    filename = sys.argv[1]
+    # dimension = sys.argv[2]
+    graph_type = sys.argv[2]
+    functionality = sys.argv[3]
+
+    g,is_2D = ig.generateGraph(filename)
+    fg = ig.filterGraph(g)
+
+
+    if functionality == 'visuals':
+        if is_2D == True:
+            if graph_type == 'g':
+                ig.visual2D(g,'graph')
+                print("Plot displayed.")
+            if graph_type == 'fg':
+                ig.visual2D(fg,'filtered')
+                print("Plot displayed.")
+        else:
+            if graph_type == 'g':
+                ig.visual3D(g)
+            if graph_type == 'fg':
+                ig.visual3D(fg)
+
+    if functionality == 'descriptors':
+        print(descriptors.descriptors(g))
+
+    
+    if functionality == 'cc':
+        print(ig.connectedComponents(g))
+
+
+if __name__ == '__main__':
+    main()
+
+
+

py_graspi-0.0.1.0/graspi_igraph/csvFileMaker.py

@@ -0,0 +1,99 @@
+from . import igraph_testing as ig
+import time 
+import tracemalloc
+import csv
+
+def functionRuntime(count,function, *argv):
+    """
+    Measures the average runtime of a function over a specified number of executions.
+
+    Args:
+        count (int): The number of times to execute the function.
+        function (Callable): The function to measure the runtime for.
+        *argv: Arguments to be passed to the function.
+
+    Returns:
+        float: The average execution time in seconds across the `count` executions.
+    """
+    totaltime = 0
+    
+    for x in range(count):
+        startTime = time.time()
+        function(*argv)
+        endTime = time.time()
+        timeTaken = endTime - startTime
+        totaltime += timeTaken
+
+    avgExecution = totaltime / count
+
+    return avgExecution
+
+def functionMemory(function, *argv):
+    """
+    Measures the peak memory usage of a function during its execution.
+
+    Args:
+        function (Callable): The function to measure memory usage for.
+        *argv: Arguments to be passed to the function.
+
+    Returns:
+        int: The memory used in bytes during the function's execution.
+    """
+    tracemalloc.start()
+    function(*argv)
+    stats = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+    stats = stats[1] - stats[0]
+    
+    return stats
+
+def csvMaker(fileName, n, dim, count, graphGen, graphGenPar,graphFilt, graphFiltPar,shortPath, shortPathPar):
+    """
+    Runs multiple graph-related functions, records their runtime and memory usage,
+    and stores the results in a CSV file.
+
+    Args:
+        fileName (str): The name of the CSV file to write results to.
+        n (int): The base size parameter of the graph.
+        dim (int): The dimension to compute the total nodes as n^dim.
+        count (int): The number of times to run each function for benchmarking.
+        graphGen (Callable): Function to generate a graph.
+        graphGenPar (tuple): Parameters for the graph generation function.
+        graphFilt (Callable): Function to filter the graph.
+        graphFiltPar (tuple): Parameters for the graph filtering function.
+        shortPath (Callable): Function to compute the shortest path in the graph.
+        shortPathPar (tuple): Parameters for the shortest path function.
+
+    Returns:
+        None: The function writes results to the specified CSV file.
+    """
+    row = [n,(n**dim)]
+    totalTime = 0
+    totalMem = 0
+
+    graphGenRuntime = functionRuntime(count,graphGen,*graphGenPar)
+    graphFiltRuntime = functionRuntime(count,graphFilt,*graphFiltPar)
+    shortPathRuntime = functionRuntime(count,shortPath,*shortPathPar)
+
+    totalTime = graphGenRuntime + graphFiltRuntime + shortPathRuntime
+    totalTime = round(totalTime,20)
+    
+    graphGenMem = functionMemory(graphGen,*graphGenPar)
+    graphFiltMem = functionMemory(graphFilt,*graphFiltPar)
+    shortPathMem = functionMemory(shortPath,*shortPathPar)
+
+    totalMem = graphGenMem + graphFiltMem + shortPathMem
+    totalMem = round(totalMem,20)
+
+    row.append(graphGenRuntime)
+    row.append(graphFiltRuntime)
+    row.append(shortPathRuntime)
+    row.append(totalTime)
+    row.append(graphGenMem)
+    row.append(graphFiltMem)
+    row.append(shortPathMem)
+    row.append(totalMem)
+
+    with open(fileName, 'a', newline = "\n") as file:
+        writer = csv.writer(file)
+        writer.writerow(row)