helios-network 0.10.1__tar.gz

helios_network-0.10.1/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.1
+Name: helios-network
+Version: 0.10.1
+Summary: Helios Network Python bindings
+Author: Helios
+License: MIT
+Requires-Python: >=3.9
+Provides-Extra: umap
+Requires-Dist: numpy>=1.23; extra == "umap"
+Requires-Dist: scipy>=1.10; extra == "umap"
+Requires-Dist: umap-learn>=0.5.7; extra == "umap"
+Requires-Dist: pynndescent>=0.5.12; extra == "umap"
+Description-Content-Type: text/markdown
+
+# Helios Network (Python)
+
+Python bindings for the Helios Network C core.
+
+## Quick start
+
+```python
+from helios_network import AttributeScope, AttributeType, Network
+
+network = Network(directed=False)
+node_ids = network.add_nodes(3)
+network.add_edges([(node_ids[0], node_ids[1])])
+
+network.define_attribute(AttributeScope.Node, "weight", AttributeType.Double, 1)
+network.nodes["weight"] = 1.0
+
+# Auto-define attributes on assignment
+network.nodes["score"] = 2.5
+
+network.define_attribute(AttributeScope.Network, "title", AttributeType.String, 1)
+network.network["title"] = "demo"
+print(network.graph["title"])
+network["title"] = "demo2"
+
+# Node access
+print(network.nodes[node_ids[0]]["weight"])
+network.nodes[[node_ids[0], node_ids[1]]]["weight"] = [2.0, 3.0]
+
+for node in network.nodes:
+    node["weight"] = 4.0
+```
+
+## Selectors
+
+- `network.nodes[id]` returns a node view
+- `network.nodes[[id1, id2]]` returns a selector for active nodes
+- `network.nodes["attr"]` returns a list of attribute values for active nodes
+- `network.nodes["attr"] = value` assigns a constant to all active nodes
+- `network.nodes[[id1, id2]]["attr"] = [v1, v2]` assigns per-node values
+
+Edge access mirrors node access via `network.edges`, with `network.edges.pairs()` yielding `(source, target)` tuples.
+
+For large generated graphs, avoid materializing Python `(source, target)` tuples:
+
+```python
+from array import array
+
+network.add_nodes(1_000_000)
+network.add_edges_from_arrays(
+    array("I", sources),
+    array("I", targets),
+)
+```
+
+## Network Generators
+
+The Python package exposes native generators as module-level constructors:
+
+```python
+from helios_network import generate_watts_strogatz
+
+network = generate_watts_strogatz(
+    5_000,
+    neighbor_level=2,
+    rewiring_probability=0.01,
+    seed=1,
+)
+```
+
+Available generators include `generate_stochastic_block_model`,
+`generate_barabasi_albert`, `generate_watts_strogatz`,
+`generate_random_geometric`, `generate_waxman`,
+`generate_configuration_model`, and `generate_lattice_2d`.
+
+### Edge indices
+
+```python
+for edge_id, (source, target) in network.edges.with_indices():
+    print(edge_id, source, target)
+```
+
+## Measurements and Community Detection
+
+The Python wrapper exposes the native measurement APIs:
+
+```python
+degree = network.measure_degree(direction="both")
+components = network.measure_connected_components(mode="weak")
+leiden = network.leiden_modularity(
+    resolution=1.0,
+    seed=42,
+    out_node_community_attribute="community",
+)
+```
+
+`leiden_modularity(...)` is an alias for `measure_leiden_modularity(...)`. It
+writes an unsigned-integer node attribute and returns `community_count`,
+`modularity`, and `values_by_node`.
+
+To label only major components for filtering or visualization:
+
+```python
+major = network.label_major_components(
+    mode="weak",
+    max_components=3,
+    min_size=100,
+    out_node_component_attribute="major_component",
+)
+```
+
+Selected components receive rank labels `1..N` by decreasing size. Other nodes
+receive `0` by default.
+
+The Leiden comparison harness in `research/benchmarks/leiden_compare/` uses a
+conda environment file:
+
+```bash
+conda env create -f research/benchmarks/leiden_compare/environment.yml
+conda run -n helios-leiden-compare python -m pip install -e python --no-build-isolation
+conda run -n helios-leiden-compare python research/benchmarks/leiden_compare/compare_leiden.py
+```
+
+## Installation
+
+Standard install:
+
+```bash
+python -m pip install ./python --upgrade
+```
+
+Editable install (recommended during development):
+
+```bash
+python -m pip install -e python --no-build-isolation
+```
+
+`mesonpy` editable builds require `--no-build-isolation`.
+
+If editable install fails, install build tools in the active environment:
+
+```bash
+python -m pip install meson ninja meson-python
+python -m pip install -e python --no-build-isolation
+```
+
+## Optional conversions
+
+NetworkX and igraph conversions are optional. Install when needed:
+
+```bash
+python -m pip install networkx
+python -m pip install igraph
+```
+
+## UMAP export
+
+Install the optional UMAP stack when you want a Helios-ready fuzzy graph or
+kNN graph export:
+
+```bash
+python -m pip install ./python[umap]
+```
+
+```python
+from helios_network import HeliosUMAP
+
+umap_export = HeliosUMAP(
+    n_neighbors=15,
+    min_dist=0.1,
+    build_knn_network=True,
+)
+
+network = umap_export.fit_network(X)
+network.save_bxnet("embedding.bxnet")
+
+# Optional directed kNN export
+umap_export.knn_network_.save_zxnet("embedding-knn.zxnet")
+```
+
+If you want only the UMAP graph construction output for `helios-web-next`
+to lay out from scratch, use the graph-only export path instead:
+
+```python
+graph_network = umap_export.fit_graph_network(X)
+graph_network.save_zxnet("umap-graph.zxnet")
+```
+
+The fit graph export writes:
+
+- node attributes: `umap_embedding`, `_helios_visuals_position`, `umap_mass`
+- edge attribute: `umap_weight`
+- network attributes that let `helios-web-next` auto-enable UMAP force mode on import
+
+The graph-only export writes the same UMAP edge weights and graph metadata, but
+omits `umap_embedding` and `_helios_visuals_position` so `helios-web-next` can
+start its own realtime UMAP-like layout from scratch.
+
+## Examples
+
+From `python/`:
+
+```bash
+python examples/basic_usage.py
+python examples/toroidal_dimensions_table.py
+python examples/toroidal_dimensions_plot.py --skip-plot
+python examples/toroidal_dimensions_plot.py
+python examples/toroidal_dimensions_plot.py --large --skip-plot
+python examples/generate_umap_example_networks.py --sizes 200 2000 20000
+```
+
+`toroidal_dimensions_plot.py` uses `matplotlib` for plotting local dimension curves. Install it with:
+
+```bash
+python -m pip install matplotlib
+```
+
+## Vector attributes
+
+Attributes with dimension > 1 accept vector assignments:
+
+```python
+network.define_attribute(AttributeScope.Node, "i3", AttributeType.Integer, 3)
+network.nodes["i3"] = [1, 2, 3]  # broadcast to all nodes
+network.nodes[[0, 1]]["i3"] = [[4, 5, 6], [7, 8, 9]]
+```

