API Reference

MoC-JEPA is a pretrained framework — Moment-driven Charge Density Joint Embedding Predictive Architecture — that maps a structure into per-node latents, then into one of two SCF seeds: a charge-density grid (.chgcar / .cube) for plane-wave codes, or an initial density matrix (dm0 / mo_c) for GTO codes. Raw AUX coefficients remain available for power users. Billing is metered on Processed Atoms for every DEN or AUX prediction. The API is operated by 本征实验室 (Braketlab Inc.). All requests go over HTTPS to https://api.braketlab.ai/moc-jepa.

1. 01

   Upload structure

   Crystal .cif / .xyz, or molecule .pdb / .xyz.

2. 02

   Encode latents

   Backbone returns per-node latents as .h5.

3. 03

   Predict DEN or AUX

   DEN writes .chgcar / .cube. :seed writes dm0 / mo_c. Raw AUX stays for power users.

4. 04

   Seed SCF

   VASP: ICHARG=1 reads CHGCAR. GTO: pass dm0 from :seed to PySCF.

Authentication

Authenticate with a secret key in the Authorization header. Generate keys from your dashboard. Never expose a secret key in client-side code.

Pretrained Backbones

Two independently pretrained backbones share the same architecture and versioning rule. Pick the one that matches your chemistry.

Density Prediction Models

DEN heads predict a real-space charge-density grid. That grid is native to plane-wave SCF: put CHGCAR next to ICHARG=1 in VASP. Do not project the grid onto an AO density matrix for PySCF or other GTO codes — use AUX :seed instead. Future heads (Band Gap Prediction, Potential Energy Prediction) will reuse the same naming slot.

Auxiliary Fitting Models

AUX heads predict density-fitting coefficients in def2-universal-jfit, stored in PySCF order. That vector is not an AO density matrix. The recommended path is :seed, which builds F₀ = h + J[ρ_aux] + Vxc[ρ_aux] server-side and returns dm0 / mo_c. Raw AUX stays for power users. See GTO Adapter (PySCF first-class). AUX is bound to O1 only and does not share checkpoints with DEN.

Naming & Versioning

Checkpoints follow a single pattern. The three-letter task slot is reserved so new applications can land without renaming the backbone.

• major — latent space is not backward compatible; every downstream head must be retrained.
• minor — same architecture, more or cleaner data; latents stay compatible.
• Heads at DEN-v1.x and AUX-v1.x bind to backbone major line v1.x.
• API ids are the lowercase kebab form. Unpinned ids (moc-jepa-m1-den, moc-jepa-o1-aux) resolve to the latest minor within the current major. Pin with moc-jepa-m1-den-v1.0 / moc-jepa-o1-aux-v1.0.
• Reserved task codes: GAP Band Gap Prediction PES Potential Energy Prediction — documented, not shipping.

Encode Latents

Maps an input structure into the MoC-JEPA latent space and returns per-node latents as an .h5 file. The model is equivariant under the Euclidean group E(3), so for any rotation R the latents transform as z(Rx) = R · z(x).

Each Processed Atom yields a 256-dimensional latent vector. The full tensor has shape (N, 256) and dtype float32.

Request body

Predict Density

Runs a DEN head on a latents file and returns a charge-density grid. Use CHGCAR with VASP ICHARG=1. This is a billable call: one Processed Atom per atom in the encoded structure.

Request body

One-shot Density

Encodes latents and predicts a density grid in one request. Equivalent to /moc-jepa/latents then /moc-jepa/density. Prefer the two-step path when you want to reuse latents across DEN and AUX.

Request body

Predict Aux Density

Runs the O1 AUX head and returns fitting coefficients as .h5. Dataset aux_coeff is float64 of length naux in PySCF order for def2-universal-jfit. It is not an AO density matrix. Prefer :seed for a ready-to-use dm0; this raw-aux endpoint stays for power users. Billable on Processed Atoms.

Request body

One-shot Aux Density

Encodes O1 latents and predicts AUX coefficients in one request. Equivalent to /moc-jepa/latents then /moc-jepa/auxdensity. Same h5 fields and element / closed-shell constraints as /moc-jepa/auxdensity. For a ready-to-use dm0, call /moc-jepa/auxdensity:direct-seed instead.

Request body

Seed Initial Guess

Same inputs as /moc-jepa/auxdensity. The server builds F₀ = h + J[ρ_aux] + Vxc[ρ_aux] and returns an initial density matrix / MO coefficients, not raw aux coefficients. Pass dm0 straight to PySCF. Continue at GTO Adapter (PySCF first-class).

