A unified toolkit for quantum chemistry DFT calculations, supporting CRYSTAL23, Quantum Espresso, and VASP. Uses a primary Python/Textual TUI ("Workshop") with an optional Rust/Ratatui TUI ("Cockpit") for high-performance monitoring.
| Code | Status | Input Style | Energy Unit |
|---|---|---|---|
| CRYSTAL23 | Full Support | .d12 stdin |
Hartree |
| Quantum Espresso | Full Support | .in flag |
Rydberg |
| VASP | Full Support | Multi-file (POSCAR, INCAR, KPOINTS, POTCAR) | eV |
- Production-grade modular Bash architecture
- Automatic MPI/OpenMP hybrid parallelism
- Scratch space management with cleanup
- Visual feedback with gum
- Educational
--explainmode
- Primary UI for job creation, configuration, and workflows
- Textual-based async interface
- Tight integration with the Python scientific stack (AiiDA/pymatgen/ASE)
- Optional high-performance monitoring UI (Ratatui)
- Great for dense job/log dashboards
- Under feature freeze until IPC boundary replaces PyO3 — see ADR-002
- Permitted: bug fixes, security patches, IPC migration prep
cd cli/
# Set environment
export CRY23_ROOT=~/CRYSTAL23
export CRY_SCRATCH_BASE=~/tmp_crystal
# Run CRYSTAL calculation
bin/runcrystal my_calculation
# Run with MPI (14 ranks)
bin/runcrystal my_calculation 14
# Show execution plan
bin/runcrystal my_calculation --explaincd tui/
crystal-tui# From crystalmath/ root
# Build (first time or after Python version changes)
./scripts/build-tui.sh
# Launch the unified tool
./target/release/crystalmath
# Keyboard shortcuts:
# 1-4 - Switch tabs (Jobs, Editor, Results, Log)
# n - Create new job (formerly Workshop feature)
# c - Cluster Manager
# s - SLURM Queue
# v - VASP Input Manager
# Tab - Next tab
# j/k - Navigate up/down
# Ctrl+R - Refresh jobs
# Ctrl+I - Import from Materials Project (Editor tab)
# Ctrl+Q - Quit- 27/27 issues closed (100%)
- 9 modular library components
- 76 unit tests
- Primary UI for workflows and configuration.
- Backend: Python scientific logic (AiiDA, parsers, runners).
- Features:
- Multi-code support (CRYSTAL23, QE, VASP)
- Remote execution (SSH, SLURM)
- Materials Project integration
- Optional high-performance cockpit for monitoring.
- Feature freeze in effect — see ADR-002 for policy.
crystalmath/
├── src/ # Rust TUI (secondary/experimental)
│ ├── main.rs # Entry point
│ ├── app.rs # State management & Tests
│ ├── bridge.rs # PyO3 bridge
│ ├── models.rs # Shared data models
│ └── ui/ # UI Components (New Job, Results, etc.)
│
├── python/ # Python Backend
│ └── crystalmath/
│ ├── api.py # Facade for Rust
│ └── models.py # Pydantic models
│
├── cli/ # Bash CLI tools
│
└── tui/ # Python TUI (primary)
The system follows a "Python-first UI with optional Rust cockpit" model:
- Primary UI (Python/Textual): Handles user interaction and workflows.
- Secondary UI (Rust/Ratatui): Optional high-performance cockpit. Should communicate via IPC rather than embedding Python.
- Backend (Python): Scientific logic, database access, and HPC communication.
- Database: SQLite (
.crystal_tui.db) shared source of truth.
- Native stdin invocation
- Environment from
cry23.bashrc - Full parser for energy, convergence, geometry
- Flag-based invocation (
pw.x -in input.in) - SCF, relaxation, vc-relax support
- K-point and convergence threshold templates
- Multi-file handling (VASPInputFiles class)
- INCAR, KPOINTS, POSCAR, POTCAR management
- Relaxation → SCF workflow chains
# templates/qe/scf.yml - Quantum Espresso SCF
# templates/vasp/relax.yml - VASP geometry optimization# templates/workflows/vasp_relax_scf.yml
workflow:
nodes:
- id: "relax"
template: "vasp/relax"
- id: "transfer_structure"
type: "data_transfer"
file_renames: {"CONTCAR": "POSCAR"}
- id: "scf"
template: "vasp/scf"- Bash 4.0+
- CRYSTAL23 installation
- Optional: gum, mpirun
- Python 3.10+
- DFT executables in PATH or configured
- See
tui/pyproject.tomlfor dependencies
- Rust 1.70+ (for cargo build)
- Python 3.12 venv (for PyO3)
- Node.js 18+ (for LSP server, optional)
- Optional:
dft-language-server(providesvasp-lsp/dft-lspCLI) - See
Cargo.tomlfor dependencies
npm install -g dft-language-serverTo use the bundled upstream repo:
git submodule update --init --recursive
cd third_party/vasp-language-server
npm install
npm run buildThe Rust TUI will prefer the bundled repo when built (looks for
third_party/vasp-language-server/out/server.js). It falls back to the
vasp-lsp command on PATH, and you can override either with
CRYSTAL_TUI_LSP_PATH.
# CLI tests
cd cli/ && bats tests/unit/*.bats
# Python TUI tests
cd tui/
pytest # All tests
pytest --cov=src # With coverage
black src/ tests/ # Format
ruff check src/ tests/ # Lint
mypy src/ # Type check
# Rust TUI tests
cd crystalmath/
cargo test # All tests (44)
cargo clippy # Lint
cargo fmt --check # Format check
./scripts/build-tui.sh # Build with correct PythonUses beads (bd command):
bd list # Open issues
bd list --all # All issues
bd show <issue-id> # Details
bd create "Title" # New issueCurrent Epic: crystalmath-as6l - TUI Unification (Python primary, Rust secondary)
Full documentation is available in the docs/ directory:
- Getting Started: Installation and setup guides
- User Guide: Manuals for TUI and CLI usage
- Architecture: System design and module details
- Development: Contributing guidelines and testing
- CLI: Production-ready with 76 tests
- Python TUI Phase 1-2: Core TUI, remote runners, templates
- Multi-Code Support: CRYSTAL23, QE, VASP
- Rust TUI Core: 60fps monitoring, PyO3 bridge, LSP editor
- Epic 5hh: TUI UX Excellence ("Cockpit vs Workshop")
- Database unification
- Empty state UX
- Live log streaming
- Job status dashboard
- Phase 4: Materials Project API integration
- AiiDA: Full provenance tracking
- Rust TUI IPC: Optional Rust cockpit via stable IPC boundary
MIT License
Repository: github.com/TheFermiSea/CrystalMath (private)