helios_network-0.10.1/README.md

@@ -0,0 +1,225 @@
+# Helios Network (Python)
+
+Python bindings for the Helios Network C core.
+
+## Quick start
+
+```python
+from helios_network import AttributeScope, AttributeType, Network
+
+network = Network(directed=False)
+node_ids = network.add_nodes(3)
+network.add_edges([(node_ids[0], node_ids[1])])
+
+network.define_attribute(AttributeScope.Node, "weight", AttributeType.Double, 1)
+network.nodes["weight"] = 1.0
+
+# Auto-define attributes on assignment
+network.nodes["score"] = 2.5
+
+network.define_attribute(AttributeScope.Network, "title", AttributeType.String, 1)
+network.network["title"] = "demo"
+print(network.graph["title"])
+network["title"] = "demo2"
+
+# Node access
+print(network.nodes[node_ids[0]]["weight"])
+network.nodes[[node_ids[0], node_ids[1]]]["weight"] = [2.0, 3.0]
+
+for node in network.nodes:
+    node["weight"] = 4.0
+```
+
+## Selectors
+
+- `network.nodes[id]` returns a node view
+- `network.nodes[[id1, id2]]` returns a selector for active nodes
+- `network.nodes["attr"]` returns a list of attribute values for active nodes
+- `network.nodes["attr"] = value` assigns a constant to all active nodes
+- `network.nodes[[id1, id2]]["attr"] = [v1, v2]` assigns per-node values
+
+Edge access mirrors node access via `network.edges`, with `network.edges.pairs()` yielding `(source, target)` tuples.
+
+For large generated graphs, avoid materializing Python `(source, target)` tuples:
+
+```python
+from array import array
+
+network.add_nodes(1_000_000)
+network.add_edges_from_arrays(
+    array("I", sources),
+    array("I", targets),
+)
+```
+
+## Network Generators
+
+The Python package exposes native generators as module-level constructors:
+
+```python
+from helios_network import generate_watts_strogatz
+
+network = generate_watts_strogatz(
+    5_000,
+    neighbor_level=2,
+    rewiring_probability=0.01,
+    seed=1,
+)
+```
+
+Available generators include `generate_stochastic_block_model`,
+`generate_barabasi_albert`, `generate_watts_strogatz`,
+`generate_random_geometric`, `generate_waxman`,
+`generate_configuration_model`, and `generate_lattice_2d`.
+
+### Edge indices
+
+```python
+for edge_id, (source, target) in network.edges.with_indices():
+    print(edge_id, source, target)
+```
+
+## Measurements and Community Detection
+
+The Python wrapper exposes the native measurement APIs:
+
+```python
+degree = network.measure_degree(direction="both")
+components = network.measure_connected_components(mode="weak")
+leiden = network.leiden_modularity(
+    resolution=1.0,
+    seed=42,
+    out_node_community_attribute="community",
+)
+```
+
+`leiden_modularity(...)` is an alias for `measure_leiden_modularity(...)`. It
+writes an unsigned-integer node attribute and returns `community_count`,
+`modularity`, and `values_by_node`.
+
+To label only major components for filtering or visualization:
+
+```python
+major = network.label_major_components(
+    mode="weak",
+    max_components=3,
+    min_size=100,
+    out_node_component_attribute="major_component",
+)
+```
+
+Selected components receive rank labels `1..N` by decreasing size. Other nodes
+receive `0` by default.
+
+The Leiden comparison harness in `research/benchmarks/leiden_compare/` uses a
+conda environment file:
+
+```bash
+conda env create -f research/benchmarks/leiden_compare/environment.yml
+conda run -n helios-leiden-compare python -m pip install -e python --no-build-isolation
+conda run -n helios-leiden-compare python research/benchmarks/leiden_compare/compare_leiden.py
+```
+
+## Installation
+
+Standard install:
+
+```bash
+python -m pip install ./python --upgrade
+```
+
+Editable install (recommended during development):
+
+```bash
+python -m pip install -e python --no-build-isolation
+```
+
+`mesonpy` editable builds require `--no-build-isolation`.
+
+If editable install fails, install build tools in the active environment:
+
+```bash
+python -m pip install meson ninja meson-python
+python -m pip install -e python --no-build-isolation
+```
+
+## Optional conversions
+
+NetworkX and igraph conversions are optional. Install when needed:
+
+```bash
+python -m pip install networkx
+python -m pip install igraph
+```
+
+## UMAP export
+
+Install the optional UMAP stack when you want a Helios-ready fuzzy graph or
+kNN graph export:
+
+```bash
+python -m pip install ./python[umap]
+```
+
+```python
+from helios_network import HeliosUMAP
+
+umap_export = HeliosUMAP(
+    n_neighbors=15,
+    min_dist=0.1,
+    build_knn_network=True,
+)
+
+network = umap_export.fit_network(X)
+network.save_bxnet("embedding.bxnet")
+
+# Optional directed kNN export
+umap_export.knn_network_.save_zxnet("embedding-knn.zxnet")
+```
+
+If you want only the UMAP graph construction output for `helios-web-next`
+to lay out from scratch, use the graph-only export path instead:
+
+```python
+graph_network = umap_export.fit_graph_network(X)
+graph_network.save_zxnet("umap-graph.zxnet")
+```
+
+The fit graph export writes:
+
+- node attributes: `umap_embedding`, `_helios_visuals_position`, `umap_mass`
+- edge attribute: `umap_weight`
+- network attributes that let `helios-web-next` auto-enable UMAP force mode on import
+
+The graph-only export writes the same UMAP edge weights and graph metadata, but
+omits `umap_embedding` and `_helios_visuals_position` so `helios-web-next` can
+start its own realtime UMAP-like layout from scratch.
+
+## Examples
+
+From `python/`:
+
+```bash
+python examples/basic_usage.py
+python examples/toroidal_dimensions_table.py
+python examples/toroidal_dimensions_plot.py --skip-plot
+python examples/toroidal_dimensions_plot.py
+python examples/toroidal_dimensions_plot.py --large --skip-plot
+python examples/generate_umap_example_networks.py --sizes 200 2000 20000
+```
+
+`toroidal_dimensions_plot.py` uses `matplotlib` for plotting local dimension curves. Install it with:
+
+```bash
+python -m pip install matplotlib
+```
+
+## Vector attributes
+
+Attributes with dimension > 1 accept vector assignments:
+
+```python
+network.define_attribute(AttributeScope.Node, "i3", AttributeType.Integer, 3)
+network.nodes["i3"] = [1, 2, 3]  # broadcast to all nodes
+network.nodes[[0, 1]]["i3"] = [[4, 5, 6], [7, 8, 9]]
+```

