Metadata-Version: 2.4
Name: pbitlang
Version: 2.1.0
Summary: The language of thermodynamic computing: author energies as Hamiltonians and denoising processes, compile to ThermoIR, and run certified on simulators or the Thermo Bridge. Multi-dialect (Ising core + categorical/token diffusion), with exact-sampling proofs and replay certificates.
Project-URL: Homepage, https://github.com/dmjdxb/Thermodynamic-Computing-Platform-/tree/main/pbitlang
Project-URL: Documentation, https://pbitlang.readthedocs.io
Project-URL: Repository, https://github.com/dmjdxb/Thermodynamic-Computing-Platform-/tree/main/pbitlang
Author: David Johnson
License: PbitLang Software License
        =========================
        
        Copyright (c) 2024 David Johnson. All Rights Reserved.
        
        NOTICE: This is proprietary software. By installing, copying, or using this
        software, you agree to be bound by the terms of this license.
        
        ================================================================================
                                      GRANT OF LICENSE
        ================================================================================
        
        Subject to the terms and conditions of this License, David Johnson ("Licensor")
        hereby grants you a limited, non-exclusive, non-transferable, royalty-free
        license to:
        
        1. INSTALL AND USE: You may install and use this software for personal,
           educational, research, or commercial purposes.
        
        2. BACKUP COPIES: You may make copies of the software solely for backup
           or archival purposes.
        
        3. INTEGRATION: You may use this software as a component in your own
           applications and products.
        
        ================================================================================
                                       RESTRICTIONS
        ================================================================================
        
        You may NOT, without prior written consent from the Licensor:
        
        1. MODIFY: Alter, adapt, translate, or create derivative works based on
           this software or any portion thereof.
        
        2. REDISTRIBUTE: Distribute, sublicense, lease, rent, loan, or otherwise
           transfer this software to any third party, whether for commercial
           purposes or otherwise.
        
        3. REVERSE ENGINEER: Reverse engineer, disassemble, decompile, or
           otherwise attempt to derive the source code of this software (except
           to the extent that such activity is expressly permitted by applicable
           law notwithstanding this limitation).
        
        4. REMOVE NOTICES: Remove, alter, or obscure any proprietary notices,
           labels, or marks on this software.
        
        5. COMPETE: Use this software to create a competing product or service.
        
        6. CLAIM OWNERSHIP: Represent that you own, created, or have rights to
           this software beyond those expressly granted herein.
        
        ================================================================================
                                   INTELLECTUAL PROPERTY
        ================================================================================
        
        This software, including all associated documentation, source code, object
        code, algorithms, and designs, is the exclusive intellectual property of
        David Johnson. This license does not grant you any ownership rights or
        intellectual property rights in the software.
        
        All rights not expressly granted herein are reserved by the Licensor.
        
        ================================================================================
                                      NO WARRANTY
        ================================================================================
        
        THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
        THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER
        IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
        CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
        ================================================================================
                                      TERMINATION
        ================================================================================
        
        This license is effective until terminated. Your rights under this license
        will terminate automatically without notice if you fail to comply with any
        of its terms. Upon termination, you must destroy all copies of the software
        in your possession.
        
        ================================================================================
                                    GOVERNING LAW
        ================================================================================
        
        This license shall be governed by and construed in accordance with applicable
        law, without regard to conflict of law principles.
        
        ================================================================================
                                       CONTACT
        ================================================================================
        
        For licensing inquiries, permissions, or commercial licensing arrangements:
        
        David Johnson
        GitHub: https://github.com/dmjdxb
        
        ================================================================================
        
        BY INSTALLING OR USING THIS SOFTWARE, YOU ACKNOWLEDGE THAT YOU HAVE READ,
        UNDERSTOOD, AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE.
        
        
        
