Metadata-Version: 2.2
Name: lattice-mind
Version: 0.3.1.post1
Summary: LatticeMind: The AI agent for materials science.
Keywords: materials science,DFT,density functional theory,RESCU,VASP,NanoDCAL,computational chemistry,AI agent
Author-Email: "Nanoacademic Technologies Inc." <support@nanoacademic.com>
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Project-URL: Homepage, https://www.nanoacademic.com/
Project-URL: Documentation, https://docs.nanoacademic.com/
Project-URL: Changelog, https://github.com/nanoacademic/nanoai/blob/main/rescu_agent/CHANGELOG.md
Requires-Python: >=3.10
Requires-Dist: rich
Requires-Dist: textual
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: python-multipart
Requires-Dist: langgraph
Requires-Dist: langchain-core<2.0.0,>=1.0.1
Requires-Dist: openai
Requires-Dist: python-dotenv
Requires-Dist: ipython
Requires-Dist: art
Requires-Dist: pyperclip
Requires-Dist: numpy
Requires-Dist: h5py
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: requests
Requires-Dist: packaging>=23
Requires-Dist: ase
Requires-Dist: seekpath>=2.1
Provides-Extra: postprocess
Provides-Extra: qwen
Provides-Extra: all
Description-Content-Type: text/markdown

# LatticeMind

**The AI agent for materials science.** Describe the calculation you want in
plain words; LatticeMind plans it, writes the solver inputs, validates them,
runs them, and reports the physics with its own assessment of whether the
numbers are trustworthy.

**RESCU** is fully supported. **NanoDCAL** support is experimental, and **VASP**
support is early and experimental.

---

## Install

CPython 3.10 through 3.14, on Linux x86-64, Windows AMD64, or macOS. Install into a
virtual environment -- `python3 -m venv .venv && source .venv/bin/activate` -- so
`pip` cannot resolve to a different interpreter than the one you mean.

Install from the Nanoacademic PyPI index. LatticeMind's dependencies come from public
PyPI, so pip needs both indexes:

```bash
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install \
  --index-url https://pypi.nanoacademic.ca/simple/ \
  --extra-index-url https://pypi.org/simple/ \
  lattice-mind
```

Add `--upgrade` to move to a newer release, and check what you got with
`latticemind --version`. Interactive CLI and Web startup print that command when
the public index contains a newer compatible stable wheel; set
`LATTICEMIND_UPDATE_CHECK=0` to disable the once-daily check. Startup waits at
most 1.5 seconds for the notice. Unreleased builds live on the
password-protected staging index;
see [docs/pypi_index.md](docs/pypi_index.md) for that, for how releases reach each index,
and for installing from a wheel file directly.

## Configure

LatticeMind needs one AI provider key. Put it in a `.env` file in the directory
you work from, or export it as an environment variable.

```env
OPENAI_API_KEY=sk-your-key-here
```

That is the only required setting — everything else has a working default.
Common additions:

```env
# Optional: fetch exact structures by Materials Project id ("scf for Al: mp-134")
MATERIALS_PROJECT_API_KEY=your_key_here

# Optional: where the RESCU solver lives, if it is not on PATH
LATTICEMIND_RESCU_CMD=/path/to/rescu

# Optional: RESCU license file (defaults to ~/.nanoacademic/RESCU)
LATTICEMIND_LICENSE_FILE=/path/to/license.lic
```

Prefer a different model provider? Set `RESCU_LLM_PROVIDER` to `openai`,
`claude`, `gemini`, `qwen`, or `ollama` and supply that provider's key.
See [INSTALL.md](INSTALL.md#ai-provider--models) for every variable.

## Run

```bash
latticemind          # interactive assistant
latticemind-web      # browser dashboard at http://127.0.0.1:7865
```

Inside the app, `/examples` lists ready-to-run prompts and `/commands` shows
what LatticeMind can do.

## What you can ask for

| | example |
|---|---|
| Ground state | `scf for silicon` |
| Electronic structure | `scf + bs + dos for Si: mp-149` |
| Band gap | `compute the band gap of SiC: mp-8062` |
| Magnetism | `spin-polarized scf for bcc Fe and report the magnetic moment` |
| Relaxation | `relax the structure of Si and report the relaxed lattice constant` |
| Convergence study | `k-point convergence for Si at 6x6x6, 8x8x8 and 12x12x12` |

Naming a Materials Project id builds from that exact published cell. Without an
id, LatticeMind uses its curated crystal reference table.

`/examples` inside the app covers a wider range, including phonons, defect
formation energies and strain comparisons.

## Running calculations

Generating and validating inputs needs nothing but an API key. To *execute*
calculations you also need the solver and, for RESCU, a license. A runtime
pseudopotential bundle ships with the package, so no separate download is needed
for the elements it covers.

Results land in `./latticemind_outputs/<timestamp>_<your-request>/`, with the
generated inputs, raw solver output, figures, and an HTML report.

## Documentation

**The full LatticeMind manual ships with the package.** After installing, find
it under `rescu_agent/latticemind_manual/` in your Python environment, including
`LatticeMind_Documentation_v0.3.1.pdf` and chapters covering:

- installation, API keys and solver setup
- your first project, and how the pipeline works
- the interactive assistant, the web dashboard, and command reference
- releasing long calculations and reattaching to them later
- remote and HPC execution
- every configuration setting
- worked tutorials

| | |
|---|---|
| [INSTALL.md](INSTALL.md) | installation, `.env` configuration, deployment, HPC, troubleshooting |
| [CHANGELOG.md](CHANGELOG.md) | release history |
| [docs.nanoacademic.com](https://docs.nanoacademic.com/) | solver documentation |

## Support

Nanoacademic Technologies Inc. — support@nanoacademic.com