helios_network-0.10.1/docs/API.md

@@ -0,0 +1,142 @@
+# Helios Network Python API
+
+## Overview
+
+The Python bindings expose a high-level `Network` class with convenient node/edge/network selectors. Attributes are backed by the native Helios core and can be created explicitly or implicitly.
+
+Key concepts:
+- `network.nodes`, `network.edges`: active-only selectors that allow iteration and batch attribute assignment.
+- `network.network` / `network.graph`: network-scope attribute access (single record).
+- `network["attr"]`: shorthand for network-scope attribute access.
+
+## Creating Networks
+
+```python
+from helios_network import Network
+
+network = Network(directed=False)
+```
+
+### Constructor
+
+`Network(directed: bool = False, node_capacity: int | None = None, edge_capacity: int | None = None)`
+
+- `directed`: If `True`, edges are directed.
+- `node_capacity`, `edge_capacity`: Optional initial capacities.
+
+## Nodes and Edges
+
+### Iteration
+
+```python
+for node in network.nodes:
+    print(node.id)
+
+for edge in network.edges:
+    print(edge.id, edge.endpoints)
+```
+
+### Edge pairs
+
+```python
+for source, target in network.edges.pairs():
+    print(source, target)
+```
+
+### Edge indices + endpoints
+
+```python
+for edge_id, (source, target) in network.edges.with_indices():
+    print(edge_id, source, target)
+```
+
+## Attributes
+
+### Auto-definition
+
+Assigning to an unknown attribute name will create it automatically based on the assigned value.
+
+```python
+network.nodes["weight"] = 1.0          # creates Double attribute, dimension 1
+network.nodes["i3"] = [1, 2, 3]         # creates Integer attribute, dimension 3
+network.edges["weight"] = 0.5          # creates Double attribute on edges
+network["title"] = "demo"              # creates String attribute on network scope
+```
+
+### Explicit definition
+
+```python
+from helios_network import AttributeScope, AttributeType
+
+network.define_attribute(AttributeScope.Node, "score", AttributeType.Double, 1)
+```
+
+### Collection helpers
+
+```python
+network.nodes.define_attribute("score", float)
+network.edges.define_attribute("weight", AttributeType.Double)
+network.network.define_attribute("title", str)
+```
+
+### Attribute access
+
+```python
+# Single node
+network.nodes[node_id]["score"] = 1.5
+value = network.nodes[node_id]["score"]
+
+# Selector
+network.nodes[[id1, id2]]["score"] = [1.0, 2.0]
+values = network.nodes[[id1, id2]]["score"]
+
+# All nodes
+network.nodes["score"] = 2.0
+```
+
+### Vector attributes (dimension > 1)
+
+```python
+network.nodes["i3"] = [1, 2, 3]  # broadcast
+network.nodes[[id1, id2]]["i3"] = [[1, 2, 3], [4, 5, 6]]
+```
+
+NumPy arrays with shape `(dim,)` or `(count, dim)` are supported when NumPy is installed.
+
+## Categorical attributes
+
+```python
+network.nodes["label"] = ["a", "b", "a"]
+network.categorize_attribute(AttributeScope.Node, "label")
+
+mapping = network.get_category_dictionary(AttributeScope.Node, "label")
+# mapping: {"a": 0, "b": 1, ...}
+
+network.set_category_dictionary(AttributeScope.Node, "label", {"x": 10, "y": 11}, remap_existing=True)
+network.decategorize_attribute(AttributeScope.Node, "label")
+```
+
+## Serialization
+
+```python
+network.save_xnet("graph.xnet")
+network.save_bxnet("graph.bxnet")
+network.save_zxnet("graph.zxnet")
+network.save_gml("graph.gml")
+network.save_node_link_json("graph.json")
+
+loaded = read_xnet("graph.xnet")
+loaded_gml = read_gml("graph.gml")
+loaded_json = read_node_link_json("graph.json")
+```
+
+## Conversions
+
+```python
+from helios_network import to_networkx, from_networkx
+
+nx_graph = to_networkx(network)
+network2 = from_networkx(nx_graph)
+```
+
+`to_igraph` / `from_igraph` are available when `igraph` is installed.

