Skip to content

Commit e2c0994

Browse files
luca-software-developerluca-software-developer
committed
How-to & documentazione Sphinx
1 parent be8a0e3 commit e2c0994

23 files changed

Lines changed: 1449 additions & 5 deletions

‎README.md‎

Lines changed: 194 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ The library offers comprehensive hypernetwork manipulation capabilities with
1616
optimized performance characteristics. The core implementation supports
1717
efficient addition and removal of nodes and hyperedges while maintaining
1818
complete structural integrity. Advanced attack simulation functionality
19-
enables security analysis through both individual attacks and coordinated
19+
enables analysis through both individual attacks and coordinated
2020
attack sequences.
2121

2222
The modular architecture facilitates selective importing of functionality
@@ -72,11 +72,11 @@ hypernetwork.print_info()
7272

7373
## Attack Simulation
7474

75-
The simulation framework enables comprehensive security analysis through
76-
individual attacks and coordinated sequences.
75+
The simulation framework enables comprehensive analysis through individual
76+
attacks and coordinated sequences.
7777

7878
```python
79-
"""Execute attack simulations for security analysis."""
79+
"""Execute attack simulations for analysis."""
8080
from hiper import (
8181
HypernetworkSimulator, AddNodeAttack, RemoveNodeAttack,
8282
AttackSequence, Hypernetwork
@@ -86,7 +86,7 @@ from hiper import (
8686
hn = Hypernetwork()
8787
hn.add_hyperedge(0, [1, 2, 3])
8888

89-
simulator = HypernetworkSimulator('security_analysis')
89+
simulator = HypernetworkSimulator('analysis')
9090
simulator.set_hypernetwork(hn)
9191

9292
# Execute individual attack with restoration
@@ -107,6 +107,195 @@ execution_stats = sequence_result['execution_stats']
107107
print(f"Success rate: {execution_stats['success_rate']:.2%}")
108108
```
109109

