Skip to content

Helios Network Native C API

Native core reference

The C API is the native surface behind the WASM and Python bindings. Functions are grouped by lifecycle, topology, attributes, selectors, serialization, and measurements.

Network Lifecycle

Allocation, destruction, version, and graph-wide metadata helpers.

function CXFreeNetwork Releases all resources owned by a network. function CXNetworkBuildFilteredSubgraph Builds an induced filtered subgraph from optional node/edge filters. - `nodeFilter` / `edgeFilter` may be NULL to indicate "all active". - Node output is always active-only. - Edge output is always active-only and induced by the resulting node set (edges with at least one endpoint outside `outNodeSelector` are removed). - Output order follows native active index order. function CXNetworkGenerateBarabasiAlbert Creates a Barabasi-Albert preferential-attachment graph. function CXNetworkGenerateConfigurationModel Creates a graph with the requested degree sequence using the configuration model. function CXNetworkGenerateLattice2D Creates a two-dimensional lattice graph. function CXNetworkGenerateRandomGeometric Creates a random geometric graph using random 2D positions and a radius cutoff. function CXNetworkGenerateStochasticBlockModel Creates a stochastic block model graph from block sizes and a flattened block-to-block probability matrix. function CXNetworkGenerateWattsStrogatz Creates a Watts-Strogatz small-world graph. function CXNetworkGenerateWaxman Creates a Waxman random graph using distance-weighted edge probabilities. function CXNetworkIsDirected Returns CXTrue when the network treats edges as directed. function CXNewNetwork Allocates a new network with default capacities. function CXNewNetworkWithCapacity Allocates a new network with explicit node/edge capacities.

Topology

Node, edge, neighbor, compaction, and topology mutation APIs.

function CXNetworkAddEdges Inserts the provided edges, writing the new indices to `outIndices` when supplied. Edges are expressed as contiguous (from,to) pairs. function CXNetworkAddNodes Appends `count` new nodes to the network. When `outIndices` is non-null it receives the indices assigned to the created nodes. function CXNetworkCollectNeighbors Collects unique one-hop neighbors for one or more source nodes. - `sourceNodes` can contain any node ids; inactive/out-of-range entries are ignored. - `direction` controls traversal for directed graphs (`out`, `in`, `both`). - `includeSourceNodes` controls whether source nodes can appear in `outNodeSelector`. - `outEdgeSelector` is optional; pass NULL to skip edge collection. function CXNetworkCollectNeighborsAtLevel Collects neighbors at exactly the given concentric level (shortest-path hop distance). - `level == 0` refers to the source set itself. - `includeSourceNodes` only affects whether level-0 source nodes are included. - `outEdgeSelector` is optional; pass NULL to skip edge collection. function CXNetworkCollectNeighborsUpToLevel Collects neighbors up to (and including) the given concentric level. - `maxLevel == 0` returns only the source set when `includeSourceNodes` is true. - `outEdgeSelector` is optional; pass NULL to skip edge collection. function CXNetworkCompact Compacts the network so that node and edge indices become contiguous starting at zero and capacities shrink to match the number of active elements. When `nodeOriginalIndexAttr` or `edgeOriginalIndexAttr` are provided, the function records the previous indices in attributes of type `CXUnsignedIntegerAttributeType`. Returns CXFalse on allocation failure or when incompatible attributes are encountered. function CXNetworkEdgeCapacity Returns the allocated edge capacity. function CXNetworkEdgeCount Returns the number of active edges currently stored. function CXNetworkEdgeFreeListCapacity Returns the allocated edge free-list capacity (reserved slots). function CXNetworkEdgeFreeListCount Returns the current edge free-list size (recycled indices). function CXNetworkGetEdgeValidRange Returns the min/max active edge indices as [start,end). function CXNetworkGetNodeValidRange Returns the min/max active node indices as [start,end). function CXNetworkInNeighbors Returns the inbound neighbor container for the given node. function CXNetworkNodeCapacity Returns the allocated node capacity (useful for buffer sizing). function CXNetworkNodeCount Returns the number of active nodes currently stored. function CXNetworkNodeFreeListCapacity Returns the allocated node free-list capacity (reserved slots). function CXNetworkNodeFreeListCount Returns the current node free-list size (recycled indices). function CXNetworkOutNeighbors Returns the outbound neighbor container for the given node. function CXNetworkRemoveEdges Removes the supplied edges from the network. function CXNetworkRemoveNodes Removes the supplied nodes, reclaiming their indices for future use.