helios_network-0.10.1/docs/PYDOC.md

@@ -0,0 +1,77 @@
+# Helios Network Python Docstrings
+
+Below is a summary of the main classes and methods exposed in the Python API.
+This complements the inline docstrings and `python/docs/API.md`.
+
+## Network
+
+`Network(directed=False, node_capacity=None, edge_capacity=None)`
+
+- Creates a network wrapper around the native core.
+- Properties:
+- `nodes`, `edges`: active selectors
+- `network`, `graph`, `attributes`: network-scope selectors
+ - `__getitem__(name)` / `__setitem__(name, value)`: network-scope shorthand
+
+### Common methods
+
+- `node_count() -> int`
+- `edge_count() -> int`
+- `add_nodes(count) -> list[int]`
+- `remove_nodes(indices) -> bool`
+- `add_edges([(from, to), ...]) -> list[int]`
+- `remove_edges(indices) -> bool`
+- `node_indices() -> list[int]`
+- `edge_indices() -> list[int]`
+- `edges_with_indices() -> list[(edge_id, (source, target))]`
+
+### Attribute methods
+
+- `define_attribute(scope, name, type, dimension=1) -> bool`
+ - `nodes.define_attribute(name, type, dimension=1) -> bool`
+ - `edges.define_attribute(name, type, dimension=1) -> bool`
+ - `network.define_attribute(name, type, dimension=1) -> bool`
+- `attribute_info(scope, name) -> dict`
+- `set_attribute_value(scope, name, index, value) -> bool`
+- `get_attribute_value(scope, name, index)`
+
+### Categorical helpers
+
+- `categorize_attribute(scope, name, sort_order=None, missing_label=None) -> bool`
+- `decategorize_attribute(scope, name, missing_label=None) -> bool`
+- `get_category_dictionary(scope, name) -> dict[label, id]`
+- `set_category_dictionary(scope, name, mapping_or_pairs, remap_existing=True) -> bool`
+
+### Serialization
+
+- `save_xnet(path)`
+- `save_bxnet(path)`
+- `save_zxnet(path, compression=6)`
+- `save_gml(path)`
+- `save_node_link_json(path)`
+- `read_gml(path)`
+- `read_node_link_json(path)`
+
+## NodeCollection / EdgeCollection
+
+Selectors for active nodes/edges. Support iteration and vectorized assignment.
+
+### Common behaviors
+
+- `collection[id]` -> `NodeView` / `EdgeView`
+- `collection[[ids]]` -> selector for multiple items
+- `collection["attr"]` -> list of values
+- `collection["attr"] = value` -> broadcast or per-item assignment
+
+### Convenience
+
+- `nodes.define_attribute(name, type, dimension=1)`
+- `edges.define_attribute(name, type, dimension=1)`
+- `network.define_attribute(name, type, dimension=1)`
+
+## NodeView / EdgeView / NetworkView
+
+Simple wrappers around a single item (node, edge, network).
+
+- `node["attr"]` / `edge["attr"]` / `network["attr"]`
+- `edge.endpoints -> (source, target)`