License-File: LICENSE
Keywords: domain-specific-language,hamiltonian,ising-model,pbit,physics,spin-systems,statistical-mechanics,thermodynamic-computing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Interpreters
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: budget
Provides-Extra: certify
Requires-Dist: cryptography>=3.4; extra == 'certify'
Requires-Dist: numpy>=1.21; extra == 'certify'
Provides-Extra: continuous
Requires-Dist: numpy>=1.21; extra == 'continuous'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: diffuse
Requires-Dist: numpy>=1.21; extra == 'diffuse'
Provides-Extra: docs
Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
Requires-Dist: sphinx>=6.0; extra == 'docs'
Provides-Extra: hyper
Requires-Dist: numpy>=1.21; extra == 'hyper'
Provides-Extra: learn
Requires-Dist: numpy>=1.21; extra == 'learn'
Provides-Extra: phal
Requires-Dist: phal>=0.1.0; extra == 'phal'
Provides-Extra: schedules
Requires-Dist: numpy>=1.21; extra == 'schedules'
Provides-Extra: thermo
Requires-Dist: energyir[thermo]>=1.1.0; extra == 'thermo'
Requires-Dist: numpy>=1.21; extra == 'thermo'
Provides-Extra: torch
Requires-Dist: numpy>=1.21; extra == 'torch'
Requires-Dist: torch>=1.13; extra == 'torch'
Provides-Extra: torch-thermo
Requires-Dist: energyir[thermo]>=1.1.0; extra == 'torch-thermo'
Requires-Dist: numpy>=1.21; extra == 'torch-thermo'
Requires-Dist: torch>=1.13; extra == 'torch-thermo'
Description-Content-Type: text/markdown

# PbitLang

**The p-bit / thermodynamic-computing language.**