Attributes

Attribute definition, lookup, categorization, and multi-category APIs.

function CXAttributeData Returns a pointer to the raw backing buffer for an attribute (or NULL when missing). function CXAttributeInterpolateFloatBuffer Interpolates a float attribute buffer toward target values and bumps the attribute version. Returns CXTrue when further interpolation steps are recommended based on minDisplacementRatio. function CXAttributeStride Returns the byte stride between consecutive entries of an attribute. function CXAttributeVersion Returns the version counter for an attribute descriptor. function CXNetworkBumpEdgeAttributeVersion Manually bumps an edge attribute version and returns the new value. function CXNetworkBumpNetworkAttributeVersion Manually bumps a network attribute version and returns the new value. function CXNetworkBumpNodeAttributeVersion Manually bumps a node attribute version and returns the new value. function CXNetworkCategorizeAttribute Converts a string attribute into category ids using the requested sort policy. function CXNetworkClearMultiCategoryEntry Clears all category ids and weights for one multi-category entry. function CXNetworkCopyNodeAttributesToEdgeAttributes Copies node attributes into an edge attribute buffer using the network's topology. `endpointMode` controls which endpoint is copied: -1 = both, 0 = source only, 1 = destination only. When copying a single endpoint and `duplicateSingleEndpoint` is true, the chosen endpoint is written twice sequentially (for double-width edge attributes). function CXNetworkDecategorizeAttribute Converts category ids back to string labels for the named attribute. function CXNetworkDefineEdgeAttribute Declares an edge attribute backing buffer. function CXNetworkDefineMultiCategoryAttribute Defines a multi-category attribute with optional per-entry weights. function CXNetworkDefineNetworkAttribute Declares a network-level attribute backing buffer. function CXNetworkDefineNodeAttribute Declares a node attribute backing buffer. Dimension defaults to 1. function CXNetworkEdgeAttributeCount Returns the number of edge attributes currently defined on the network. function CXNetworkEdgeAttributeNameAt Returns the edge attribute name at `index`, or NULL when out of range. function CXNetworkGetAttributeCategoryDictionary Returns the category dictionary for a categorical attribute, or NULL when unavailable. function CXNetworkGetAttributeCategoryDictionaryCount Returns how many category entries are defined for a categorical attribute. function CXNetworkGetAttributeCategoryDictionaryEntries Copies category ids and labels into caller-provided arrays. function CXNetworkGetEdgeAttribute Fetches an edge attribute descriptor by name. function CXNetworkGetEdgeAttributeBuffer Returns a pointer to the raw edge attribute buffer for the named attribute. function CXNetworkGetMultiCategoryEntryCount Returns the number of category entries stored for a multi-category attribute. function CXNetworkGetMultiCategoryEntryRange Returns the [start,end) range for one entry inside the packed multi-category buffers. function CXNetworkGetMultiCategoryIds Returns the packed category id buffer for a multi-category attribute. function CXNetworkGetMultiCategoryOffsetCount Returns the number of offsets stored for a multi-category attribute. function CXNetworkGetMultiCategoryOffsets Returns the packed offsets buffer for a multi-category attribute. function CXNetworkGetMultiCategoryWeights Returns the packed weight buffer, or NULL when the attribute is unweighted. function CXNetworkGetNetworkAttribute Fetches a network attribute descriptor by name. function CXNetworkGetNetworkAttributeBuffer Returns a pointer to the raw network attribute buffer for the named attribute. function CXNetworkGetNodeAttribute Fetches a node attribute descriptor by name. function CXNetworkGetNodeAttributeBuffer Returns a pointer to the raw node attribute buffer for the named attribute. function CXNetworkMultiCategoryHasWeights Returns CXTrue when the multi-category attribute stores per-entry weights. function CXNetworkNetworkAttributeCount Returns the number of network attributes currently defined on the network. function CXNetworkNetworkAttributeNameAt Returns the network attribute name at `index`, or NULL when out of range. function CXNetworkNodeAttributeCount Returns the number of node attributes currently defined on the network. function CXNetworkNodeAttributeNameAt Returns the node attribute name at `index` in the internal dictionary iteration order, or NULL when out of range. function CXNetworkRemoveEdgeAttribute Removes a sparse edge attribute and its storage. function CXNetworkRemoveNetworkAttribute Removes a sparse network attribute and its storage. function CXNetworkRemoveNodeAttribute Removes a sparse node attribute and its storage. function CXNetworkSetAttributeCategoryDictionary Replaces or remaps the category dictionary for a categorical attribute. function CXNetworkSetMultiCategoryBuffers Replaces the packed offset/id/weight buffers for a multi-category attribute. function CXNetworkSetMultiCategoryEntry Writes one entry of a multi-category attribute using category ids. function CXNetworkSetMultiCategoryEntryByLabels Writes one entry of a multi-category attribute using category labels.