110+
## Running Experiments
111+
112+
The library provides several example scripts in the `examples/` directory for
113+
comprehensive hypernetwork analysis. Each script performs specific experiments
114+
and saves results in dedicated output directories.
115+
116+
For detailed documentation of all examples, see [`examples/README.md`](examples/README.md).
117+
118+
### Resilience Experiments
119+
120+
Test hypernetwork resilience by removing nodes using different strategies:
121+
122+
```bash
123+
python examples/run_resilience_experiments.py [optional_dataset_path]
124+
```
125+
126+
**What it does:**
127+
- Removes nodes at percentages: 1%, 2%, 5%, 10%, 25%
128+
- Uses three strategies: Random, TOPSIS Top (critical), TOPSIS Bottom (peripheral)
129+
- Computes metrics: connectivity, redundancy coefficient, s-walk efficiency
130+
131+
**Results location:** `resilience_results/`
132+
- `resilience_analysis.png` - Metric degradation plots
133+
- `impact_comparison.png` - Strategy comparison
134+
- `resilience_summary.csv` - Detailed numeric results
135+
136+
### Perturbation Analysis
137+
138+
Analyze single and multiple perturbations with targeted attacks:
139+
140+
```bash
141+
python examples/run_perturbation_analysis.py
142+
```
143+
144+
**What it does:**
145+
- Single perturbations: 1%, 2%, 5%, 10% node removal
146+
- Multiple perturbations: Attack sequences with k ∈ {2, 5, 10, 25, 50, 100}
147+
- Compares Random vs TOPSIS targeting strategies
148+
- Analyzes component fragmentation and largest component evolution
149+
150+
**Results location:** `results/`
151+
- `{dataset}_single_comparison.png` - Single perturbation plots
152+
- `{dataset}_multiple_timeline.png` - Evolution over attack sequences
153+
- `{dataset}_component_analysis.png` - Fragmentation analysis
154+
- `{dataset}_largest_components.png` - Component metrics
155+
- `perturbation_results_{timestamp}.json` - Complete experimental data
156+
- `analysis_summary.json` - Executive summary
157+
158+
### Comprehensive Node and Hyperedge Experiments
159+
160+
Run experiments on both node and hyperedge removal:
161+
162+
```bash
163+
python examples/run_node_hyperedge_experiments.py
164+
```
165+
166+
**What it does:**
167+
- Tests removal of both nodes and hyperedges
168+
- Computes traditional metrics (connectivity, redundancy)
169+
- Computes higher-order cohesion metrics (HOCR_m, LHC_m)
170+
- Removal percentages: 1%, 2%, 5%, 10%, 25%
171+
172+
**Results location:** `resilience_results/plots/`
173+
- `node_removal_traditional_metrics.png` - Node removal analysis
174+
- `hyperedge_removal_traditional_metrics.png` - Hyperedge removal analysis
175+
- `higher_order_cohesion_comparison.png` - Advanced metrics
176+
- `strategy_effectiveness_heatmap.png` - Comparative effectiveness
177+
178+
### Statistical Analysis
179+
180+
Perform cross-domain statistical analysis on hypernetwork features:
181+
182+
```bash
183+
python examples/run_statistical_analysis.py
184+
```
185+
186+
**What it does:**
187+
- Computes structural features for all datasets in `data/` directory
188+
- Performs ANOVA/Kruskal-Wallis tests across hypergraph families
189+
- Correlation analysis between features and resilience metrics
190+
- Normalized metrics for size-independent comparisons
191+
192+
**Results location:** `statistical_analysis_results/`
193+
- `data_directory_features_by_family.png` - Feature distributions by family
194+
- `structural_correlations_heatmap.png` - Feature correlation matrix
195+
- `structural_features_scatter.png` - Relationship visualizations
196+
- `significant_correlations.png` - Feature-resilience correlations
197+
- `statistical_analysis_summary.csv` - Complete statistical results
198+
- `data_directory_features.csv` - Computed features for all datasets
199+
200+
### Working with Custom Datasets
201+
202+
To run experiments on your own hypernetwork data:
203+
204+
1. **Prepare your dataset**: Create a text file where each line represents a
205+
hyperedge with space-separated node IDs:
206+
```
207+
1 2 3
208+
2 3 4 5
209+
3 4 6
210+
```
211+
212+
2. **Place in data directory**: Save the file in the `data/` folder
213+
214+
3. **Run experiments**: Execute any of the experiment scripts above
215+
216+
4. **View results**: Check the corresponding results directories for plots
217+
and data files
218+
219+
### Example Workflow
220+
221+
Complete analysis workflow for a new dataset:
222+
223+
```bash
224+
# 1. Run perturbation analysis
225+
python examples/run_perturbation_analysis.py
226+
227+
# 2. Run resilience experiments
228+
python examples/run_resilience_experiments.py data/your_dataset.txt
229+
230+
# 3. Run comprehensive analysis
231+
python examples/run_node_hyperedge_experiments.py
232+
233+
# 4. Perform statistical analysis
234+
python examples/run_statistical_analysis.py
235+
```
236+
237+
Results will be organized in:
238+
- `results/` - Perturbation analysis outputs
239+
- `resilience_results/` - Resilience experiment outputs
240+
- `statistical_analysis_results/` - Statistical analysis outputs
241+
242+
## API Documentation
243+
244+
Complete API documentation is available and built with **Sphinx**. The documentation
245+
includes:
246+
247+
- Complete class and function references with type hints
248+
- Method signatures and parameters
249+
- Detailed docstrings from the source code
250+
- Module hierarchies and dependencies
251+
- Code examples and tutorials
252+
- Searchable interface
253+
254+
### Viewing the Documentation
255+
256+
To view the pre-built documentation, open `docs/_build/html/index.html` in your
257+
web browser:
258+
259+
```bash
260+
# Windows
261+
start docs/_build/html/index.html
262+
263+
# macOS
264+
open docs/_build/html/index.html
265+
266+
# Linux
267+
xdg-open docs/_build/html/index.html
268+
```
269+
270+
### Building the Documentation
271+
272+
If you make changes to the code or documentation, rebuild it locally:
273+
274+
**Option 1: Using sphinx-build directly:**
275+
276+
```bash
277+
cd docs
278+
sphinx-build -b html . _build/html
279+
```
280+
281+
**Option 2: Using make:**
282+
283+
```bash
284+
cd docs
285+
make html # Unix/macOS
286+
make.bat html # Windows
287+
```
288+
289+
### Documentation Structure
290+
291+
- **User Guide**: Getting started, experiments, and examples
292+
- **API Reference**: Complete module, class, and function documentation
293+
- Core modules (Hypernetwork, Node, Hyperedge)
294+
- Dataset management (loading and configuration)
295+
- Metrics (experiments, TOPSIS, connectivity, distance, etc.)
296+
- Simulation framework (simulator, attacks, sequences)
297+
- **Development**: Contributing guidelines and license
298+
110299
## Configuration
111300

