siriaisa 0.0.1__tar.gz

siriaisa-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Vega
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

siriaisa-0.0.1/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: siriaisa
+Version: 0.0.1
+Summary: Compute the Approximate Independent Dominating Set for undirected graph encoded in DIMACS format.
+Home-page: https://github.com/frankvegadelgado/mids
+Author: Frank Vega
+Author-email: vega.frank@gmail.com
+License: MIT License
+Project-URL: Source Code, https://github.com/frankvegadelgado/mids
+Project-URL: Documentation Research, https://github.com/frankvegadelgado/mids
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.2.1
+Requires-Dist: scipy>=1.15.0
+Requires-Dist: networkx[default]>=3.4.2
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Siriaisa: Approximate Independent Dominating Set Solver
+
+![To my mother who I love.](docs/siriaisa.jpg)
+
+This work builds upon [A 3-Approximation for Independent Dominating Sets: The Siriaisa Algorithm](https://github.com/frankvegadelgado/mids).
+
+---
+
+# Overview of the Minimum Independent Dominating Set (MIDS)
+
+## Definition:
+
+A **dominating set** in a graph $G = (V, E)$ is a subset $D \subseteq V$ such that every vertex not in $D$ is adjacent to at least one vertex in $D$. The **minimum independent dominating set (MIDS)** is the smallest possible dominating set in terms of the number of vertices.
+
+## Key Concepts:
+
+1. **Graph Representation**:
+
+   - $V$: Set of vertices.
+   - $E$: Set of edges connecting the vertices.
+
+2. **Dominating Set**:
+
+   - A set $D$ where for every vertex $v \in V$, either $v \in D$ or $v$ is adjacent to some vertex in $D$.
+
+3. **Minimum Independent Dominating Set**:
+   - The dominating set with the smallest cardinality (i.e., the fewest number of vertices).
+
+## Applications:
+
+- **Network Design**: Ensuring coverage in wireless sensor networks.
+- **Social Networks**: Identifying influential nodes.
+- **Game Theory**: Strategies in certain types of games.
+- **Biology**: Modeling protein-protein interaction networks.
+
+## Computational Complexity:
+
+- **NP-Hard**: Finding the minimum independent dominating set is computationally intensive for large graphs.
+- **Approximation Algorithms**: Used to find near-optimal solutions in polynomial time.
+
+## Algorithms:
+
+1. **Greedy Algorithm**:
+
+   - Iteratively selects the vertex that covers the most uncovered vertices.
+   - Provides a logarithmic approximation ratio.
+
+2. **Integer Linear Programming (ILP)**:
+
+   - Formulates the problem as an optimization problem.
+   - Solvable using ILP solvers for exact solutions, though computationally expensive.
+
+3. **Heuristics and Metaheuristics**:
+   - Genetic algorithms, simulated annealing, etc., for large-scale problems.
+
+## Challenges:
+
+- **Scalability**: Exact algorithms are infeasible for very large graphs.
+- **Dynamic Graphs**: Maintaining a minimum independent dominating set in graphs that change over time.
+
+## Research Directions:
+
+- **Parallel Algorithms**: Leveraging multi-core processors and distributed computing.
+- **Machine Learning**: Using learning-based approaches to predict dominating sets.
+- **Hybrid Methods**: Combining exact and heuristic methods for better performance.
+
+## Conclusion:
+
+The minimum independent dominating set problem is a fundamental issue in graph theory with wide-ranging applications. While it is computationally challenging, various algorithms and heuristics provide practical solutions for different scenarios. Ongoing research continues to improve the efficiency and applicability of these methods.
+
+---
+
+## Problem Statement
+
+Input: A Boolean Adjacency Matrix $M$.
+
+Answer: Find a Minimum Independent Dominating Set.
+
+### Example Instance: 5 x 5 matrix
+
+|        | c1  | c2  | c3  | c4  | c5  |
+| ------ | --- | --- | --- | --- | --- |
+| **r1** | 0   | 0   | 1   | 0   | 1   |
+| **r2** | 0   | 0   | 0   | 1   | 0   |
+| **r3** | 1   | 0   | 0   | 0   | 1   |
+| **r4** | 0   | 1   | 0   | 0   | 0   |
+| **r5** | 1   | 0   | 1   | 0   | 0   |
+
+The input for undirected graph is typically provided in [DIMACS](http://dimacs.rutgers.edu/Challenges) format. In this way, the previous adjacency matrix is represented in a text file using the following string representation:
+
+```
+p edge 5 4
+e 1 3
+e 1 5
+e 2 4
+e 3 5
+```
+
+This represents a 5x5 matrix in DIMACS format such that each edge $(v,w)$ appears exactly once in the input file and is not repeated as $(w,v)$. In this format, every edge appears in the form of
+
+```
+e W V
+```
+
+where the fields W and V specify the endpoints of the edge while the lower-case character `e` signifies that this is an edge descriptor line.
+
+_Example Solution:_
+
+Independent Dominating Set Found `1, 4`: Nodes `1` and `4` constitute an optimal solution.
+
+---
+
+# Compile and Environment
+
+## Prerequisites
+
+- Python >= 3.12
+
+## Installation
+
+```bash
+pip install siriaisa
+```
+
+## Execution
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/frankvegadelgado/mids.git
+   cd mids
+   ```
+
+2. Run the script:
+
+   ```bash
+   iris -i ./benchmarks/testMatrix1
+   ```
+
+   utilizing the `iris` command provided by Siriaisa's library to execute the Boolean adjacency matrix `mids\benchmarks\testMatrix1`. The file `testMatrix1` represents the example described herein. We also support `.xz`, `.lzma`, `.bz2`, and `.bzip2` compressed text files.
+
+   **Example Output:**
+
+   ```
+   testMatrix1: Independent Dominating Set Found 1, 4
+   ```
+
+   This indicates nodes `1, 4` form a Independent Dominating Set.
+
+---
+
+## Independent Dominating Set Size
+
+Use the `-c` flag to count the nodes in the Independent Dominating Set:
+
+```bash
+iris -i ./benchmarks/testMatrix2 -c
+```
+
+**Output:**
+
+```
+testMatrix2: Independent Dominating Set Size 2
+```
+
+---
+
+# Command Options
+
+Display help and options:
+
+```bash
+iris -h
+```
+
+**Output:**
+
+```bash
+usage: iris [-h] -i INPUTFILE [-a] [-b] [-c] [-v] [-l] [--version]
+
+Solve the Approximate Independent Dominating Set for undirected graph encoded in DIMACS format.
+
+options:
+  -h, --help            show this help message and exit
+  -i INPUTFILE, --inputFile INPUTFILE
+                        input file path
+  -a, --approximation   enable comparison with a polynomial-time approximation approach within a maximum degree factor
+  -b, --bruteForce      enable comparison with the exponential-time brute-force approach
+  -c, --count           calculate the size of the Independent Dominating Set
+  -v, --verbose         enable verbose output
+  -l, --log             enable file logging
+  --version             show program's version number and exit
+```
+
+---
+
+# Batch Execution
+
+Batch execution allows you to solve multiple graphs within a directory consecutively.
+
+To view available command-line options for the `batch_iris` command, use the following in your terminal or command prompt:
+
+```bash
+batch_iris -h
+```
+
+This will display the following help information:
+
+```bash
+usage: batch_iris [-h] -i INPUTDIRECTORY [-a] [-b] [-c] [-v] [-l] [--version]
+
+Solve the Approximate Independent Dominating Set for all undirected graphs encoded in DIMACS format and stored in a directory.
+
+options:
+  -h, --help            show this help message and exit
+  -i INPUTDIRECTORY, --inputDirectory INPUTDIRECTORY
+                        Input directory path
+  -a, --approximation   enable comparison with a polynomial-time approximation approach within a maximum degree factor
+  -b, --bruteForce      enable comparison with the exponential-time brute-force approach
+  -c, --count           calculate the size of the Independent Dominating Set
+  -v, --verbose         enable verbose output
+  -l, --log             enable file logging
+  --version             show program's version number and exit
+```
+
+---
+
+# Testing Application
+
+A command-line utility named `test_iris` is provided for evaluating the Algorithm using randomly generated, large sparse matrices. It supports the following options:
+
+```bash
+usage: test_iris [-h] -d DIMENSION [-n NUM_TESTS] [-s SPARSITY] [-a] [-b] [-c] [-w] [-v] [-l] [--version]
+
+The Siriaisa Testing Application using randomly generated, large sparse matrices.
+
+options:
+  -h, --help            show this help message and exit
+  -d DIMENSION, --dimension DIMENSION
+                        an integer specifying the dimensions of the square matrices
+  -n NUM_TESTS, --num_tests NUM_TESTS
+                        an integer specifying the number of tests to run
+  -s SPARSITY, --sparsity SPARSITY
+                        sparsity of the matrices (0.0 for dense, close to 1.0 for very sparse)
+  -a, --approximation   enable comparison with a polynomial-time approximation approach within a maximum degree factor
+  -b, --bruteForce      enable comparison with the exponential-time brute-force approach
+  -c, --count           calculate the size of the Independent Dominating Set
+  -w, --write           write the generated random matrix to a file in the current directory
+  -v, --verbose         enable verbose output
+  -l, --log             enable file logging
+  --version             show program's version number and exit
+```
+
+---
+
+# Code
+
+- Python implementation by **Frank Vega**.
+
+---
+
+# Complexity
+
+```diff
++ Siriaisa separates feasibility from the approximation certificate: every returned set is verified as independent and dominating, while a universal proof of the 3-approximation certificate would imply P = NP by known MIDS inapproximability results.
+```
+
+---
+
+# License
+
+- MIT License.

siriaisa-0.0.1/README.md

@@ -0,0 +1,272 @@
+# Siriaisa: Approximate Independent Dominating Set Solver
+
+![To my mother who I love.](docs/siriaisa.jpg)
+
+This work builds upon [A 3-Approximation for Independent Dominating Sets: The Siriaisa Algorithm](https://github.com/frankvegadelgado/mids).
+
+---
+
+# Overview of the Minimum Independent Dominating Set (MIDS)
+
+## Definition:
+
+A **dominating set** in a graph $G = (V, E)$ is a subset $D \subseteq V$ such that every vertex not in $D$ is adjacent to at least one vertex in $D$. The **minimum independent dominating set (MIDS)** is the smallest possible dominating set in terms of the number of vertices.
+
+## Key Concepts:
+
+1. **Graph Representation**:
+
+   - $V$: Set of vertices.
+   - $E$: Set of edges connecting the vertices.
+
+2. **Dominating Set**:
+
+   - A set $D$ where for every vertex $v \in V$, either $v \in D$ or $v$ is adjacent to some vertex in $D$.
+
+3. **Minimum Independent Dominating Set**:
+   - The dominating set with the smallest cardinality (i.e., the fewest number of vertices).
+
+## Applications:
+
+- **Network Design**: Ensuring coverage in wireless sensor networks.
+- **Social Networks**: Identifying influential nodes.
+- **Game Theory**: Strategies in certain types of games.
+- **Biology**: Modeling protein-protein interaction networks.
+
+## Computational Complexity:
+
+- **NP-Hard**: Finding the minimum independent dominating set is computationally intensive for large graphs.
+- **Approximation Algorithms**: Used to find near-optimal solutions in polynomial time.
+
+## Algorithms:
+
+1. **Greedy Algorithm**:
+
+   - Iteratively selects the vertex that covers the most uncovered vertices.
+   - Provides a logarithmic approximation ratio.
+
+2. **Integer Linear Programming (ILP)**:
+
+   - Formulates the problem as an optimization problem.
+   - Solvable using ILP solvers for exact solutions, though computationally expensive.
+
+3. **Heuristics and Metaheuristics**:
+   - Genetic algorithms, simulated annealing, etc., for large-scale problems.
+
+## Challenges:
+
+- **Scalability**: Exact algorithms are infeasible for very large graphs.
+- **Dynamic Graphs**: Maintaining a minimum independent dominating set in graphs that change over time.
+
+## Research Directions:
+
+- **Parallel Algorithms**: Leveraging multi-core processors and distributed computing.
+- **Machine Learning**: Using learning-based approaches to predict dominating sets.
+- **Hybrid Methods**: Combining exact and heuristic methods for better performance.
+
+## Conclusion:
+
+The minimum independent dominating set problem is a fundamental issue in graph theory with wide-ranging applications. While it is computationally challenging, various algorithms and heuristics provide practical solutions for different scenarios. Ongoing research continues to improve the efficiency and applicability of these methods.
+
+---
+
+## Problem Statement
+
+Input: A Boolean Adjacency Matrix $M$.
+
+Answer: Find a Minimum Independent Dominating Set.
+
+### Example Instance: 5 x 5 matrix
+
+|        | c1  | c2  | c3  | c4  | c5  |
+| ------ | --- | --- | --- | --- | --- |
+| **r1** | 0   | 0   | 1   | 0   | 1   |
+| **r2** | 0   | 0   | 0   | 1   | 0   |
+| **r3** | 1   | 0   | 0   | 0   | 1   |
+| **r4** | 0   | 1   | 0   | 0   | 0   |
+| **r5** | 1   | 0   | 1   | 0   | 0   |
+
+The input for undirected graph is typically provided in [DIMACS](http://dimacs.rutgers.edu/Challenges) format. In this way, the previous adjacency matrix is represented in a text file using the following string representation:
+
+```
+p edge 5 4
+e 1 3
+e 1 5
+e 2 4
+e 3 5
+```
+
+This represents a 5x5 matrix in DIMACS format such that each edge $(v,w)$ appears exactly once in the input file and is not repeated as $(w,v)$. In this format, every edge appears in the form of
+
+```
+e W V
+```
+
+where the fields W and V specify the endpoints of the edge while the lower-case character `e` signifies that this is an edge descriptor line.
+
+_Example Solution:_
+
+Independent Dominating Set Found `1, 4`: Nodes `1` and `4` constitute an optimal solution.
+
+---
+
+# Compile and Environment
+
+## Prerequisites
+
+- Python >= 3.12
+
+## Installation
+
+```bash
+pip install siriaisa
+```
+
+## Execution
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/frankvegadelgado/mids.git
+   cd mids
+   ```
+
+2. Run the script:
+
+   ```bash
+   iris -i ./benchmarks/testMatrix1
+   ```
+
+   utilizing the `iris` command provided by Siriaisa's library to execute the Boolean adjacency matrix `mids\benchmarks\testMatrix1`. The file `testMatrix1` represents the example described herein. We also support `.xz`, `.lzma`, `.bz2`, and `.bzip2` compressed text files.
+
+   **Example Output:**
+
+   ```
+   testMatrix1: Independent Dominating Set Found 1, 4
+   ```
+
+   This indicates nodes `1, 4` form a Independent Dominating Set.
+
+---
+
+## Independent Dominating Set Size
+
+Use the `-c` flag to count the nodes in the Independent Dominating Set:
+
+```bash
+iris -i ./benchmarks/testMatrix2 -c
+```
+
+**Output:**
+
+```
+testMatrix2: Independent Dominating Set Size 2
+```
+
+---
+
+# Command Options
+
+Display help and options:
+
+```bash
+iris -h
+```
+
+**Output:**
+
+```bash
+usage: iris [-h] -i INPUTFILE [-a] [-b] [-c] [-v] [-l] [--version]
+
+Solve the Approximate Independent Dominating Set for undirected graph encoded in DIMACS format.
+
+options:
+  -h, --help            show this help message and exit
+  -i INPUTFILE, --inputFile INPUTFILE
+                        input file path
+  -a, --approximation   enable comparison with a polynomial-time approximation approach within a maximum degree factor
+  -b, --bruteForce      enable comparison with the exponential-time brute-force approach
+  -c, --count           calculate the size of the Independent Dominating Set
+  -v, --verbose         enable verbose output
+  -l, --log             enable file logging
+  --version             show program's version number and exit
+```
+
+---
+
+# Batch Execution
+
+Batch execution allows you to solve multiple graphs within a directory consecutively.
+
+To view available command-line options for the `batch_iris` command, use the following in your terminal or command prompt:
+
+```bash
+batch_iris -h
+```
+
+This will display the following help information:
+
+```bash
+usage: batch_iris [-h] -i INPUTDIRECTORY [-a] [-b] [-c] [-v] [-l] [--version]
+
+Solve the Approximate Independent Dominating Set for all undirected graphs encoded in DIMACS format and stored in a directory.
+
+options:
+  -h, --help            show this help message and exit
+  -i INPUTDIRECTORY, --inputDirectory INPUTDIRECTORY
+                        Input directory path
+  -a, --approximation   enable comparison with a polynomial-time approximation approach within a maximum degree factor
+  -b, --bruteForce      enable comparison with the exponential-time brute-force approach
+  -c, --count           calculate the size of the Independent Dominating Set
+  -v, --verbose         enable verbose output
+  -l, --log             enable file logging
+  --version             show program's version number and exit
+```
+
+---
+
+# Testing Application
+
+A command-line utility named `test_iris` is provided for evaluating the Algorithm using randomly generated, large sparse matrices. It supports the following options:
+
+```bash
+usage: test_iris [-h] -d DIMENSION [-n NUM_TESTS] [-s SPARSITY] [-a] [-b] [-c] [-w] [-v] [-l] [--version]
+
+The Siriaisa Testing Application using randomly generated, large sparse matrices.
+
+options:
+  -h, --help            show this help message and exit
+  -d DIMENSION, --dimension DIMENSION
+                        an integer specifying the dimensions of the square matrices
+  -n NUM_TESTS, --num_tests NUM_TESTS
+                        an integer specifying the number of tests to run
+  -s SPARSITY, --sparsity SPARSITY
+                        sparsity of the matrices (0.0 for dense, close to 1.0 for very sparse)
+  -a, --approximation   enable comparison with a polynomial-time approximation approach within a maximum degree factor
+  -b, --bruteForce      enable comparison with the exponential-time brute-force approach
+  -c, --count           calculate the size of the Independent Dominating Set
+  -w, --write           write the generated random matrix to a file in the current directory
+  -v, --verbose         enable verbose output
+  -l, --log             enable file logging
+  --version             show program's version number and exit
+```
+
+---
+
+# Code
+
+- Python implementation by **Frank Vega**.
+
+---
+
+# Complexity
+
+```diff
++ Siriaisa separates feasibility from the approximation certificate: every returned set is verified as independent and dominating, while a universal proof of the 3-approximation certificate would imply P = NP by known MIDS inapproximability results.
+```
+
+---
+
+# License
+
+- MIT License.

siriaisa-0.0.1/pyproject.toml

@@ -0,0 +1,26 @@
+[tool.ruff]
+exclude = [".git", ".vscode", ".pytest_cache", ".mypy_cache", ".env"]
+line-length = 125
+
+[tool.ruff.lint]
+ignore = ["B008", "ISC001", "E501", "W191"]
+select = [
+    "B",
+    "E",
+    "F",
+    "W",
+    "I",
+    "N",
+    "C4",
+    "EXE",
+    "ISC",
+    "ICN",
+    "PIE",
+    "PT",
+    "RET",
+    "SIM",
+    "ERA",
+    "PLC",
+    "RUF",
+    "ARG",
+]

siriaisa-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

siriaisa-0.0.1/setup.py

@@ -0,0 +1,53 @@
+from pathlib import Path
+
+import setuptools
+
+VERSION = "0.0.1"
+
+NAME = "siriaisa"
+
+INSTALL_REQUIRES = [
+    "numpy>=2.2.1",
+    "scipy>=1.15.0",
+    "networkx[default]>=3.4.2"
+]
+
+setuptools.setup(
+    name=NAME,
+    version=VERSION,
+    description="Compute the Approximate Independent Dominating Set for undirected graph encoded in DIMACS format.",
+    url="https://github.com/frankvegadelgado/mids",
+    project_urls={
+        "Source Code": "https://github.com/frankvegadelgado/mids",
+        "Documentation Research": "https://github.com/frankvegadelgado/mids",
+    },
+    author="Frank Vega",
+    author_email="vega.frank@gmail.com",
+    license="MIT License",
+    classifiers=[
+        "Topic :: Scientific/Engineering",
+        "Topic :: Software Development",
+        "Development Status :: 5 - Production/Stable",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3.12",
+        "Environment :: Console",
+        "Intended Audience :: Developers",
+        "Intended Audience :: Education",
+        "Intended Audience :: Information Technology",
+        "Intended Audience :: Science/Research",
+        "Natural Language :: English",
+    ],
+    python_requires=">=3.12",
+    # Requirements
+    install_requires=INSTALL_REQUIRES,
+    packages=["siriaisa"],
+    long_description=Path("README.md").read_text(),
+    long_description_content_type="text/markdown",
+    entry_points={
+        'console_scripts': [
+            'iris = siriaisa.app:main',
+            'test_iris = siriaisa.test:main',
+            'batch_iris = siriaisa.batch:main'
+        ]
+    }
+)

siriaisa-0.0.1/siriaisa/__init__.py

@@ -0,0 +1,4 @@
+# Siriaisa: Approximate Independent Dominating Set Solver https://pypi.org/project/siriaisa
+# Author: Frank Vega
+
+__all__ = ["utils", "approx", "algorithm", "parser", "applogger", "test", "app", "batch"]