Buffers And Versions

Direct buffer access and version counters used by high-performance integrations.

function CXNetworkActiveEdgeIndexCount Returns the number of entries in the stable active edge index buffer. function CXNetworkActiveEdgeIndices Returns a stable buffer of active edge indices in native active order. function CXNetworkActiveNodeIndexCount Returns the number of entries in the stable active node index buffer. function CXNetworkActiveNodeIndices Returns a stable buffer of active node indices in native active order. function CXNetworkEdgeActivityBuffer Provides a pointer to the edge activity bitmap. function CXNetworkEdgesBuffer Returns a pointer to the flattened edge buffer `[from, to, ...]`. function CXNetworkEdgeTopologyVersion Returns the edge topology version. function CXNetworkIsEdgeActive Returns CXTrue if the edge index is active. function CXNetworkIsNodeActive Returns CXTrue if the given node index is currently active. function CXNetworkNodeActivityBuffer Provides a pointer to the node activity bitmap in linear memory. function CXNetworkNodeTopologyVersion Returns the node topology version (increments on topology edits and repacks). function CXNetworkPromoteActiveEdgesForNodesToRenderEnd Moves active edges incident to the supplied active nodes to the end of the native active edge order. function CXNetworkPromoteActiveEdgesToRenderEnd Moves active edge indices to the end of the native active order, preserving batch order. function CXNetworkPromoteActiveNodesToRenderEnd Moves active node indices to the end of the native active order, preserving batch order. function CXNetworkVersionString Returns the semantic version string for the compiled library (e.g. "1.2.3").

Selectors

Node and edge selector containers used for filtering and set operations.