Billing is the same Processed-Atom metering as /moc-jepa/auxdensity. The F₀ build is included; we absorb that compute cost into the per-atom price. The returned guess_grid is the server quadrature only — set the client grid in SCF Grid Settings.

Request body

One-shot Seed

Structure → dm0 in one request. Equivalent to /moc-jepa/latents then /moc-jepa/auxdensity:seed. Same h5 fields, QM settings, and element / closed-shell constraints as :seed. Same Processed-Atom billing; the F₀ build is included.

Request body

VASP (ICHARG=1)

Plane-wave DFT treats the charge-density grid as the SCF variable. Download CHGCAR from a DEN head (M1), place it in the VASP working directory, and set ICHARG=1. Do not convert CHGCAR into an AO density matrix for a GTO code.

1. Call /moc-jepa/density:direct with moc-jepa-m1-den and format=chgcar.
2. Write the body to CHGCAR in the VASP directory.
3. Set ISTART=0 and ICHARG=1 in INCAR.
4. Run VASP. It reads CHGCAR as the initial charge density.

GTO Adapter (PySCF first-class)

The :seed endpoint returns an initial density matrix dm0 already built from F₀ = h + J[ρ_aux] + Vxc[ρ_aux]. Pass it straight to your SCF solver and get a 1.28–1.41× end-to-end speedup over the default SAD guess (benchmarked on 33–117 atom drug-like molecules, PBE/def2-SVP).

You do not need to understand or implement the F₀ build. It runs on our GPU infrastructure. Your code only needs to hand dm0 to .kernel().

PySCF (first-class)

Three steps: get dm0, build mol with the same geometry, run SCF.

1from mocjepa import MoCJEPA
2import pyscf
3
4client = MoCJEPA(api_key="$MOCJEPA_API_KEY")
5
6# Step 1: get dm0 — one API call, one file
7seed = client.auxdensity.direct_seed(
8    model="moc-jepa-o1-aux",
9    structure=open("caffeine.xyz", "rb"),
10)
11seed.save("caffeine_seed.h5")
12print(seed.guess_grid)    # { "level": 2, "vxc_assembly": "sparse", "xc_for_guess": "pbe" }
13
14# Step 2: build mol — geometry must match the structure you uploaded
15mol = pyscf.gto.M(
16    atom=open("caffeine.xyz").read(),
17    basis="def2-svp",
18    charge=seed.charge,
19    spin=seed.spin,
20    verbose=0,
21)
22
23# Step 3: run SCF with dm0
24import h5py, numpy as np
25with h5py.File("caffeine_seed.h5") as f:
26    dm0 = f["dm0"][:]
27
28mf = mol.RKS(xc="pbe")
29mf.kernel(dm0=dm0)

• Released head: PBE / def2-SVP, basis="def2-svp", cart=False, closed shell, elements H, C, N, O, F, P, S. New basis or protocol needs a retrained head — contact the developers.
• Raw AUX coefficients stay on /moc-jepa/auxdensity for power users. Do not invert a DEN grid onto AOs: no S⁻¹PS⁻¹, grid_to_dm, or get_veff(mol, D_from_rho).
• PySCF is the only first-class consumer. Gaussian, TeraChem, and PSI4 take the same mo_c after AO remapping. Without a permutation matrix those guides are experimental, not “supported”.

Full Trajectory Acceleration (Geometry Optimization)

Geometry-optimization trajectories (5 drug-like molecules, 20–55 atoms, PBE/def2-SVP, geomeTRIC). Workflow: Geometry Optimization & Scans. Grid choice: SCF Grid Settings.

The server-side guess uses grid level 2, and the client SCF in this test used level 2 as well. Using level 3 on the client adds ~5–15% per-step time regardless of the initial guess, and does not change the geometry-optimization step count (level 2 and level 3 end in the same basin; see SCF Grid Settings).

PySCFfirst-class

PySCF is the only first-class GTO integration. GTO SCF iterates an AO density matrix, not a cube. Call :direct-seed, then pass dm0 to mol.RKS(xc="pbe").kernel. You do not implement the F₀ build — it runs on our GPU.

1. Call /moc-jepa/auxdensity:direct-seed and save caffeine_seed.h5.
2. Build mol with the same geometry, basis="def2-svp", cart=False, and the h5 charge / spin.
3. Read dm0 and run mol.RKS(xc="pbe").kernel(dm0=dm0).

