Merge branch 'development' of https://github.com/UWB-Biocomputing/Graphitti into issue-697-update-serializer-class

Author: Divya Kamath

Tools/Graph Generation/README.md

@@ -0,0 +1,61 @@
+# Graph Generation for NG911 Simulations
+
+## Overview
+This repository provides scripts for generating and visualizing synthetic star graphs representing Public Safety Answering Points (PSAPs), responders, and callers. These graphs are designed for simulations and analysis within emergency response systems. The generated graphs can be visualized using `matplotlib` and saved in GraphML format for further use.
+
+## Purpose
+The main objective is to create synthetic star graphs representing emergency response systems with:
+- PSAPs at the center.
+- Responders and callers distributed within specified regions.
+- Special handling for prime numbers of PSAPs and other specific cases.
+- The `visualize_generation.py` script specifically focuses on visualizing the generation of a synthetic network graph from parameterized GraphML data, highlighting different node types and their positions within defined regions.
+
+## `graph_generation.py`
+Generates synthetic star graphs based on input parameters. The script handles various scenarios, including special cases such as prime numbers of PSAPs, to ensure appropriate distribution of graph elements. It includes logic for:
+ - Distributing PSAPs, responders, and callers within defined regions.
+ - Handling prime numbers of PSAPs by creating an extra region and combining it appropriately.
+ - Ensuring each region contains a star-shaped graph centered on a PSAP.
+
+## `visualize_generation.py`
+Visualizes the graphs generated by `graph_generation.py` from the GraphML file. It displays the graph with color-coded nodes for PSAPs, callers, and responders. It outlines the rectangular boundary, PSAP regions, and caller regions, allowing for easy analysis and verification of the graph structure.
+
+## `format_graphml.py`
+Converts the `graph_generation.py` synthetic GraphML file to a format that can be used within the cluster-point call generation and Graphitti simulations. This script ensures the GraphML file is compatible with the tools and configurations used in subsequent simulation steps.
+
+## 'examples' folder 
+call_generation: Contains XML call scripts generated using `format_graphml.py` graphml  files and python clusterpoint process. These scripts use the structured graphs to simulate call events, providing data for emergency response simulations.
+
+config_files: Holds the configuration files for Graphitti simulations that test GraphGeneration scalability. These files use the generated graphs and call data to configure and run various simulation scenarios, testing different aspects of emergency response systems.
+
+graphml_generation: Stores the generated graph models from `graph_generation.py`, formatted through `format_graphml.py`. These GraphML files serve as the basis for further simulations and call generation, ensuring consistency and compatibility across different simulation tools.
+
+output_files: Contains the output files from the simulations run using the configuration files. These outputs include results and logs from the simulation runs, which can be analyzed to evaluate the performance and effectiveness of the generated graphs and configurations.
+
+test_visualization: Holds visualization PNGs of various cases from the `graph_generation.py` script, visualized using `visualize_generation.py`. These visualizations provide a graphical representation of the generated graphs, highlighting the structure and distribution of PSAPs, callers, and responders.
+
+## Install Dependencies
+Ensure you have all required libraries installed. Use `pip` or `conda` for installation.
+
+## Libraries Used
+- `matplotlib.pyplot`: For creating and displaying visualizations of the graph.
+- `networkx`: For creating, manipulating, and saving network graphs.
+- `random`: For generating random positions for responders and callers within specified regions.
+- `xml.etree.ElementTree`: For creating and manipulating XML elements.
+- `xml.dom.minidom`: For printing XML information.
+- `math`: Provides mathematical functions used for calculating regions and dimensions.
+
+## Mathematical Logic
+- **Region Partitioning:** Calculates the number of rows and columns needed to partition a bounding box into a specified number of regions. Uses the square root to determine the optimal grid layout and adjusts as necessary to match the required number of regions.
+- **Region Dimensions:** Computes the width and height of each region based on the bounding box dimensions and the number of rows and columns.
+- **Region Merging:** Combines two rectangular regions into a single larger region by determining the minimum and maximum coordinates.
+- **Prime Number Handling:** Checks if the number of PSAPs is a prime number, which affects how regions are created and combined.
+- **Random Positioning:** Generates random positions for responders and callers within their designated regions.
+
+## Contributors
+- Jasleen Kaur Saini
+- Zaina Shaikh
+
+
+
+
+