function CXEdgeSelectorClear Clears all indices from an edge selector without releasing its capacity. function CXEdgeSelectorCount Returns how many indices are currently stored in the selector. function CXEdgeSelectorCreate Creates a selector object for edges. function CXEdgeSelectorData Returns a pointer to the selector's index data. function CXEdgeSelectorDestroy Releases all heap memory associated with an edge selector. function CXEdgeSelectorFillAll Populates the selector with every active edge. function CXEdgeSelectorFillFromArray Fills the selector with the provided edge indices. function CXEdgeSelectorFilterActive Removes invalid/inactive indices in-place from an edge selector. function CXEdgeSelectorFilterByNodes Keeps only active edges whose endpoints are both present in `nodeSelector`. function CXEdgeSelectorIntersect Intersects an edge selector in-place with another selector (active indices only). function CXNodeSelectorClear Clears all indices from a node selector without releasing its capacity. function CXNodeSelectorCount Returns how many indices are currently stored in the selector. function CXNodeSelectorCreate Creates a selector object for nodes with an optional initial capacity. function CXNodeSelectorData Returns a pointer to the selector's contiguous index data. function CXNodeSelectorDestroy Releases all heap memory associated with a node selector. function CXNodeSelectorFillAll Populates the selector with every active node. function CXNodeSelectorFillFromArray Fills the selector with the provided node indices. function CXNodeSelectorFilterActive Removes invalid/inactive indices in-place from a node selector. function CXNodeSelectorIntersect Intersects a node selector in-place with another selector (active indices only).

Queries

Query parser and selector APIs.

function CXNetworkQueryLastErrorMessage Returns the most recent query parser/evaluator error message for this thread. function CXNetworkQueryLastErrorOffset Returns the byte offset for the most recent query parser/evaluator error. function CXNetworkSelectEdgesByQuery Evaluates a query string against edges, populating the provided edge selector. function CXNetworkSelectNodesByQuery Evaluates a query string against the network, populating the provided selector. Returns CXFalse on parse or evaluation errors. Use CXNetworkQueryLastError* to retrieve details about the last failure.

Serialization

Readers and writers for BXNet, ZXNet, XNet, GML, and node-link JSON.

function CXNetworkReadBXNet Reads an uncompressed BXNet file from disk. function CXNetworkReadGML Reads a graph from a GML file. Accepts standard GML and a looser dialect that tolerates quoted keys and unquoted scalar strings. @param path Path to the `.gml` file on disk. @return Newly allocated network when successful, otherwise NULL. function CXNetworkReadGT Reads a graph-tool `.gt` binary graph file. Supports the v1 graph-tool wire format, including endian-aware topology loading and the scalar/vector property-map types that map cleanly to Helios attributes. Unsupported or lossy property maps are skipped and reported via `CXNetworkSerializationLastWarningMessage()`. @param path Path to the `.gt` file on disk. @return Newly allocated network when successful, otherwise NULL. function CXNetworkReadXNet Reads a graph from an `.xnet` (XNET 1.0.0 or legacy) container. @param path Path to the XNET file on disk. @return Newly allocated network when successful, otherwise NULL. function CXNetworkReadZXNet Reads a BGZF-compressed ZXNet file from disk. function CXNetworkSerializationLastWarningMessage Returns the last non-fatal serialization warning emitted by a save/load helper. function CXNetworkSerializationWarningAppend Appends a formatted message to the shared serialization warning buffer. function CXNetworkSerializationWarningClear Clears the shared serialization warning buffer. function CXNetworkWriteActiveEdgeNodeAttributes Writes `componentsPerNode` values for each endpoint of active edges from the provided node attribute buffer into a caller-managed destination. Values are copied verbatim; the caller controls element width (`componentSizeBytes`) and must ensure the typed views line up with the provided byte offsets. Returns the number of edges that would be written; when `dstCapacityEdges` is too small, the required count is returned and no writes occur. function CXNetworkWriteActiveEdges Writes active edge indices into caller-provided storage. When `capacity` is insufficient the required size is returned and no writes occur. function CXNetworkWriteActiveEdgeSegments Writes two position vectors per active edge directly into the provided buffer. `componentsPerNode` describes how many floats to copy per endpoint (commonly 4 for vec4 data). Returns the number of edges that would be written; when `dstCapacityEdges` is too small, the required count is returned and no writes occur. function CXNetworkWriteActiveNodes Writes active node indices into caller-provided storage. When `capacity` is insufficient the required size is returned and no writes occur. function CXNetworkWriteBXNet Writes an uncompressed binary BXNet file to disk. function CXNetworkWriteBXNetFiltered Writes a BXNet file while allowing or ignoring selected attributes by scope. function CXNetworkWriteGML Serializes a network as GML. Lossy cases (for example unsupported attribute payloads or renamed keys) are reported via `CXNetworkSerializationLastWarningMessage()`. @param network Network to serialize. @param path Output path for the `.gml` file. @return CXTrue on success, CXFalse on failure. function CXNetworkWriteGT Serializes a network as a graph-tool `.gt` binary graph file. `.gt` is an interoperability format. Helios-specific state and unsupported attributes may be skipped or converted, with warnings reported via `CXNetworkSerializationLastWarningMessage()`. @param network Network to serialize. @param path Output path for the `.gt` file. @return CXTrue on success, CXFalse on failure. function CXNetworkWriteNodeLinkJSON Serializes a network as node-link JSON compatible with common D3/NetworkX style payloads. Lossy cases are reported via `CXNetworkSerializationLastWarningMessage()`. @param network Network to serialize. @param path Output path for the `.json` file. @return CXTrue on success, CXFalse on failure. function CXNetworkWriteXNet Serializes a network using the XNET 1.0.0 human-readable container. Performs compaction to ensure contiguous node and edge indices before writing. Adds the `_original_ids_` vertex attribute to preserve the original node identifiers. @param network Network to serialize. @param path Output path for the `.xnet` file. @return CXTrue on success, CXFalse on failure. function CXNetworkWriteXNetFiltered Serializes an XNET file while allowing or ignoring selected attributes. Attribute filters are split by node, edge, and graph/network scope. @param network Network to serialize. @param path Output path for the `.xnet` file. @return CXTrue on success, CXFalse on failure. function CXNetworkWriteZXNet Writes a BGZF-compressed ZXNet file to disk. function CXNetworkWriteZXNetFiltered Writes a ZXNet file while allowing or ignoring selected attributes by scope.