Released-model limits: PBE / def2-SVP, closed shell, H, C, N, O, F, P, S. Do not set cart=True. Do not use S⁻¹PS⁻¹, grid_to_dm, or get_veff(mol, D_from_rho). New basis or protocol needs a retrained head.

Gaussianexperimental · PySCF bridge + AO remap

Without an AO permutation this is not a Gaussian integration — it is reading the wrong orbitals. formchk / unfchk only convert chk ↔ fchk; they cannot inject a foreign mo_c. Guess=Read on an empty chk is not a path. Gaussian PBE is PBEPBE; add 5D 7F so the basis is spherical like PySCF cart=False.

1. Download mo_c from /moc-jepa/auxdensity:direct-seed.
2. Remap PySCF AO order → Gaussian 5D/7F (d/f order and spherical-harmonic phases). Identity is the wrong guess.
3. Write Guess=Cards with the remapped MOs (Fortran format line, IVec, coefficients, IVec=0). Or let Gaussian write a chk, edit Alpha MO coefficients in the fchk after remapping, then unfchk.

TeraChemexperimental · PySCF bridge + AO remap

method pbe / basis def2-svp / guess read is the right direction, but c0 is TeraChem's own AO-order MO matrix. Binary layout depends on the TeraChem version (header, Fortran unformatted vs raw, row vs column major). It is not a dump of PySCF mo_c. Charge, spin, and closed-shell occupancy must match the PySCF molecule.

1. Download mo_c from /moc-jepa/auxdensity:direct-seed.
2. Remap to TeraChem AO order, then write c0 in that build's binary layout.
3. Run TeraChem with matching charge and spinmult (closed shell: 0 / 1).

PSI4experimental · PySCF bridge + AO remap

Da = C_occ C_occᵀ is the alpha block — not PySCF's closed-shell dm0 = 2 C_occ C_occᵀ. Do not write into the PSI4 scratch wavefunction; that is not a stable public API. Set Ca / Da on psi4.core.Wavefunction, or to_file / from_file a wfn for the same molecule and same basis, then guess=read. PSI4 d/f AO order may still differ from PySCF — remap. Do not project a DEN cube onto PSI4 AOs.

1. Download mo_c from /moc-jepa/auxdensity:direct-seed.
2. Remap to PSI4 AO order. Set Ca = C and Da = C_occ C_occᵀ on a psi4.core.Wavefunction, then persist that same-molecule, same-basis wfn.
3. set_options with basis=def2-svp, scf_type, and guess=read, then energy("pbe/def2-svp") — not energy("pbe").

Geometry Optimization & Scans

Geometry optimization is an ML-first warm restart: request dm0 once, inject it on the first SCF, then let later steps reuse mo_coeff. Grid choice is in SCF Grid Settings.

Geometry optimization (ML-first + warm restart)

1. Request dm0 from :direct-seed for the initial geometry.
2. Use that dm0 as the first SCF guess (mf.get_init_guess).
3. For later geometry steps, let SCF warm-restart from the previous mo_coeff.
4. Run geomeTRIC, or any optimizer that drives the same SCF object.

1from mocjepa import MoCJEPA
2import h5py
3import pyscf
4import gpu4pyscf.dft
5import cupy as cp
6from pyscf.geomopt.geometric_solver import kernel as geo_kernel
7
8client = MoCJEPA(api_key="$MOCJEPA_API_KEY")
9
10# 1) :direct-seed once on the starting geometry (server guess is level 2)
11seed = client.auxdensity.direct_seed(
12    model="moc-jepa-o1-aux",
13    structure=open("mol.xyz", "rb"),
14)
15seed.save("mol_seed.h5")
16print(seed.guess_grid)    # { "level": 2, "vxc_assembly": "sparse", "xc_for_guess": "pbe" }
17
18with h5py.File("mol_seed.h5") as f:
19    dm0_np = f["dm0"][:]
20
21# 2) client SCF — grid is independent of guess_grid
22mol = pyscf.M(
23    atom=open("mol.xyz").read(),
24    basis="def2-svp",
25    charge=seed.charge,
26    spin=seed.spin,
27)
28mf = gpu4pyscf.dft.RKS(mol)
29mf.xc = "pbe"
30mf = mf.density_fit(auxbasis="def2-universal-jfit")
31mf.grids.level = 2   # use 3 for force-sensitive work
32
33# 3) inject dm0 on the first SCF only; later steps warm-restart
34dm0_cp = cp.asarray(dm0_np)
35_dm0_injected = [False]
36
37def _ml_init_guess(mol_=None, key_=None):
38    if not _dm0_injected[0]:
39        _dm0_injected[0] = True
40        return dm0_cp
41    return type(mf).get_init_guess(mf, mol_ or mf.mol, key_ or mf.init_guess)
42
43mf.get_init_guess = _ml_init_guess
44
45# 4) geomeTRIC
46mol_opt = geo_kernel(mf, maxsteps=200, assert_convergence=False)