helios_network-0.10.1/examples/attributes.py

@@ -0,0 +1,16 @@
+from helios_network import AttributeScope, AttributeType, Network
+
+network = Network(directed=True)
+node_ids = network.add_nodes(3)
+
+network.define_attribute(AttributeScope.Node, "weight", AttributeType.Double, 1)
+network.define_attribute(AttributeScope.Node, "label", AttributeType.String, 1)
+
+network.nodes["weight"] = 1.0
+network.nodes["label"] = [f"node-{idx}" for idx in range(len(node_ids))]
+
+network.nodes[[node_ids[0], node_ids[2]]]["weight"] = [2.5, 3.5]
+
+for node in network.nodes:
+    print(node)
+    print(node.id, node["weight"], node["label"])

helios_network-0.10.1/examples/basic_usage.py

@@ -0,0 +1,14 @@
+from helios_network import Network
+
+network = Network(directed=False)
+node_ids = network.add_nodes(4)
+edge_ids = network.add_edges([
+    (node_ids[0], node_ids[1]),
+    (node_ids[1], node_ids[2]),
+    (node_ids[2], node_ids[3]),
+])
+
+print("nodes:", node_ids)
+print("edges:", edge_ids)
+print("node_count:", network.node_count())
+print("edge_count:", network.edge_count())