Measurements

One-shot graph measurements such as degree, strength, clustering, dimension, and centrality.

function CXNetworkLeidenModularity Runs Leiden community detection optimizing (weighted) modularity. - For undirected graphs, uses the standard modularity objective. - For directed graphs, uses the directed modularity formulation. - `resolution` corresponds to the modularity resolution parameter (gamma). - When `edgeWeightAttribute` is NULL/empty, every edge has weight 1. Writes the resulting community id into a node attribute (created when missing) of type `CXUnsignedIntegerAttributeType` and dimension 1. Returns the number of detected communities, or 0 on failure. function CXNetworkMeasureBetweennessCentrality Runs Brandes betweenness centrality (weighted when an edge weight attribute is provided, unweighted otherwise). - `sourceNodes` can restrict the set of source nodes used by the algorithm. When NULL/empty, all active nodes are used. - Set `accumulate` to CXTrue to add into `inOutNodeBetweenness` instead of clearing it first (useful for chunked stepping). - Output buffer length must be at least `CXNetworkNodeCapacity(network)`. Returns the number of source nodes actually processed. function CXNetworkMeasureConnectedComponents Measures connected components. - Weak mode treats directed edges as undirected (weakly-connected components). - Strong mode computes strongly-connected components on directed graphs. Undirected graphs behave like weak mode. Component ids are written into `outNodeComponent` (length must be at least `CXNetworkNodeCapacity(network)`). Inactive nodes receive id `0`. Returns the number of detected components. function CXNetworkMeasureCoreness Measures node coreness (k-core index) for all node capacity indices. - Uses iterative peeling over the chosen degree policy (`direction`). - For directed graphs: - `Out` uses outgoing degree. - `In` uses incoming degree. - `Both` uses incoming + outgoing degree. - For undirected graphs, direction is normalized to undirected degree. Output buffer length must be at least `CXNetworkNodeCapacity(network)`. Inactive nodes receive coreness 0. function CXNetworkMeasureDegree Measures node degree for every node index (inactive nodes receive 0). Output buffer length must be at least `CXNetworkNodeCapacity(network)`. function CXNetworkMeasureDimension Computes global multiscale dimension statistics over a node set. - If `nodes` is NULL or `nodeCount` is 0, all active nodes are used. - Invalid/inactive node ids in `nodes` are ignored. - Output buffers, when non-null, must each have length `maxLevel + 1`. Returns the number of nodes actually measured. function CXNetworkMeasureEigenvectorCentrality Runs power-iteration eigenvector centrality. - `initialNodeCentrality`, when non-null, must have one value per node capacity index and is used as the initial vector. - `outNodeCentrality` must have one value per node capacity index. - `executionMode` allows callers to force single-thread or parallel mode. function CXNetworkMeasureLocalClusteringCoefficient Measures local clustering coefficients for all node indices. - `variant` selects the unweighted or weighted formulation. - Weighted variants read `edgeWeightAttribute` (unit weights when omitted). Output buffer length must be at least `CXNetworkNodeCapacity(network)`. function CXNetworkMeasureNodeDimension Computes local multiscale capacity and dimension for a single node. - `maxLevel` controls the largest geodesic radius r evaluated. - `method` and `order` select the derivative estimator (FW/BK/CE/LS). - `outCapacity` and `outDimension`, when non-null, must point to buffers of length `maxLevel + 1`. Returns CXFalse when the node is invalid/inactive or on allocation failure. function CXNetworkMeasureStrength Measures node strength from an edge weight attribute (or unit weights when `edgeWeightAttribute` is NULL/empty). Output buffer length must be at least `CXNetworkNodeCapacity(network)`.