[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

PbitLang lets you write a Hamiltonian (energy function) once and run it on thermodynamic hardware —
P-bits, Ising machines, annealers, and continuous thermodynamic samplers. v2.0 makes PbitLang the
authoring front-end for the whole **EnergyIR** stack: a program compiles to device-independent
**ThermoIR** and runs on the local simulator, a real sampler, or the hosted **Thermo Bridge**, where
every run comes back with a **signed certificate you verify offline**.

## Train energy-based models (new)

Where PyTorch trains by backprop, energy-based models train by **sampling** — the gradient of the
log-likelihood is `⟨·⟩data − ⟨·⟩model`, and the model term is the negative phase a thermodynamic
device is built to compute. `pbitlang.learn` is that engine:

```python
from pbitlang.learn import RBM, learn_ising

rbm = RBM(n_visible=9, n_hidden=16).fit(data)   # contrastive divergence
gen = rbm.sample(100)                            # generate

J, h = learn_ising(spin_samples)                 # recover couplings from data (inverse Ising)
```

## What's new in 2.0

- **Compiles to ThermoIR** — not just PHAL. One program, any backend.
- **Runs on the Thermo Bridge** — `run(..., backend="bridge")` → result **+ certificate**, verified offline.
- **All four primitive families** (the p-bit hardware vocabulary):
  | Primitive | What it is | PbitLang |
  |---|---|---|
  | **p-bit** | Bernoulli / binary spin | `ising` / `binary` on a lattice → ThermoIR `Ising` |
  | **p-mode** | Gaussian | `thermo.gaussian_program(A, b)` → ThermoIR `Quadratic` |
  | **p-MoG** | Mixture of Gaussians (multimodal) | `thermo.mixture_program(...)` → `EnergyGraph` + Langevin |
  | **p-dit** | Categorical | Potts / one-hot lowering *(DSL surface lands in 2.x)* |
- **A training engine for energy-based models** (`pbitlang.learn`) — RBMs (CD / persistent CD /
  parallel tempering), classification RBMs, deep belief nets, Gaussian–Bernoulli RBMs, and inverse
  Ising — with the **negative phase runnable on the Thermo Bridge** (`negative="thermo"`).
- **Certified inference** — provable lower/upper bounds on `log Z` yield a *certified* log-likelihood
  interval, wrapped in an **ed25519-signed, offline-verifiable certificate**. The number PyTorch can't
  give you: a bound you can prove, not a loss you take on faith.
- **PyTorch interop** (`pbitlang.torch`) — write the energy as a `torch.nn.Module`, train with
  `torch.optim` + autograd, and let the **thermodynamic sampler supply the partition-function
  gradient**. `DeepThermoEBM` extends this to deep (conditional) energy landscapes.
- **CLI `run`** — compile and execute from the shell, local or hosted.
- **Repaired core** — the v1.x parser/checker rejected its own documented examples (`coupling:` / `field:`
  labels, `neighbors` domains, `J * s[i]` arithmetic). Those now compile.

## Install

```bash
pip install pbitlang                    # the language + compiler (zero core deps)
pip install 'pbitlang[learn]'           # + the EBM training engine + certified inference (NumPy only)
pip install 'pbitlang[certify]'         # + ed25519-signed certificates (adds cryptography)
pip install 'pbitlang[thermo]'          # + the ThermoIR / Thermo Bridge backend (needs energyir >= 1.1.0)
pip install 'pbitlang[torch]'           # + PyTorch interop: DeepThermoEBM, autograd training
pip install 'pbitlang[torch-thermo]'    # + ThermoEBM samplers on the thermo runtime (torch + energyir)
```

> The `[thermo]` / `[torch-thermo]` extras require **energyir ≥ 1.1.0**, the first release that ships the
> `energyir.thermo` runtime (compiler, backends, the `gibbs` Boltzmann sampler). The training engine and
> certified inference (`[learn]` / `[certify]`) are pure-NumPy and need none of that.

## Quick start

```python
import pbitlang
from pbitlang import thermo

src = """
hamiltonian Ising(n: int, J: real = 1.0, h: real = 0.0)
    -> ising on chain(n) {
    coupling: sum((i, j) in neighbors) { -J * s[i] * s[j] }
    field:    sum(i in sites)          { -h * s[i] }
}
"""

# Compile → a ThermoIR Program; run locally:
res = thermo.run(src, n=16, J=1.0, h=0.1, backend="simulator", shots=1000)
print(res.value)

# ...or run on the hosted Thermo Bridge and verify the certificate offline:
res = thermo.run(src, n=16, backend="bridge",
                 api_key="eir-thermo-...", certificate="statistical")
print(res.verified)   # True — the worker signed it, you checked it
```

Continuous pole (p-mode / p-MoG):

```python
import numpy as np
from pbitlang import thermo

# p-mode: solve A x = b as a Gaussian readout
A = np.array([[4., 1.], [1., 3.]]); b = np.array([1., 2.])
print(thermo.run(None, program=thermo.gaussian_program(A, b, readout="mean")).value)  # = A^-1 b

# p-MoG: a bimodal landscape; both basins are visited
prog = thermo.mixture_program(dim=1, wells=1.0, well_scale=2.0, shots=4000)
print(thermo.run(None, program=prog).value)
```

## CLI

```bash
pbitlang run model.pbit -p n=16 -p J=1.0 --backend simulator
pbitlang run model.pbit -p n=16 --backend bridge --certificate statistical   # $THERMO_API_KEY
pbitlang compile model.pbit -t info
pbitlang stdlib list
```

## Language

- **Spin types:** `ising`, `binary`, `potts(q)`, `clock(q)`, `continuous`
- **Lattices:** `chain`, `square`, `triangular`, `honeycomb`, `kagome`, `cubic`, custom (adjacency / edges)
- **Energy:** `coupling:` / `field:` / `energy:` terms with `sum` / `product` comprehensions, patterns, `where`
- **Domains:** `neighbors`, `next_neighbors`, `all_pairs`, `sites`
- **Physics validation:** frustration, critical temperature, symmetry checks at compile time

## Part of the EnergyIR thermodynamic stack

PbitLang authors the Hamiltonian; **ThermoIR** is the device-independent IR; the **Thermo Bridge** runs it
hosted with certificates. See the Thermo Bridge docs on energyir.io.

## License

**Proprietary Software** — Copyright © 2024–2026 David Johnson. All Rights Reserved.
