hvala 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hvala-0.0.1/LICENSE +21 -0
- hvala-0.0.1/PKG-INFO +339 -0
- hvala-0.0.1/README.md +299 -0
- hvala-0.0.1/hvala/__init__.py +4 -0
- hvala-0.0.1/hvala/algorithm.py +169 -0
- hvala-0.0.1/hvala/app.py +98 -0
- hvala-0.0.1/hvala/applogger.py +80 -0
- hvala-0.0.1/hvala/batch.py +53 -0
- hvala-0.0.1/hvala/greedy.py +118 -0
- hvala-0.0.1/hvala/parser.py +79 -0
- hvala-0.0.1/hvala/test.py +118 -0
- hvala-0.0.1/hvala/utils.py +257 -0
- hvala-0.0.1/hvala.egg-info/PKG-INFO +339 -0
- hvala-0.0.1/hvala.egg-info/SOURCES.txt +19 -0
- hvala-0.0.1/hvala.egg-info/dependency_links.txt +1 -0
- hvala-0.0.1/hvala.egg-info/entry_points.txt +4 -0
- hvala-0.0.1/hvala.egg-info/requires.txt +3 -0
- hvala-0.0.1/hvala.egg-info/top_level.txt +1 -0
- hvala-0.0.1/pyproject.toml +26 -0
- hvala-0.0.1/setup.cfg +4 -0
- hvala-0.0.1/setup.py +53 -0
hvala-0.0.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Frank Vega
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
hvala-0.0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hvala
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Compute the Approximate Vertex Cover for undirected graph encoded in DIMACS format.
|
|
5
|
+
Home-page: https://github.com/frankvegadelgado/hvala
|
|
6
|
+
Author: Frank Vega
|
|
7
|
+
Author-email: vega.frank@gmail.com
|
|
8
|
+
License: MIT License
|
|
9
|
+
Project-URL: Source Code, https://github.com/frankvegadelgado/hvala
|
|
10
|
+
Project-URL: Documentation Research, https://www.preprints.org/manuscript/202506.0875
|
|
11
|
+
Classifier: Topic :: Scientific/Engineering
|
|
12
|
+
Classifier: Topic :: Software Development
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Environment :: Console
|
|
17
|
+
Classifier: Intended Audience :: Developers
|
|
18
|
+
Classifier: Intended Audience :: Education
|
|
19
|
+
Classifier: Intended Audience :: Information Technology
|
|
20
|
+
Classifier: Intended Audience :: Science/Research
|
|
21
|
+
Classifier: Natural Language :: English
|
|
22
|
+
Requires-Python: >=3.12
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: numpy>=2.2.1
|
|
26
|
+
Requires-Dist: scipy>=1.15.0
|
|
27
|
+
Requires-Dist: networkx[default]>=3.4.2
|
|
28
|
+
Dynamic: author
|
|
29
|
+
Dynamic: author-email
|
|
30
|
+
Dynamic: classifier
|
|
31
|
+
Dynamic: description
|
|
32
|
+
Dynamic: description-content-type
|
|
33
|
+
Dynamic: home-page
|
|
34
|
+
Dynamic: license
|
|
35
|
+
Dynamic: license-file
|
|
36
|
+
Dynamic: project-url
|
|
37
|
+
Dynamic: requires-dist
|
|
38
|
+
Dynamic: requires-python
|
|
39
|
+
Dynamic: summary
|
|
40
|
+
|
|
41
|
+
# Hvala: Approximate Vertex Cover Solver
|
|
42
|
+
|
|
43
|
+