Measurement Sessions

Steppable native measurement sessions for long-running algorithms.

function CXConnectedComponentsSessionCreate Creates a steppable connected-components session. function CXConnectedComponentsSessionDestroy Releases all resources held by a connected-components session. function CXConnectedComponentsSessionFinalize Finalizes a completed session, copying per-node component ids into `outNodeComponent` (length >= nodeCapacity). function CXConnectedComponentsSessionGetProgress Returns current progress metrics. Any output pointer may be NULL. function CXConnectedComponentsSessionStep Advances the session by at most `budget` node-visits (best effort). function CXCorenessSessionCreate Creates a steppable coreness session. function CXCorenessSessionDestroy Releases all resources held by a coreness session. function CXCorenessSessionFinalize Finalizes a completed session, copying per-node coreness values into `outNodeCoreness` (length >= nodeCapacity). function CXCorenessSessionGetProgress Returns current progress metrics. Any output pointer may be NULL. function CXCorenessSessionStep Advances the session by at most `budget` peeled nodes (best effort). function CXLeidenSessionCreate Creates a steppable Leiden session. The network topology and relevant edge weight attribute must not change while the session is active. Returns NULL on failure. function CXLeidenSessionDestroy Releases all resources held by a Leiden session. function CXLeidenSessionFinalize Finalizes a completed session, writing the resulting community ids into a node attribute of type `CXUnsignedIntegerAttributeType` (dimension 1). Returns CXFalse if the session has not completed or on failure. function CXLeidenSessionGetProgress Returns current progress metrics. Any output pointer may be NULL. `outProgressCurrent` and `outProgressTotal` are best-effort and may change as the algorithm advances (i.e. the total may be revised). function CXLeidenSessionStep Advances the session by at most `budget` node-visits (best effort). Returns the current phase after stepping.

Coverage Notes

The extractor reads CX_EXTERN declarations and the nearest preceding Doxygen-style block comment. Internal bundled headers and uthash/utarray compatibility headers are intentionally excluded. For more precise grouping later, add a section annotation to the Doxygen block and wire it into scripts/generate_api_reference.py.

  • No missing C comment summaries detected for extracted declarations.