Skip to content

Commit d4019b8

Browse files
Mircusclaude
Mircus
and
claude
committed
Public-facing polish: docs spine, badges, onboarding path, CONTRIBUTING
Docs spine: - docs/README.md — index with docs map and navigation - docs/tutorials/getting_started.md — install, first examples, onboarding - docs/tutorials/social_diffusers.md — diffusers, bridges, cohesion, temporal - docs/api/overview.md — public API map with stable-vs-heuristic labels README: - Added CI, Python, status, and license badges - Added "Start here" section with numbered onboarding path - Added "Examples at a glance" table with type and takeaway columns - Added "Documentation" table linking to docs spine - Added link to CONTRIBUTING.md Archive: - Moved docs/internal/archive/ to docs/archive/ (cleaner path) New: - CONTRIBUTING.md — lightweight contribution guidance Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 1c51a9c commit d4019b8

File tree

14 files changed

+408
-35
lines changed

14 files changed

+408
-35
lines changed

‎CONTRIBUTING.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Contributing to SHE
2+
3+
SHE is a **Research Preview** under the [HNCL v1.0](LICENCE.md) license
4+
(source-available, non-commercial).
5+
6+
## How to engage
7+
8+
- **Issues** are welcome: bugs, questions, feature ideas.
9+
- **Pull requests** are welcome for the stable package (`src/she/`).
10+
- Please keep PRs focused — one concern per PR.
11+
- New public-surface features should include tests and an example or
12+
docstring update.
13+
14+
## What is where
15+
16+
| Path | Status |
17+
|---|---|
18+
| `src/she/` | Canonical public package — contributions welcome here |
19+
| `src/core/`, `src/morse/` | Legacy/experimental — not part of stable API |
20+
| `tests/` | pytest suite — run with `pytest` |
21+
| `examples/` | Scripts and notebooks |
22+
| `docs/` | Tutorials, API overview, use cases |
23+
24+
## Running tests
25+
26+
```bash
27+
pip install -e ".[dev]"
28+
pytest -v
29+
```
30+
31+
## Style
32+
33+
- No heavy formatting rules yet. Keep code readable.
34+
- Prefer clear variable names over comments.
35+
- Match the style of surrounding code.
36+
37+
## Reporting security issues
38+
39+
If you find a security issue, please email [info@holomathics.com](mailto:info@holomathics.com)
40+
rather than opening a public issue.

‎README.md‎

Lines changed: 58 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# S.H.E. — Simplicial Hyperstructure Engine
22