112301
The library supports flexible configuration through JSON-based configuration

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# Sphinx build output
2+
_build/

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/_static/custom.css‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
/* Custom CSS for HIPER documentation - Read the Docs theme */
2+
3+
/* Make content area wider on large screens */
4+
.wy-nav-content {
5+
max-width: none !important;
6+
}
7+
8+
/* On very large screens, limit to reasonable width but wider than default */
9+
@media screen and (min-width: 1400px) {
10+
.wy-nav-content {
11+
max-width: 1400px;
12+
margin: 0 auto;
13+
}
14+
}
15+
16+
/* On extra large screens, use even more space */
17+
@media screen and (min-width: 1800px) {
18+
.wy-nav-content {
19+
max-width: 1600px;
20+
}
21+
}

‎docs/_static/favicon.svg‎

Lines changed: 3 additions & 0 deletions
Loading

‎docs/_templates/search.html‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
{% extends "!search.html" %}
2+
3+
{% block body %}
4+
<h1>{{ _('Search') }}</h1>
5+
6+
<div id="fallback" class="admonition warning">
7+
<p class="first admonition-title">{{ _('Please activate JavaScript to enable the search functionality.') }}</p>
8+
<p class="last">
9+
{% trans %}Searching for multiple words only shows matches that contain
10+
all words.{% endtrans %}
11+
</p>
12+
</div>
13+
14+
<div id="search-field" style="margin: 2em 0;">
15+
<form role="search" method="get" action="{{ pathto('search') }}">
16+
<div style="display: flex; gap: 10px; align-items: center;">
17+
<input
18+
type="text"
19+
name="q"
20+
id="search-input"
21+
placeholder="{{ _('Search documentation...') }}"
22+
style="flex: 1; padding: 10px; font-size: 16px; border: 1px solid #ccc; border-radius: 4px;"
23+
autofocus
24+
/>
25+
<input
26+
type="submit"
27+
value="{{ _('Search') }}"
28+
style="padding: 10px 20px; font-size: 16px; background-color: #2980b9; color: white; border: none; border-radius: 4px; cursor: pointer;"
29+
/>
30+
</div>
31+
<input type="hidden" name="check_keywords" value="yes" />
32+
<input type="hidden" name="area" value="default" />
33+
</form>
34+
</div>
35+
36+
<div id="search-results">
37+
{% if search_performed %}
38+
<h2>{{ _('Search Results') }}</h2>
39+
{% if not search_results %}
40+
<p>{{ _('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.') }}</p>
41+
{% endif %}
42+
{% endif %}
43+
{{ search_results }}
44+
</div>
45+
46+
<script type="text/javascript">
47+
// Focus the search input when page loads
48+
document.addEventListener('DOMContentLoaded', function() {
49+
var searchInput = document.getElementById('search-input');
50+
if (searchInput) {
51+
// Get query from URL if present
52+
var params = new URLSearchParams(window.location.search);
53+
var query = params.get('q');
54+
if (query) {
55+
searchInput.value = query;
56+
}
57+
}
58+
});
59+
</script>
60+
{% endblock %}

‎docs/api/core.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
Core Modules
2+
============
3+
4+
The core modules provide the fundamental data structures and operations
5+
for hypernetwork manipulation.
6+
7+
hiper.core.hypernetwork
8+
-----------------------
9+
10+
.. automodule:: hiper.core.hypernetwork
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
hiper.core.node
16+
---------------
17+
18+
.. automodule:: hiper.core.node
19+
:members:
20+
:undoc-members:
21+
:show-inheritance:
22+
23+
hiper.core.hyperedge
24+
--------------------
25+
26+
.. automodule:: hiper.core.hyperedge
27+
:members:
28+
:undoc-members:
29+
:show-inheritance:
30+
31+
hiper.core.incidence
32+
--------------------
33+
34+
.. automodule:: hiper.core.incidence
35+
:members:
36+
:undoc-members:
37+
:show-inheritance:

‎docs/api/datasets.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Dataset Management
2+
==================
3+
4+
The datasets module provides utilities for loading and managing
5+
hypernetwork datasets.
6+
7+
hiper.datasets
8+
--------------
9+
10+
.. automodule:: hiper.datasets
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
hiper.config
16+
------------
17+
18+
.. automodule:: hiper.config
19+
:members:
20+
:undoc-members:
21+
:show-inheritance:

0 commit comments

Comments
 (0)