|
|
44
|
+
|
|
45
|
+
This work builds upon [Disproving the Unique Games Conjecture](https://www.preprints.org/manuscript/202506.0875).
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
# The Minimum Vertex Cover Problem
|
|
50
|
+
|
|
51
|
+
The **Minimum Vertex Cover (MVC)** problem is a classic optimization problem in computer science and graph theory. It involves finding the smallest set of vertices in a graph that **covers** all edges, meaning at least one endpoint of every edge is included in the set.
|
|
52
|
+
|
|
53
|
+
## Formal Definition
|
|
54
|
+
|
|
55
|
+
Given an undirected graph $G = (V, E)$, a **vertex cover** is a subset $V' \subseteq V$ such that for every edge $(u, v) \in E$, at least one of $u$ or $v$ belongs to $V'$. The MVC problem seeks the vertex cover with the smallest cardinality.
|
|
56
|
+
|
|
57
|
+
## Importance and Applications
|
|
58
|
+
|
|
59
|
+
- **Theoretical Significance:** MVC is a well-known NP-hard problem, central to complexity theory.
|
|
60
|
+
- **Practical Applications:**
|
|
61
|
+
- **Network Security:** Identifying critical nodes to disrupt connections.
|
|
62
|
+
- **Bioinformatics:** Analyzing gene regulatory networks.
|
|
63
|
+
- **Wireless Sensor Networks:** Optimizing sensor coverage.
|
|
64
|
+
|
|
65
|
+
## Related Problems
|
|
66
|
+
|
|
67
|
+
- **Maximum Independent Set:** The complement of a vertex cover.
|
|
68
|
+
- **Set Cover Problem:** A generalization of MVC.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Problem Statement
|
|
73
|
+
|
|
74
|
+
Input: A Boolean Adjacency Matrix $M$.
|
|
75
|
+
|
|
76
|
+
Answer: Find a Minimum Vertex Cover.
|
|
77
|
+
|
|
78
|
+
### Example Instance: 5 x 5 matrix
|
|
79
|
+
|
|
80
|
+
| | c1 | c2 | c3 | c4 | c5 |
|
|
81
|
+
| ------ | --- | --- | --- | --- | --- |
|
|
82
|
+
| **r1** | 0 | 0 | 1 | 0 | 1 |
|
|
83
|
+
| **r2** | 0 | 0 | 0 | 1 | 0 |
|
|
84
|
+
| **r3** | 1 | 0 | 0 | 0 | 1 |
|
|
85
|
+
| **r4** | 0 | 1 | 0 | 0 | 0 |
|
|
86
|
+
| **r5** | 1 | 0 | 1 | 0 | 0 |
|
|
87
|
+
|
|
88
|
+
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:
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
p edge 5 4
|
|
92
|
+
e 1 3
|
|
93
|
+
e 1 5
|
|
94
|
+
e 2 4
|
|
95
|
+
e 3 5
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
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
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
e W V
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
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.
|
|
105
|
+
|
|
106
|
+
_Example Solution:_
|
|
107
|
+
|
|
108
|
+
Vertex Cover Found `1, 2, 3`: Nodes `1`, `2`, and `3` constitute an optimal solution.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
# Vertex Cover via Degree Reduction Algorithm
|
|
113
|
+
|
|
114
|
+
## Algorithm Overview
|
|
115
|
+
|
|
116
|
+
The **Vertex Cover via Degree Reduction Algorithm** is a polynomial-time approximation algorithm that finds near-optimal vertex covers by transforming the input graph into a simpler structure where optimal solutions can be computed efficiently.
|
|
117
|
+
|
|
118
|
+
### Core Approach
|
|
119
|
+
|
|
120
|
+
1. **Preprocessing**: Remove self-loops and isolated vertices from the input graph
|
|
121
|
+
2. **Component Decomposition**: Process each connected component independently
|
|
122
|
+
3. **Degree Reduction**: Transform each component using a novel reduction technique:
|
|
123
|
+
- Replace each vertex `u` of degree `k` with `k` auxiliary vertices
|
|
124
|
+
- Connect each auxiliary vertex to one of `u`'s original neighbors
|
|
125
|
+
- Assign weight `1/k` to each auxiliary vertex
|
|
126
|
+
- Resulting graph has maximum degree ≤ 1 (paths and cycles only)
|
|
127
|
+
4. **Optimal Solving**: Apply two different greedy algorithms on the reduced graph:
|
|
128
|
+
- Minimum weighted dominating set algorithm
|
|
129
|
+
- Minimum weighted vertex cover algorithm
|
|
130
|
+
5. **Solution Selection**: Choose the better of the two solutions
|
|
131
|
+
6. **Extraction**: Map auxiliary vertices back to original vertices
|
|
132
|
+
|
|
133
|
+
### Key Innovation
|
|
134
|
+
|
|
135
|
+
The algorithm's strength lies in its **dual-approach strategy**: by solving both dominating set and vertex cover problems optimally on the degree-1 reduced graph and selecting the better solution, it consistently outperforms single-approach algorithms.
|
|
136
|
+
|
|
137
|
+
## Performance Guarantees
|
|
138
|
+
|
|
139
|
+
### Approximation Ratio
|
|
140
|
+
- **Theoretical Bound**: `< 2` (strict inequality)
|
|
141
|
+
- **Practical Performance**: Often significantly better than 2, approaching optimal for many graph classes
|
|
142
|
+
- **Comparison**: Outperforms classical algorithms like the standard edge-based 2-approximation
|
|
143
|
+
|
|
144
|
+
### Time Complexity
|
|
145
|
+
- **Overall Runtime**: `O(|V| + |E|)` - linear time
|
|
146
|
+
- **Space Complexity**: `O(|V| + |E|)` for storing the reduced graph
|
|
147
|
+
|
|
148
|
+
#### Complexity Breakdown
|
|
149
|
+
| Phase | Time Complexity | Description |
|
|
150
|
+
|-------|----------------|-------------|
|
|
151
|
+
| Preprocessing | `O(|V| + |E|)` | Remove self-loops and isolated vertices |
|
|
152
|
+
| Component Finding | `O(|V| + |E|)` | DFS/BFS for connected components |
|
|
153
|
+
| Graph Reduction | `O(|E|)` | Create auxiliary vertices and edges |
|
|
154
|
+
| Optimal Solving | `O(|V| + |E|)` | Greedy algorithms on degree-1 graphs |
|
|
155
|
+
| Solution Extraction | `O(|V|)` | Map back to original vertices |
|
|
156
|
+
|
|
157
|
+
## Advantages
|
|
158
|
+
|
|
159
|
+
✅ **Superior Approximation**: Achieves approximation ratio < 2 (better than classical algorithms)
|
|
160
|
+
|
|
161
|
+
✅ **Optimal Time Complexity**: Linear time `O(|V| + |E|)` - matches the best possible for graph problems
|
|
162
|
+
|
|
163
|
+
✅ **Practical Efficiency**: Often produces near-optimal solutions in real-world instances
|
|
164
|
+
|
|
165
|
+
✅ **Theoretical Rigor**: Formal proofs guarantee correctness and performance bounds
|
|
166
|
+
|
|
167
|
+
✅ **Robust Design**: Handles all graph types including disconnected graphs and edge cases
|
|
168
|
+
|
|
169
|
+
## Use Cases
|
|
170
|
+
|
|
171
|
+
The algorithm is particularly effective for:
|
|
172
|
+
- **Large sparse graphs** where linear time complexity is crucial
|
|
173
|
+
- **Graphs with moderate vertex degrees** where the reduction preserves structure well
|
|
174
|
+
- **Applications requiring proven approximation guarantees** with practical efficiency
|
|
175
|
+
- **Real-time systems** where predictable linear performance is essential
|
|
176
|
+
|
|
177
|
+
## Implementation Notes
|
|
178
|
+
|
|
179
|
+
The algorithm requires:
|
|
180
|
+
- NetworkX for graph operations
|
|
181
|
+
- Custom greedy solvers for minimum weighted dominating set and vertex cover on degree-1 graphs
|
|
182
|
+
- Efficient data structures for mapping between original and auxiliary vertices
|
|
183
|
+
|
|
184
|
+
The dual-solution approach (trying both dominating set and vertex cover) is essential for achieving the < 2 approximation ratio and should not be omitted in implementations.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
# Compile and Environment
|
|
189
|
+
|
|
190
|
+
## Prerequisites
|
|
191
|
+
|
|
192
|
+
- Python ≥ 3.12
|
|
193
|
+
|
|
194
|
+
## Installation
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
pip install hvala
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## Execution
|
|
201
|
+
|
|
202
|
+
1. Clone the repository:
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
git clone https://github.com/frankvegadelgado/hvala.git
|
|
206
|
+
cd hvala
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
2. Run the script:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
idemo -i ./benchmarks/testMatrix1
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
utilizing the `idemo` command provided by Hvala's Library to execute the Boolean adjacency matrix `hvala\benchmarks\testMatrix1`. The file `testMatrix1` represents the example described herein. We also support `.xz`, `.lzma`, `.bz2`, and `.bzip2` compressed text files.
|
|
216
|
+
|
|
217
|
+
**Example Output:**
|
|
218
|
+
|
|
219
|
+
```
|
|
220
|
+
testMatrix1: Vertex Cover Found 1, 2, 3
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
This indicates nodes `1, 2, 3` form a vertex cover.
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Vertex Cover Size
|
|
228
|
+
|
|
229
|
+
Use the `-c` flag to count the nodes in the vertex cover:
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
idemo -i ./benchmarks/testMatrix2 -c
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
**Output:**
|
|
236
|
+
|
|
237
|
+
```
|
|
238
|
+
testMatrix2: Vertex Cover Size 5
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
# Command Options
|
|
244
|
+
|
|
245
|
+
Display help and options:
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
idemo -h
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
**Output:**
|
|
252
|
+
|
|
253
|
+
```bash
|
|
254
|
+
usage: idemo [-h] -i INPUTFILE [-a] [-b] [-c] [-v] [-l] [--version]
|
|
255
|
+
|
|
256
|
+
Compute the Approximate Vertex Cover for undirected graph encoded in DIMACS format.
|
|
257
|
+
|
|
258
|
+
options:
|
|
259
|
+
-h, --help show this help message and exit
|
|
260
|
+
-i INPUTFILE, --inputFile INPUTFILE
|
|
261
|
+
input file path
|
|
262
|
+
-a, --approximation enable comparison with a polynomial-time approximation approach within a factor of at most 2
|
|
263
|
+
-b, --bruteForce enable comparison with the exponential-time brute-force approach
|
|
264
|
+
-c, --count calculate the size of the vertex cover
|
|
265
|
+
-v, --verbose anable verbose output
|
|
266
|
+
-l, --log enable file logging
|
|
267
|
+
--version show program's version number and exit
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
---
|
|
271
|
+
|
|
272
|
+
# Batch Execution
|
|
273
|
+
|
|
274
|
+
Batch execution allows you to solve multiple graphs within a directory consecutively.
|
|
275
|
+
|
|
276
|
+
To view available command-line options for the `batch_idemo` command, use the following in your terminal or command prompt:
|
|
277
|
+
|
|
278
|
+
```bash
|
|
279
|
+
batch_idemo -h
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
This will display the following help information:
|
|
283
|
+
|
|
284
|
+
```bash
|
|
285
|
+
usage: batch_idemo [-h] -i INPUTDIRECTORY [-a] [-b] [-c] [-v] [-l] [--version]
|
|
286
|
+
|
|
287
|
+
Compute the Approximate Vertex Cover for all undirected graphs encoded in DIMACS format and stored in a directory.
|
|
288
|
+
|
|
289
|
+
options:
|
|
290
|
+
-h, --help show this help message and exit
|
|
291
|
+
-i INPUTDIRECTORY, --inputDirectory INPUTDIRECTORY
|
|
292
|
+
Input directory path
|
|
293
|
+
-a, --approximation enable comparison with a polynomial-time approximation approach within a factor of at most 2
|
|
294
|
+
-b, --bruteForce enable comparison with the exponential-time brute-force approach
|
|
295
|
+
-c, --count calculate the size of the vertex cover
|
|
296
|
+
-v, --verbose anable verbose output
|
|
297
|
+
-l, --log enable file logging
|
|
298
|
+
--version show program's version number and exit
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
---
|
|
302
|
+
|
|
303
|
+
# Testing Application
|
|
304
|
+
|
|
305
|
+
A command-line utility named `test_idemo` is provided for evaluating the Algorithm using randomly generated, large sparse matrices. It supports the following options:
|
|
306
|
+
|
|
307
|
+
```bash
|
|
308
|
+
usage: test_idemo [-h] -d DIMENSION [-n NUM_TESTS] [-s SPARSITY] [-a] [-b] [-c] [-w] [-v] [-l] [--version]
|
|
309
|
+
|
|
310
|
+
The Hvala Testing Application using randomly generated, large sparse matrices.
|
|
311
|
+
|
|
312
|
+
options:
|
|
313
|
+
-h, --help show this help message and exit
|
|
314
|
+
-d DIMENSION, --dimension DIMENSION
|
|
315
|
+
an integer specifying the dimensions of the square matrices
|
|
316
|
+
-n NUM_TESTS, --num_tests NUM_TESTS
|
|
317
|
+
an integer specifying the number of tests to run
|
|
318
|
+
-s SPARSITY, --sparsity SPARSITY
|
|
319
|
+
sparsity of the matrices (0.0 for dense, close to 1.0 for very sparse)
|
|
320
|
+
-a, --approximation enable comparison with a polynomial-time approximation approach within a factor of at most 2
|
|
321
|
+
-b, --bruteForce enable comparison with the exponential-time brute-force approach
|
|
322
|
+
-c, --count calculate the size of the vertex cover
|
|
323
|
+
-w, --write write the generated random matrix to a file in the current directory
|
|
324
|
+
-v, --verbose anable verbose output
|
|
325
|
+
-l, --log enable file logging
|
|
326
|
+
--version show program's version number and exit
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
# Code
|
|
332
|
+
|
|
333
|
+
- Python implementation by **Frank Vega**.
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
# License
|
|
338
|
+
|
|
339
|
+
- MIT License.
|
hvala-0.0.1/README.md
ADDED
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
# Hvala: Approximate Vertex Cover Solver
|
|
2
|
+
|
|
3
|
+

|
|
4
|
+
|
|
5
|
+
This work builds upon [Disproving the Unique Games Conjecture](https://www.preprints.org/manuscript/202506.0875).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# The Minimum Vertex Cover Problem
|
|
10
|
+
|
|
11
|
+
The **Minimum Vertex Cover (MVC)** problem is a classic optimization problem in computer science and graph theory. It involves finding the smallest set of vertices in a graph that **covers** all edges, meaning at least one endpoint of every edge is included in the set.
|
|
12
|
+
|
|
13
|
+
## Formal Definition
|
|
14
|
+
|
|
15
|
+
Given an undirected graph $G = (V, E)$, a **vertex cover** is a subset $V' \subseteq V$ such that for every edge $(u, v) \in E$, at least one of $u$ or $v$ belongs to $V'$. The MVC problem seeks the vertex cover with the smallest cardinality.
|
|
16
|
+
|
|
17
|
+
## Importance and Applications
|
|
18
|
+
|
|
19
|
+
- **Theoretical Significance:** MVC is a well-known NP-hard problem, central to complexity theory.
|
|
20
|
+
- **Practical Applications:**
|
|
21
|
+
- **Network Security:** Identifying critical nodes to disrupt connections.
|
|
22
|
+
- **Bioinformatics:** Analyzing gene regulatory networks.
|
|
23
|
+
- **Wireless Sensor Networks:** Optimizing sensor coverage.
|
|
24
|
+
|
|
25
|
+
## Related Problems
|
|
26
|
+
|
|
27
|
+
- **Maximum Independent Set:** The complement of a vertex cover.
|
|
28
|
+
- **Set Cover Problem:** A generalization of MVC.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Problem Statement
|
|
33
|
+
|
|
34
|
+
Input: A Boolean Adjacency Matrix $M$.
|
|
35
|
+
|
|
36
|
+
Answer: Find a Minimum Vertex Cover.
|
|
37
|
+
|
|
38
|
+
### Example Instance: 5 x 5 matrix
|
|
39
|
+
|
|
40
|
+
| | c1 | c2 | c3 | c4 | c5 |
|
|
41
|
+
| ------ | --- | --- | --- | --- | --- |
|
|
42
|
+
| **r1** | 0 | 0 | 1 | 0 | 1 |
|
|
43
|
+
| **r2** | 0 | 0 | 0 | 1 | 0 |
|
|
44
|
+
| **r3** | 1 | 0 | 0 | 0 | 1 |
|
|
45
|
+
| **r4** | 0 | 1 | 0 | 0 | 0 |
|
|
46
|
+
| **r5** | 1 | 0 | 1 | 0 | 0 |
|
|
47
|
+
|
|
48
|
+
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:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
p edge 5 4
|
|
52
|
+
e 1 3
|
|
53
|
+
e 1 5
|
|
54
|
+
e 2 4
|
|
55
|
+
e 3 5
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
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
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
e W V
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
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.
|
|
65
|
+
|
|
66
|
+
_Example Solution:_
|
|
67
|
+
|
|
68
|
+
Vertex Cover Found `1, 2, 3`: Nodes `1`, `2`, and `3` constitute an optimal solution.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
# Vertex Cover via Degree Reduction Algorithm
|
|
73
|
+
|
|
74
|
+
## Algorithm Overview
|
|
75
|
+
|
|
76
|
+
The **Vertex Cover via Degree Reduction Algorithm** is a polynomial-time approximation algorithm that finds near-optimal vertex covers by transforming the input graph into a simpler structure where optimal solutions can be computed efficiently.
|
|
77
|
+
|
|
78
|
+
### Core Approach
|
|
79
|
+
|
|
80
|
+
1. **Preprocessing**: Remove self-loops and isolated vertices from the input graph
|
|
81
|
+
2. **Component Decomposition**: Process each connected component independently
|
|
82
|
+
3. **Degree Reduction**: Transform each component using a novel reduction technique:
|
|
83
|
+
- Replace each vertex `u` of degree `k` with `k` auxiliary vertices
|
|
84
|
+
- Connect each auxiliary vertex to one of `u`'s original neighbors
|
|
85
|
+
- Assign weight `1/k` to each auxiliary vertex
|
|
86
|
+
- Resulting graph has maximum degree ≤ 1 (paths and cycles only)
|
|
87
|
+
4. **Optimal Solving**: Apply two different greedy algorithms on the reduced graph:
|
|
88
|
+
- Minimum weighted dominating set algorithm
|
|
89
|
+
- Minimum weighted vertex cover algorithm
|
|
90
|
+
5. **Solution Selection**: Choose the better of the two solutions
|
|
91
|
+
6. **Extraction**: Map auxiliary vertices back to original vertices
|
|
92
|
+
|
|
93
|
+
### Key Innovation
|
|
94
|
+
|
|
95
|
+
The algorithm's strength lies in its **dual-approach strategy**: by solving both dominating set and vertex cover problems optimally on the degree-1 reduced graph and selecting the better solution, it consistently outperforms single-approach algorithms.
|
|
96
|
+
|
|
97
|
+
## Performance Guarantees
|
|
98
|
+
|
|
99
|
+
### Approximation Ratio
|
|
100
|
+
- **Theoretical Bound**: `< 2` (strict inequality)
|
|
101
|
+
- **Practical Performance**: Often significantly better than 2, approaching optimal for many graph classes
|
|
102
|
+
- **Comparison**: Outperforms classical algorithms like the standard edge-based 2-approximation
|
|
103
|
+
|
|
104
|
+
### Time Complexity
|
|
105
|
+
- **Overall Runtime**: `O(|V| + |E|)` - linear time
|
|
106
|
+
- **Space Complexity**: `O(|V| + |E|)` for storing the reduced graph
|
|
107
|
+
|
|
108
|
+
#### Complexity Breakdown
|
|
109
|
+
| Phase | Time Complexity | Description |
|
|
110
|
+
|-------|----------------|-------------|
|
|
111
|
+
| Preprocessing | `O(|V| + |E|)` | Remove self-loops and isolated vertices |
|
|
112
|
+
| Component Finding | `O(|V| + |E|)` | DFS/BFS for connected components |
|
|
113
|
+
| Graph Reduction | `O(|E|)` | Create auxiliary vertices and edges |
|
|
114
|
+
| Optimal Solving | `O(|V| + |E|)` | Greedy algorithms on degree-1 graphs |
|
|
115
|
+
| Solution Extraction | `O(|V|)` | Map back to original vertices |
|
|
116
|
+
|
|
117
|
+
## Advantages
|
|
118
|
+
|
|
119
|
+
✅ **Superior Approximation**: Achieves approximation ratio < 2 (better than classical algorithms)
|
|
120
|
+
|
|
121
|
+
✅ **Optimal Time Complexity**: Linear time `O(|V| + |E|)` - matches the best possible for graph problems
|
|
122
|
+
|
|
123
|
+
✅ **Practical Efficiency**: Often produces near-optimal solutions in real-world instances
|
|
124
|
+
|
|
125
|
+
✅ **Theoretical Rigor**: Formal proofs guarantee correctness and performance bounds
|
|
126
|
+
|
|
127
|
+
✅ **Robust Design**: Handles all graph types including disconnected graphs and edge cases
|
|
128
|
+
|
|
129
|
+
## Use Cases
|
|
130
|
+
|
|
131
|
+
The algorithm is particularly effective for:
|
|
132
|
+
- **Large sparse graphs** where linear time complexity is crucial
|
|
133
|
+
- **Graphs with moderate vertex degrees** where the reduction preserves structure well
|
|
134
|
+
- **Applications requiring proven approximation guarantees** with practical efficiency
|
|
135
|
+
- **Real-time systems** where predictable linear performance is essential
|
|
136
|
+
|
|
137
|
+
## Implementation Notes
|
|
138
|
+
|
|
139
|
+
The algorithm requires:
|
|
140
|
+
- NetworkX for graph operations
|
|
141
|
+
- Custom greedy solvers for minimum weighted dominating set and vertex cover on degree-1 graphs
|
|
142
|
+
- Efficient data structures for mapping between original and auxiliary vertices
|
|
143
|
+
|
|
144
|
+
The dual-solution approach (trying both dominating set and vertex cover) is essential for achieving the < 2 approximation ratio and should not be omitted in implementations.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
# Compile and Environment
|
|
149
|
+
|
|
150
|
+
## Prerequisites
|
|
151
|
+
|
|
152
|
+
- Python ≥ 3.12
|
|
153
|
+
|
|
154
|
+
## Installation
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
pip install hvala
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## Execution
|
|
161
|
+
|
|
162
|
+
1. Clone the repository:
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
git clone https://github.com/frankvegadelgado/hvala.git
|
|
166
|
+
cd hvala
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
2. Run the script:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
idemo -i ./benchmarks/testMatrix1
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
utilizing the `idemo` command provided by Hvala's Library to execute the Boolean adjacency matrix `hvala\benchmarks\testMatrix1`. The file `testMatrix1` represents the example described herein. We also support `.xz`, `.lzma`, `.bz2`, and `.bzip2` compressed text files.
|
|
176
|
+
|
|
177
|
+
**Example Output:**
|
|
178
|
+
|
|
179
|
+
```
|
|
180
|
+
testMatrix1: Vertex Cover Found 1, 2, 3
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
This indicates nodes `1, 2, 3` form a vertex cover.
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## Vertex Cover Size
|
|
188
|
+
|
|
189
|
+
Use the `-c` flag to count the nodes in the vertex cover:
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
idemo -i ./benchmarks/testMatrix2 -c
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
**Output:**
|
|
196
|
+
|
|
197
|
+
```
|
|
198
|
+
testMatrix2: Vertex Cover Size 5
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
---
|
|
202
|
+
|
|
203
|
+
# Command Options
|
|
204
|
+
|
|
205
|
+
Display help and options:
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
idemo -h
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
**Output:**
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
usage: idemo [-h] -i INPUTFILE [-a] [-b] [-c] [-v] [-l] [--version]
|
|
215
|
+
|
|
216
|
+
Compute the Approximate Vertex Cover for undirected graph encoded in DIMACS format.
|
|
217
|
+
|
|
218
|
+
options:
|
|
219
|
+
-h, --help show this help message and exit
|
|
220
|
+
-i INPUTFILE, --inputFile INPUTFILE
|
|
221
|
+
input file path
|
|
222
|
+
-a, --approximation enable comparison with a polynomial-time approximation approach within a factor of at most 2
|
|
223
|
+
-b, --bruteForce enable comparison with the exponential-time brute-force approach
|
|
224
|
+
-c, --count calculate the size of the vertex cover
|
|
225
|
+
-v, --verbose anable verbose output
|
|
226
|
+
-l, --log enable file logging
|
|
227
|
+
--version show program's version number and exit
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
# Batch Execution
|
|
233
|
+
|
|
234
|
+
Batch execution allows you to solve multiple graphs within a directory consecutively.
|
|
235
|
+
|
|
236
|
+
To view available command-line options for the `batch_idemo` command, use the following in your terminal or command prompt:
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
batch_idemo -h
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
This will display the following help information:
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
usage: batch_idemo [-h] -i INPUTDIRECTORY [-a] [-b] [-c] [-v] [-l] [--version]
|
|
246
|
+
|
|
247
|
+
Compute the Approximate Vertex Cover for all undirected graphs encoded in DIMACS format and stored in a directory.
|
|
248
|
+
|
|
249
|
+
options:
|
|
250
|
+
-h, --help show this help message and exit
|
|
251
|
+
-i INPUTDIRECTORY, --inputDirectory INPUTDIRECTORY
|
|
252
|
+
Input directory path
|
|
253
|
+
-a, --approximation enable comparison with a polynomial-time approximation approach within a factor of at most 2
|
|
254
|
+
-b, --bruteForce enable comparison with the exponential-time brute-force approach
|
|
255
|
+
-c, --count calculate the size of the vertex cover
|
|
256
|
+
-v, --verbose anable verbose output
|
|
257
|
+
-l, --log enable file logging
|
|
258
|
+
--version show program's version number and exit
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
# Testing Application
|
|
264
|
+
|
|
265
|
+
A command-line utility named `test_idemo` is provided for evaluating the Algorithm using randomly generated, large sparse matrices. It supports the following options:
|
|
266
|
+
|
|
267
|
+
```bash
|
|
268
|
+
usage: test_idemo [-h] -d DIMENSION [-n NUM_TESTS] [-s SPARSITY] [-a] [-b] [-c] [-w] [-v] [-l] [--version]
|
|
269
|
+
|
|
270
|
+
The Hvala Testing Application using randomly generated, large sparse matrices.
|
|
271
|
+
|
|
272
|
+
options:
|
|
273
|
+
-h, --help show this help message and exit
|
|
274
|
+
-d DIMENSION, --dimension DIMENSION
|
|
275
|
+
an integer specifying the dimensions of the square matrices
|
|
276
|
+
-n NUM_TESTS, --num_tests NUM_TESTS
|
|
277
|
+
an integer specifying the number of tests to run
|
|
278
|
+
-s SPARSITY, --sparsity SPARSITY
|
|
279
|
+
sparsity of the matrices (0.0 for dense, close to 1.0 for very sparse)
|
|
280
|
+
-a, --approximation enable comparison with a polynomial-time approximation approach within a factor of at most 2
|
|
281
|
+
-b, --bruteForce enable comparison with the exponential-time brute-force approach
|
|
282
|
+
-c, --count calculate the size of the vertex cover
|
|
283
|
+
-w, --write write the generated random matrix to a file in the current directory
|
|
284
|
+
-v, --verbose anable verbose output
|
|
285
|
+
-l, --log enable file logging
|
|
286
|
+
--version show program's version number and exit
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
# Code
|
|
292
|
+
|
|
293
|
+
- Python implementation by **Frank Vega**.
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
# License
|
|
298
|
+
|
|
299
|
+
- MIT License.
|