3+
[![CI](https://github.com/Mircus/S.H.E./actions/workflows/ci.yml/badge.svg)](https://github.com/Mircus/S.H.E./actions/workflows/ci.yml)
4+
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
35
[![License: HNCL](https://img.shields.io/badge/license-HNCL-blue.svg)](/LICENCE.md)
6+
[![Status: Research Preview](https://img.shields.io/badge/status-research%20preview-orange.svg)](#repo-status)
47

58
<p align="center">
69
<img src="she_logo.png" alt="SHE logo" width="500">
@@ -53,8 +56,8 @@ graphs are not enough.
5356

5457
**Social analysis**
5558
- `rank_diffusers` / `rank_entity_diffusers` / `rank_simplex_diffusers`
56-
- `find_bridge_simplices` — cross-community higher-order bridges
57-
- `group_cohesion` — structural cohesion scoring for candidate groups
59+
- `find_bridge_simplices` — cross-community higher-order bridges (heuristic)
60+
- `group_cohesion` — structural cohesion scoring for candidate groups (composite)
5861
- `rank_influencers` — graph centrality vs. simplex diffusion comparison
5962

6063
**Temporal**
@@ -74,13 +77,44 @@ graphs are not enough.
7477
## Installation
7578

7679
```bash
80+
git clone https://github.com/Mircus/S.H.E.
81+
cd S.H.E
7782
pip install -e . # core only
7883
pip install -e ".[dev]" # with pytest / ruff
7984
pip install -e ".[tda]" # with gudhi / giotto-tda
8085
```
8186

8287
Requires **Python >= 3.10**.
8388

89+
## Start here
90+
91+
**1.** Check your install:
92+
93+
```python
94+
import she
95+
print(she.__version__) # 0.1.2
96+
```
97+
98+
**2.** Run the smallest example:
99+
100+
```bash
101+
python examples/toy_triangle.py
102+
```
103+
104+
**3.** Run the main worked example (graph centrality vs simplex diffusion):
105+
106+
```bash
107+
python examples/social_media_diffusers.py
108+
```
109+
110+
**4.** Open the real-data notebook:
111+
112+
```
113+
examples/eu_email_analysis.ipynb
114+
```
115+
116+
For a full walkthrough, see [Getting Started](docs/tutorials/getting_started.md).
117+
84118
## Quickstart
85119

86120
```python
@@ -104,40 +138,16 @@ for b in find_bridge_simplices(hs):
104138
print(f"{sorted(b.members)} communities={b.communities_spanned}")
105139
```
106140

107-
## Worked use case: social-media diffusers
108-
109-
`examples/social_media_diffusers.py` builds a synthetic two-community scenario
110-
where a high-degree hub dominates graph centrality, but a cross-community
111-
triad carries more weight as a higher-order structure.
112-
113-
```bash
114-
python examples/social_media_diffusers.py
115-
```
141+
## Examples at a glance
116142

117-
Output highlights:
118-
- **Graph centrality** (eigenvector on the 1-skeleton) ranks the hub (u0) first —
119-
it has the most and heaviest pairwise edges.
120-
- **Bridge detection** (heuristic: community-span x relation weight) surfaces the
121-
{u3, u5, u7} triad as the top cross-community structure — it spans both
122-
communities and carries high group weight.
123-
- **Group cohesion** (geometric mean of internal weight, pair density, and
124-
higher-order support) scores the triad as structurally tight despite
125-
containing no individually prominent member.
126-
127-
These are heuristic scores, not topological invariants. The point is that
128-
graph-only centrality never even sees group-level structures, while SHE makes
129-
them queryable.
130-
131-
## Examples
132-
133-
| Script | Description |
134-
|--------|-------------|
135-
| `examples/social_media_diffusers.py` | Graph vs. simplex ranking on a two-community scenario |
136-
| `examples/eu_email_analysis.ipynb` | Real-data notebook: SNAP EU Email network, temporal bridge/cohesion plots |
137-
| `examples/temporal_diffusion_analysis.ipynb` | Synthetic temporal scenario: bridge formation over three periods |
138-
| `examples/toy_triangle.py` | Smallest nontrivial complex — Hodge Laplacian printout |
139-
| `examples/social_group_lift.py` | Lift a small social graph to simplices via cliques |
140-
| `examples/group_diffusion_demo.py` | Weighted Karate Club diffusion analysis |
143+
| Example | Type | What you learn |
144+
|---------|------|---------------|
145+
| `examples/toy_triangle.py` | Script | Hodge Laplacians on the smallest complex |
146+
| `examples/social_group_lift.py` | Script | Graph-to-simplicial lifting via cliques |
147+
| `examples/social_media_diffusers.py` | Script | Graph centrality vs simplex diffusion on two communities |
148+
| `examples/group_diffusion_demo.py` | Script | Weighted Karate Club diffusion |
149+
| `examples/temporal_diffusion_analysis.ipynb` | Notebook | Bridge formation over three time periods (synthetic) |
150+
| `examples/eu_email_analysis.ipynb` | Notebook | Real SNAP email data, temporal bridge/cohesion plots |
141151

142152
## Experimental modules
143153

@@ -149,6 +159,15 @@ dependencies:
149159
| `src/core/SHESimplicialConvolution.py` | PyTorch | `pip install she[ml]` |
150160
| `src/morse/` | PyTorch, numba, sparse, psutil | `pip install she[morse]` |
151161

162+
## Documentation
163+
164+
| Doc | Purpose |
165+
|-----|---------|
166+
| [Getting Started](docs/tutorials/getting_started.md) | Install, first examples, onboarding path |
167+
| [Social Diffusers Tutorial](docs/tutorials/social_diffusers.md) | Diffusers, bridges, cohesion, temporal |
168+
| [API Overview](docs/api/overview.md) | Public API map with stable-vs-heuristic labels |
169+
| [Social Media Use Case](docs/usecases/social_media_diffusers.md) | Conceptual framing |
170+
152171
## Limitations
153172

154173
This is a **Research Preview**. The API may change between releases.
@@ -161,6 +180,10 @@ This is a **Research Preview**. The API may change between releases.
161180
- Tested with TopoNetX 0.2.x on Python 3.11.
162181
- Not OSI open-source — see License section below.
163182

183+
## Contributing
184+
185+
Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
186+
164187
## License
165188

166189
**Holomathics Non-Commercial License (HNCL) v1.0**

‎docs/README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# SHE Documentation
2+
3+
**SHE** (Simplicial Hyperstructure Engine) is a source-available research library
4+
for modeling and analyzing decorated higher-order relational structures, with a
5+
focus on social/group-level diffusion analysis.
6+
7+
**Status:** Research Preview (v0.1.2) under [HNCL v1.0](../LICENCE.md).
8+
**Canonical package:** `src/she/` — install with `pip install -e .`, import as `import she`.
9+
10+
## Where to start
11+
12+
| If you want to... | Go to |
13+
|---|---|
14+
| Install and run your first example | [Getting Started](tutorials/getting_started.md) |
15+
| Understand the social-analysis features | [Social Diffusers Tutorial](tutorials/social_diffusers.md) |
16+
| See the public API surface | [API Overview](api/overview.md) |
17+
| Read the social-media use case | [Use Cases](usecases/social_media_diffusers.md) |
18+
19+
## Docs map
20+
21+
```
22+
docs/
23+
README.md ← you are here
24+
tutorials/
25+
getting_started.md ← install, first import, first examples
26+
social_diffusers.md ← diffusers, bridges, cohesion, temporal
27+
api/
28+
overview.md ← public API map
29+
usecases/
30+
social_media_diffusers.md
31+
archive/ ← historical materials (not current)
32+
```
33+
34+
## What is stable
35+
36+
The `she` package (`src/she/`) is the public surface:
37+
`SHEHyperstructure`, social analysis functions, temporal windowing, export.
38+
39+
Code under `src/core/` and `src/morse/` is legacy/experimental and not part
40+
of the stable API.

‎docs/api/overview.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# API Overview
2+
3+
Public API surface of the `she` package (v0.1.2). All imports from `import she`.
4+
5+
## Modeling layer
6+
7+
### `SHEHyperstructure`
8+
9+
The central object. A decorated, weighted higher-order relational structure.
10+
11+
```python
12+
hs = SHEHyperstructure("name", config=SHEConfig(max_dimension=2))
13+
hs.add_entity("alice", community="A", role="researcher")
14+
hs.add_relation(["alice", "bob"], weight=1.0, kind="reply", topic="energy")
15+
```
16+
17+
Key methods:
18+
19+
| Method | Purpose |
20+
|---|---|
21+
| `add_entity(id, **attrs)` | Register an entity with arbitrary attributes |
22+
| `add_relation(members, weight, kind, **meta)` | Add a weighted, typed relation |
23+
| `from_records(records)` | Bulk build from list of dicts |
24+
| `from_csv(path)` | Build from CSV file |
25+
| `from_jsonl(path)` | Build from JSON-Lines file |
26+
| `entities` | List of registered entity ids |
27+
| `relations` | List of relation keys (frozensets) |
28+
| `get_entity_attrs(id)` | Entity attribute dict |
29+
| `get_relation_attrs(members)` | Relation attribute dict |
30+
| `summary()` | Dimension counts and totals |
31+
| `complex` | Access the underlying `SHESimplicialComplex` |
32+
33+
### `SHEConfig`
34+
35+
Configuration dataclass. Key fields: `max_dimension`, `spectral_k`.
36+
37+
## Social analysis
38+
39+
All functions take an `SHEHyperstructure` and return interpretable results.
40+
41+
| Function | Returns | Description |
42+
|---|---|---|
43+
| `rank_diffusers(hs, dimension, top_k)` | `List[RankedItem]` | Rank simplices by Hodge diffusion centrality |
44+
| `rank_entity_diffusers(hs, top_k)` | `List[RankedItem]` | Shortcut for dimension=0 |
45+
| `rank_simplex_diffusers(hs, dimension, top_k)` | `List[RankedItem]` | Shortcut for specific dimension |
46+
| `find_bridge_simplices(hs, community_attr, top_k)` | `List[BridgeSimplex]` | Cross-community bridges (heuristic) |
47+
| `group_cohesion(hs, group)` | `CohesionScore` | Structural cohesion composite |
48+
| `rank_influencers(hs, top_k)` | `dict` | Graph centrality vs simplex diffusion |
49+
50+
### Result types
51+
52+
- **`RankedItem`** — `target`, `dimension`, `score`, `metadata`
53+
- **`BridgeSimplex`** — `members`, `dimension`, `communities_spanned`, `bridge_score`, `metadata`
54+
- **`CohesionScore`** — `members`, `score`, `components`
55+
56+
## Temporal
57+
58+
| Function | Description |
59+
|---|---|
60+
| `window(hs, start, end)` | Hard time-range filter, returns new hyperstructure |
61+
| `rolling_windows(hs, window_size, step)` | Sequence of `(start, end, hs)` snapshots |
62+
| `decay_window(hs, reference_time, half_life)` | Exponential decay weighting |
63+
64+
## Export
65+
66+
| Function | Description |
67+
|---|---|
68+
| `ranked_items_to_csv(items, path)` | Export ranked items to CSV |
69+
| `ranked_items_to_json(items, path)` | Export ranked items to JSON |
70+
| `bridges_to_csv(bridges, path)` | Export bridge simplices to CSV |
71+
| `bridges_to_json(bridges, path)` | Export bridge simplices to JSON |
72+
| `cohesion_to_csv(scores, path)` | Export cohesion scores to CSV |
73+
| `cohesion_to_json(scores, path)` | Export cohesion scores to JSON |
74+
75+
All export functions return the string and optionally write to `path`.
76+
77+
## Core engine (lower-level)
78+
79+
These are available but most users should work through `SHEHyperstructure`.
80+
81+
| Class | Purpose |
82+
|---|---|
83+
| `SHESimplicialComplex` | Wraps TopoNetX `SimplicialComplex` |
84+
| `SHEHodgeDiffusion` | Hodge Laplacian computation and diffusion solve |
85+
| `SHEDataLoader` | Graph-to-simplicial lifting |
86+
| `SHEDiffusionVisualizer` | Matplotlib plots |
87+
| `SHEEngine` | Convenience wrapper |
88+
| `DiffusionResult` | Result container from diffusion analysis |
89+
90+
## What is stable vs heuristic
91+
92+
| Feature | Status |
93+
|---|---|
94+
| Hyperstructure construction, ingestion, temporal | Stable for this release |
95+
| Hodge Laplacian computation | Stable (harmonic component only) |
96+
| Diffusion centrality ranking | Stable method, heuristic interpretation |
97+
| Bridge detection | Heuristic score, not a topological invariant |
98+
| Group cohesion | Simple composite, not a formal measure |
99+
| Export | Stable |

docs/internal/archive/CORE-manual.md renamed to docs/archive/CORE-manual.md

File renamed without changes.

docs/internal/archive/FMT-SR-manual.md renamed to docs/archive/FMT-SR-manual.md

File renamed without changes.

docs/internal/archive/README.md renamed to docs/archive/README.md

File renamed without changes.

docs/internal/archive/SHE-ActionList.md renamed to docs/archive/SHE-ActionList.md

File renamed without changes.

docs/internal/archive/SHE_code_audit.md renamed to docs/archive/SHE_code_audit.md

File renamed without changes.

docs/internal/archive/she.toml renamed to docs/archive/she.toml

File renamed without changes.

0 commit comments

Comments
 (0)