🚀 Quickstart
========================================

Common tasks and minimal examples. Copy and run.

Tasks
-----

- Create and query: :doc:`api/hypergraphx.core`
- Load and save: :doc:`api/hypergraphx.readwrite`
- Measures: :doc:`api/hypergraphx.measures`
- Projections: :doc:`api/hypergraphx.representations`
- Matrices: :doc:`api/hypergraphx.linalg`

Core classes
------------

- ``hypergraphx.Hypergraph`` (undirected)
- ``hypergraphx.DirectedHypergraph``
- ``hypergraphx.TemporalHypergraph``
- ``hypergraphx.MultiplexHypergraph``

Create a hypergraph
-------------------

.. code-block:: python

   import hypergraphx as hgx

   hg = hgx.Hypergraph(edge_list=[(0, 1, 2), (2, 3)], weighted=True, weights=[1.0, 2.0])
   hg.add_edge((3, 4), weight=1.5, metadata={"kind": "tri"})
   print(hg)

.. note::

   Hypergraphs are weighted by default. If you want an unweighted hypergraph, pass
   ``weighted=False`` (unweighted graphs only accept ``weight=None`` or ``weight=1``).

Directed / temporal / multiplex
-------------------------------

.. code-block:: python

   dh = hgx.DirectedHypergraph(edge_list=[((0, 1), (2,)), ((2,), (3,))])
   th = hgx.TemporalHypergraph(edge_list=[(0, (0, 1)), (1, (1, 2))])
   mx = hgx.MultiplexHypergraph(edge_list=[(0, 1), (1, 2)], edge_layer=["L1", "L2"])

   # Directed in/out degrees
   dh.in_degree(2)
   dh.out_degree(2)

Common queries
--------------

.. code-block:: python

   hg.num_nodes()
   hg.num_edges()
   hg.get_edges()
   hg.get_incident_edges(2)
   hg.degree(2)
   hg.get_edge_metadata((0, 1, 2))

.. tip::

   For a smaller API surface, start with ``hypergraphx.core`` and ``hypergraphx.readwrite``.

Common patterns
---------------

.. code-block:: python

   # Build -> analyze -> save
   hg = hgx.Hypergraph(edge_list=[(0, 1), (1, 2, 3)])
   seq = degree_sequence(hg)
   hgx.save_hypergraph(hg, "graph.json")

Conversions
-----------

.. code-block:: python

   # Drop direction, time, or layer information
   dh = hgx.DirectedHypergraph(edge_list=[((0, 1), (2,))], weighted=True, weights=[2.0])
   th = hgx.TemporalHypergraph(edge_list=[(0, (0, 1)), (1, (0, 1))], weighted=True, weights=[1.0, 2.0])
   mx = hgx.MultiplexHypergraph(edge_list=[(0, 1), (0, 1)], edge_layer=["L1", "L2"], weighted=True, weights=[1.0, 2.0])

   dh.to_hypergraph()  # merges source/target, sums weights
   th.to_hypergraph()  # drops time, sums weights
   mx.to_hypergraph()  # drops layer, sums weights

Load and save
-------------

.. code-block:: python

   hgx.save_hypergraph(hg, "graph.json")
   hg2 = hgx.load_hypergraph("graph.json")

   # Prefer the compact HGX format for larger local files.
   hgx.save_hypergraph(hg, "graph.hgx", fmt="pickle")
   hg3 = hgx.load_hypergraph("graph.hgx")

Remote datasets
---------------

Hypergraphx can load datasets from the Hypergraphx-data catalog by name.
Remote datasets are downloaded and cached locally by default under
``~/.cache/hypergraphx/datasets``; set ``store=False`` to load without keeping
a local copy, or pass ``cache_dir=...`` to choose a different cache location.

