Skip to main content

ZGraph

Unit Tests

A hardware-accelerated, fully differentiable, physics-free soft-tropical sum-product graph engine.

zgraph is a low-level, high-performance numerical kernel engine built natively on JAX and Equinox (jax.jit, jax.vmap, jax.grad). It compiles hierarchical factor graph contractions, soft-tropical marginalizations, and convex optimization problems into homogeneous chains of parameterized $\text{LogSumExp}$ ($\text{LSE}$) matrix operations.


Core Philosophy: Physics-Free Pure Math

zgraph is strictly domain-agnostic and physics-free.

The engine operates exclusively on unlabeled numerical tensors (jax.Array). It contains zero domain-specific logic, zero unit conversions, and zero Python object overhead (such as string matching or dictionary lookups inside loops).

All physical nomenclature, thermodynamic ensembles, chemical potential mappings ($\mu$), state variables ($T, P$), phase definitions, and human-readable metadata are relegated to higher-level application layers such as ThermoGraph.

Separation of Concerns

Feature / Responsibility zgraph (Math Engine) thermograph (Application Layer)
Domain Scope Abstract factor graphs, soft-tropical semirings Thermodynamics, statistical mechanics, CALPHAD
Data Types Unlabeled JAX Arrays (jax.Array) Named variables, species, phases, physical units
Core Operations Incidence projection, parameterized $\text{LogSumExp}$ Ensemble definitions $(T, P, \mu)$, driving forces
Optimization Target jax.jit, XLA compilation, jax.vmap vectorization Phase equilibrium, convex hulls, phase-field coupling
Graph Mutations Structurally immutable execution graphs Dynamic model assembly & configuration

Key Pillars

1. Physics-Free Pure Tensor Math

By enforcing pure tensor-only signatures (__call__(signals: Array) -> Array), zgraph guarantees zero graph breaks during JIT compilation. Nodes do not store string names, metadata dicts, or conditional Python logic.

2. Soft-Tropical Sum-Product Algebra

Every node maps incoming child log-potentials $\mathbf{z} \in \mathbb{R}^N$ via incidence matrix $M \in \mathbb{R}^{K \times N}$, log-degeneracy bias $\boldsymbol{g} \in \mathbb{R}^K$, and scale parameter $\tau \in [0, \infty)$ into a scalar outgoing log-potential $z^+$: $$z^+(\mathbf{z}) = \tau , \text{LogSumExp}!\left( \tau^{-1} M \mathbf{z} + \boldsymbol{g} \right)$$ where $\tau$ controls the smoothing transition between exact hard-tropical selection ($\tau \to 0^+$, $\max_i (M\mathbf{z})_i$) and smooth statistical marginalization ($\tau > 0$).

3. Hardware-Native Execution

Engine nodes (FactorNode, ConstantNode, SignalNode) are engineered to compile seamlessly via jax.jit into fused XLA kernels. Vectorization across spatial grids or multi-dimensional parameter ensembles (Ensemble) is handled automatically via vmap.

4. End-to-End Differentiability & Legendre-Fenchel Duality

Built for direct integration with JAX's autodiff engine, zgraph provides exact analytical marginals and susceptibilities ($\mathbf{n} = \nabla_{\mathbf{z}} z^+$, $\mathbf{H}{\mathbf{z}} = \nabla^2{\mathbf{z}} z^+$) as well as both forward parametric (legendre_transform) and iterative inverse (legendre_solve, legendre_dual) Legendre-Fenchel duality: $$z^*(\mathbf{n}) = \sup_{\mathbf{z}} \left{ \mathbf{z}^T \mathbf{n} - z^+(\mathbf{z}) \right}$$


Engine Usage Example

At the zgraph level, models are built using purely mathematical node abstractions:

import jax.numpy as jnp
import zgraph as zg

# 1. Define incidence matrix M (K branches x N child factors)
M_matrix = jnp.array([
    [1.0, 0.0],
    [0.0, 1.0],
    [0.5, 0.5]
])

# 2. Define child subgraphs (Constant / Signal nodes)
subgraphs = [
    zg.ConstantNode(init_val=1.5),
    zg.SignalNode(0)
]

# 3. Instantiate the FactorNode engine with scale tau and optional log-degeneracy g
factor_node = zg.FactorNode(M_matrix=M_matrix, subgraph_list=subgraphs, tau=1.0)

# 4. Pure tensor input evaluation
signals = jnp.array([0.2, 1.0])  # Unlabeled numerical input tensor
potential = factor_node(signals) # Fully differentiable scalar tensor output

Interactive Examples

Explore interactive Jupyter notebooks running natively on Google Colab:

  • 2D Binary Equilibrium (binary.ipynb): Open In Colab
  • 3D Extruded Dimension (Extruded_dimension.ipynb): Open In Colab
  • Stoichiometric Equilibrium (stoichiometric.ipynb): Open In Colab
  • Simple Phase Diagram (phase_diagram.ipynb): Open In Colab

Application Layer

For thermodynamic potential evaluation, materials modeling, phase diagram construction, and user-facing APIs, please see the ThermoGraph repository.

Metadata

Release files for zgraph 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zgraph 0.1.1
File Size Uploaded Provenance Actions
zgraph-0.1.1.tar.gz 33.3 kB Without provenance Details for zgraph-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zgraph 0.1.1
File Interpreter ABI Platform Actions
zgraph-0.1.1-py3-none-any.whl Python 3 none any Details for zgraph-0.1.1-py3-none-any.whl

Total release size: 64.9 kB

Release files / zgraph-0.1.1.tar.gz

Download URL zgraph-0.1.1.tar.gz
Size 33.3 kB
Tags Source
SHA-256 checksum
How to use checksums
c75b2a6c293ec8403ed0ce5b85e75e442acce0831cc2ae63dcfdf36135b10f52
BLAKE2b-256 checksum
How to use checksums
9c1fc3afb25bc125d68422cd096491b17ee5981f689e8056540ff39f275f8779
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / zgraph-0.1.1-py3-none-any.whl

Download URL zgraph-0.1.1-py3-none-any.whl
Size 31.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f2e81ee34e2f70a31e0ac8a45f6216805d882711d4fe66dcef0b47735bd2f77f
BLAKE2b-256 checksum
How to use checksums
ac9682de9755c5db91a5ecab696c65a57da8773df6b01e3ab99bd2bd93eaec7c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for zgraph 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page