Metadata-Version: 2.4
Name: omnibias-ferminet
Version: 0.2.0
Summary: FermiNet bridge for omnibias: folx-compatible Laplacian adapters, restricted-depth Tier-2 FermiNet ansatz with closed-form Laplacian, and multiblock primitives for analytic nuclear Hessian / Born-Oppenheimer derivative work.
Author-email: Vardan Grigoryants <vardan@derivon.ai>
Maintainer-email: Derivon <info@derivon.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/derivon-ai/omnibias
Project-URL: Documentation, https://omnibias.ai/
Project-URL: Source, https://github.com/derivon-ai/omnibias
Project-URL: Issues, https://github.com/derivon-ai/omnibias/issues
Project-URL: Changelog, https://github.com/derivon-ai/omnibias/blob/main/CHANGELOG.md
Keywords: ferminet,neural-quantum-states,variational-monte-carlo,deep-learning,jax,quantum-chemistry,physics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: omnibias-core>=0.2.0
Requires-Dist: omnibias-jax>=0.2.0
Requires-Dist: jax>=0.4.30
Requires-Dist: jaxlib>=0.4.30
Requires-Dist: numpy>=1.23
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: omnibias-curvature>=0.1.0a1; extra == "test"
Provides-Extra: folx
Requires-Dist: folx>=0.1; extra == "folx"
Provides-Extra: curvature
Requires-Dist: omnibias-curvature>=0.1.0a1; extra == "curvature"
Dynamic: license-file

# omnibias-ferminet

FermiNet bridge for the omnibias closed-form n-th derivative framework.

## Install

```bash
pip install omnibias-ferminet
# Optional: pull in folx for the bit-stable Laplacian comparison test
pip install omnibias-ferminet[folx]
```

`omnibias-ferminet` depends on `omnibias-core`, `omnibias-jax`, and
`jax>=0.4.30`. It does **not** require a FermiNet installation to import
or to be unit-tested (mock log|psi| factories are provided for the bridge
contracts); a real FermiNet checkout is needed only at production VMC time.

## What is in here

- ``omnibias.ferminet.folx_compat``: ``forward_laplacian``,
  ``closed_form_forward_laplacian``, ``laplacian_factory`` -- folx-API
  drop-ins so any FermiNet / DeepQMC code that imports from ``folx`` can
  switch to omnibias's closed-form Laplacian by changing one import.
- ``omnibias.ferminet.integration``: the production bridge --
  envelope value / gradient / Hessian, optional one-body backflow, and
  the ``make_omnibias_envelope_local_kinetic_energy`` and
  ``make_omnibias_tier2_local_kinetic_energy`` factories that the
  upstream FermiNet ``laplacian_method`` switch consumes.
- ``omnibias.ferminet.restricted``: Tier-2 / Tier-2-full restricted
  FermiNet ansatz with end-to-end closed-form Laplacian (used to bring
  the bridge up before plugging into the upstream FermiNet checkpoint).
  ``tier2_grad_laplacian_log_psi`` exposes the gradient and Laplacian of
  ``log|det M|`` separately (a bit-identical refactor of the kinetic path)
  so an additive correlation factor composes correctly.
- ``omnibias.ferminet.jastrow``: closed-form symmetric **Padé-Jastrow**
  correlation factor ``exp(J)`` -- analytic value / gradient / Laplacian
  (``jastrow_value_grad_laplacian``) with physical e-e (``1/2``, ``1/4``)
  and e-n (``-Z``) cusp slopes, plus ``jastrow_slater_local_kinetic_energy``
  combining it with a Slater determinant (correct cross term in
  ``|grad log|psi||^2``).
- ``omnibias.ferminet.multiblock`` and
  ``omnibias.ferminet.multiblock_integration``: multi-block FermiNet
  primitives for Born-Oppenheimer / nuclear-Hessian work.

## Public API (lazy)

```python
from omnibias.ferminet.folx_compat import (
    forward_laplacian, closed_form_forward_laplacian, laplacian_factory,
    OmnibiasFwdLaplResult,
)
from omnibias.ferminet.integration import (
    envelope_value_grad_hessian,
    apply_optional_backflow,
    make_omnibias_envelope_local_kinetic_energy,
    make_omnibias_tier2_local_kinetic_energy,
)
from omnibias.ferminet.restricted import (
    Tier2Params, Tier2SymParams,
    tier2_log_abs_psi, tier2sym_log_abs_psi,
    tier2_local_kinetic_energy, tier2sym_local_kinetic_energy,
)
```

The top-level ``omnibias.ferminet`` namespace deliberately does **not**
re-export these: importing the bridge is opt-in so the package stays
cheap to import in scripts that do not need FermiNet.

## Contract

`omnibias-ferminet` produces a Laplacian that is bit-identical to
FermiNet's `default` autograd path on the closed-shell systems we have
validated (Be 4-electron 4-walker test in
the private release-validation archive
row R1: `rel_err = 0.0 to ULP`, `vs folx <= 5.07e-15`). This is a
**bit-stable** contract for the CPU deterministic forward path; on
stochastic GPU runs we hold to a 1-sigma reproducibility budget.

## License

Apache-2.0. See [`LICENSE`](LICENSE) and [`../../LICENSING.md`](../../LICENSING.md).
You never need a commercial licence for this package.