.. code-block:: python

   import hypergraphx as hgx

   # List catalog entries with tags/categories and basic sizes.
   datasets = hgx.list_remote_datasets()
   print(datasets[0]["name"], datasets[0]["tags"])

   # Search without downloading hypergraphs.
   biology = hgx.search_remote_datasets(
       query="biology",
       tags=["Undirected"],
   )

   # Inspect the full catalog metadata for one dataset.
   info = hgx.get_remote_dataset_info("zoo")
   print(info["description"], info["license"])

   # Download and cache a dataset file without loading it.
   path = hgx.download_remote_dataset("zoo")
   H = hgx.load_hypergraph(path)

   # Download multiple datasets and inspect per-dataset results.
   results = hgx.download_remote_datasets(
       ["zoo", "contacts-hospital"],
       continue_on_error=True,
   )
   for name, result in results.items():
       print(name, result["status"], result["path"], result["error"])

   # Load a dataset by name. The compact ``"hgx"`` format is the default.
   H = hgx.load_hypergraph_from_server("zoo")

   # Override the cache directory or force a fresh download.
   H = hgx.load_hypergraph_from_server(
       "zoo",
       cache_dir="./hgx_datasets",
       overwrite=True,
   )

   # Iterate lazily over matching remote datasets.
   for H, info in hgx.iter_remote_hypergraphs(
       ["Undirected", "Temporal"],
       include_metadata=True,
   ):
       print(info["name"], H.num_nodes(), H.num_edges())

   # Or iterate over an explicit list of dataset names.
   for H in hgx.iter_remote_hypergraphs(names=["zoo", "Marvel"]):
       print(H.num_nodes(), H.num_edges())

.. note::

   The current dataset server may require ``verify_ssl=False`` because of its
   certificate chain. This is the default for the remote dataset helpers. If the
   server certificate is fixed, pass ``verify_ssl=True`` to enforce normal TLS
   verification.

Projections and matrices
------------------------

.. code-block:: python

   from hypergraphx.linalg import adjacency_matrix
   from hypergraphx.representations.projections import clique_projection

   A = adjacency_matrix(hg)
   G = clique_projection(hg)

Random generation
-----------------

Use ``random_hypergraph`` to sample a simple random hypergraph with exact
unique-edge counts by size. Requests that exceed the number of possible
combinations are rejected.

.. code-block:: python

   from hypergraphx.generation import random_hypergraph

   hg_sample = random_hypergraph(10, {2: 20, 3: 10}, seed=0)

For dense requests, ``random_hypergraph`` switches from rejection sampling to
direct combination sampling to avoid slowdown near saturation. Tune this with
``dense_threshold`` and ``max_tries_factor`` if needed.

Use ``configuration_model`` to randomize a hypergraph with a
configuration-model-style MCMC sampler.

.. code-block:: python

   from hypergraphx.generation import configuration_model

   hg_rand = configuration_model(hg, n_steps=500, label="edge", seed=0)

The ``duplicate_output`` parameter controls how repeated sampled hyperedges are
handled:

- ``"merge"`` (default): collapse duplicates into a simple hypergraph
- ``"count"``: return a weighted hypergraph whose edge weights equal sampled multiplicities
- ``"error"``: raise an error if repeated sampled hyperedges occur

.. code-block:: python

   hg_rand = configuration_model(hg, n_steps=500, duplicate_output="merge", seed=0)
   hg_counts = configuration_model(hg, n_steps=500, duplicate_output="count", seed=0)

Measures
--------

.. code-block:: python

   from hypergraphx.measures.degree import degree_sequence
   from hypergraphx.measures.shortest_paths import calc_ho_shortest_paths
   seq = degree_sequence(hg)
   paths = calc_ho_shortest_paths(hg)

API map
-------

- Core classes: ``hypergraphx.core``
- Read/write: ``hypergraphx.readwrite``
- Measures: ``hypergraphx.measures``
- Representations: ``hypergraphx.representations``
- Linear algebra: ``hypergraphx.linalg``
- Filters: ``hypergraphx.filters``
- Motifs: ``hypergraphx.motifs``
- Dynamics: ``hypergraphx.dynamics``
- Communities: ``hypergraphx.communities``
- Utils: ``hypergraphx.utils``

Exceptions
----------

All custom exceptions inherit from ``HypergraphxError``. Most also inherit from
``ValueError`` (``ReadwriteError`` inherits from ``RuntimeError``).

.. code-block:: python

   from hypergraphx import MissingNodeError

   try:
       hg.get_incident_edges("missing")
   except MissingNodeError:
       pass

Logging (optional)
------------------

Hypergraphx uses the standard logging module. To see info-level logs:

.. code-block:: python

   import logging

   logging.basicConfig(level=logging.INFO)