Metadata-Version: 2.2
Name: lattice-mind
Version: 0.4.0
Summary: LatticeMind: The AI agent for materials science.
Keywords: materials science,DFT,density functional theory,RESCU,VASP,NanoDCAL,computational chemistry,AI agent
Author: Nanoacademic Technologies Inc.
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** is supported across all 40 calculation
types its manual documents — ground state, electronic structure, phonons, and
two-probe quantum transport — verified by a 60-case benchmark executed both on a
local installation and on an HPC cluster. **VASP** support is in preview.

---

## 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.

## License

LatticeMind is licensed separately from RESCU: a RESCU license does not activate
it, and it does not activate RESCU. Put exactly one `*.lic` or `*.license` file
in `~/.nanoacademic/LATTICEMIND` — on Windows,
`C:\Users\<YourUsername>\.nanoacademic\LATTICEMIND` — or point
`LATTICEMIND_LICENSE_FILE` at its exact path. LatticeMind checks it at startup,
before the CLI or Web UI opens, whichever solver is selected.

To obtain a license, contact support@nanoacademic.com.

## 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 beyond the license — 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: exact LatticeMind license file, if it is not in ~/.nanoacademic/LATTICEMIND
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` |
| Quantum transport (NanoDCAL) | `Using NanoDCAL, run a transmission calculation along z for a homogeneous aluminum two-probe device` |
| Continuing a project | `Now compute the current-voltage curve for the same device from 0 to 0.4 V in 0.2 V steps` |

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 the LatticeMind license and an API key.
To *execute* calculations you also need the solver itself, installed and
licensed on the machine that runs it. A runtime pseudopotential bundle ships
with the package, so no separate download is needed for the elements it covers.

A project is a conversation, not a single request. Follow-up turns build on
what the project already holds: a request to add a Seebeck coefficient to a
finished conductance project inherits the device, the material, and the settings
the project was founded on, adds only the missing steps, and reuses every
calculation that has already converged. Long calculations can be released with
`--detach` and collected on a later turn; a remote profile (`--remote-profile`)
runs them on a workstation or cluster. Spending on metered AI providers is capped
per turn and per session (`LATTICEMIND_MAX_COST_PER_TURN_USD`,
`LATTICEMIND_MAX_COST_PER_SESSION_USD`; defaults 5 and 25 USD).

```bash
latticemind run "Using NanoDCAL, run a conductance calculation along z for a homogeneous copper two-probe device" \
    --solver nanodcal --execute --approve-execution --remote-profile my-cluster
latticemind run --project <project-dir> "Add a Seebeck coefficient calculation to this project, reusing everything it already has" \
    --execute --approve-execution --remote-profile my-cluster
```

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.4.0.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.

Technical support, bug reports and feature requests go to the [Nanoacademic Customer Support Center](https://nanoacademic.atlassian.net/servicedesk/customer/portal/1).