Torsion / PES scan

For a torsion scan or PES sample, call :seed once per geometry. Each point is a fresh SCF from the ML initial guess. Warm restart does not apply across geometries.

1from mocjepa import MoCJEPA
2import h5py
3import pyscf
4import gpu4pyscf.dft
5
6client = MoCJEPA(api_key="$MOCJEPA_API_KEY")
7
8# One :direct-seed per geometry. Do not warm-restart mo_coeff across points.
9for xyz_path in scan_xyzs:
10    seed = client.auxdensity.direct_seed(
11        model="moc-jepa-o1-aux",
12        structure=open(xyz_path, "rb"),
13    )
14    path = xyz_path + ".seed.h5"
15    seed.save(path)
16    with h5py.File(path) as f:
17        dm0 = f["dm0"][:]
18    mol = pyscf.M(atom=open(xyz_path).read(), basis="def2-svp",
19                  charge=seed.charge, spin=seed.spin)
20    mf = gpu4pyscf.dft.RKS(mol)
21    mf.xc = "pbe"
22    mf = mf.density_fit(auxbasis="def2-universal-jfit")
23    mf.grids.level = 2
24    mf.kernel(dm0=dm0)

Known limitations

• Small molecules (<15 atoms): the ML initial guess improves little over SAD. The gain grows with molecular size and conformational complexity.
• Far-from-equilibrium geometries (early steps from a poor start): the ML guess may be no better than SAD. The model is trained on near-equilibrium structures.
• Closed shell (restricted KS) only. Elements H, C, N, O, F, P, S. Open-shell requests return 400 unsupported_spin.

SCF Grid Settings

MoC-JEPA returns an initial-guess density matrix dm0 from PBE/def2-SVP on grid level 2. The client SCF may use any grid level; this page is how to choose.

Decision table

PySCF / gpu4pyscf

1import pyscf
2import gpu4pyscf.dft
3
4mol = pyscf.M(
5    atom="C 0 0 0; H 0 0 1.089; H 1.027 0 -0.363; H -0.513 0.889 -0.363; H -0.514 -0.890 -0.363",
6    basis="def2-svp",
7)
8mf = gpu4pyscf.dft.RKS(mol)
9mf.xc = "pbe"
10mf = mf.density_fit(auxbasis="def2-universal-jfit")
11
12# Level 2 — SPE and torsion / PES
13mf.grids.level = 2
14
15# Level 3 — gradients, frequencies, and reference comparisons
16# mf.grids.level = 3
17
18# Mix: level 2 base + level 3 angular for S and P
19# mf.grids.level = 2
20# mf.grids.atom_grid = {"S": (80, 434), "P": (80, 434)}

Geometry optimization

Across 9 molecules × 2 starting conformers (including P/S-containing systems), level 2 and level 3 geometry optimizations never ended in different basins, and step counts were statistically similar. Level 2 force error (up to 2.7×10⁻⁴ Ha/Bohr) is comparable to the default max-gradient threshold (4.5×10⁻⁴), so on a flat potential energy surface level 2 can declare convergence early. In one case the level 2 endpoint sat 0.12 Å / 0.22 kcal/mol from the level 3 minimum; a short level 3 continuation removed the gap. Recommended pattern: optimize at level 2, then polish the final structure at level 3. See Geometry Optimization & Scans.

Comparison with reference values

File Formats

Rate Limits

Limits are enforced per Processed Atom, not per request. /moc-jepa/latents, /moc-jepa/density, /moc-jepa/auxdensity, and /moc-jepa/auxdensity:seed count against the same quota. The F₀ build on :seed is included in the per-atom price. The default tier allows 10,000,000 Processed Atoms per month and 200 requests per minute. Crossing 200 rpm returns 429 rate_limit_exceeded with Retry-After. Contact us for research-scale throughput.