quasar-core 0.3.0

QUASAR: Quantum Universal Autonomous System for Atomistic Research

Quantum Universal Autonomous System for Atomistic Research

Autonomous computational chemistry for end-to-end atomistic workflows.

QUASAR is a research-focused autonomous system for atomistic simulation and materials modeling. It combines LLM planning, scientific software execution, and reproducible workspace management in a single workflow so researchers can move from prompt to structured results with less manual orchestration.

The platform is designed for computational chemistry and materials science tasks spanning density functional theory (DFT), machine-learning potentials (MLPs), molecular dynamics (MD), and adsorption or Monte Carlo studies. QUASAR can plan multi-step work, execute tools, retrieve documentation, checkpoint progress, and archive outputs for later inspection.

Documentation: QUASAR Docs
PyPI: quasar-core
Paper: arXiv:2602.00185

Why QUASAR

• End-to-end automation: turn a scientific request into a planned workflow, executed tasks, validated intermediate results, and a final summary.
• Research-oriented tooling: support workflows that involve DFT, machine-learning potentials, molecular dynamics, and adsorption simulations.
• Traceable runs: keep checkpoints, logs, run summaries, archived workspaces, and per-task history for reproducibility and review.
• Practical interfaces: use the interactive CLI for guided work or run prompts headlessly for batch and HPC use cases.
• Flexible deployment: run QUASAR with Docker, Singularity, or a local Python installation.
• Configurable execution: tune rigor, task granularity, context compression, retrieval, and even per-agent model selection.

Architecture at a Glance

Component	Role
Strategist	Breaks the user request into a structured execution plan.
Operator	Executes tools, reads and writes files, and runs the scientific workflow.
Evaluator	Reviews task outcomes and decides whether work is ready to proceed.
Workspace layer	Stores checkpoints, logs, summaries, archives, and generated artifacts.
Retrieval layer	Optionally indexes documentation and serves grounded context during runs.

Documentation Map

• Get Started for Docker, Singularity, and local installation.
• Quick Tutorial for a first end-to-end run.
• CLI Reference for interactive, headless, resume, and cleanup commands.
• Configuration for environment variables and execution profiles.
• Workspace & History for logs, archives, and checkpoint behavior.
• Extending QUASAR for adding dependencies or adapting the environment.
• Contact for issues, collaboration, and support.

Quick Start

QUASAR supports three deployment paths:

• Docker is the recommended default for laptops and workstations.
• Singularity is the best fit for HPC and shared cluster environments.
• Local deployment is useful when you need a custom native environment, but it is typically less isolated.

Docker

Pull the image:

docker pull fengxuyang/quasar:<tag>

Launch the interactive CLI:

docker run -it --rm \
  -v "<workspace_path>:/workspace" \
  fengxuyang/quasar:<tag> \
  quasar

Run a headless prompt:

docker run --rm \
  -e MODEL=<model_name> \
  -e MODEL_API_KEY=<api_key> \
  -v "<workspace_path>:/workspace" \
  fengxuyang/quasar:<tag> \
  quasar "Calculate the band gap of silicon"

Singularity

Build the .sif image from Docker Hub:

singularity build quasar.sif docker://fengxuyang/quasar:<tag>

Run QUASAR:

singularity exec --cleanenv \
  -B "<workspace_path>:/workspace" \
  --home "<workspace_path>:/workspace" \
  quasar.sif quasar

Run a headless prompt:

singularity exec --cleanenv \
  -B "<workspace_path>:/workspace" \
  --home "<workspace_path>:/workspace" \
  --env MODEL=<model_name> \
  --env MODEL_API_KEY=<api_key> \
  quasar.sif quasar "Your research prompt here"

Local Installation

Prerequisites:

• Python 3.10 or newer
• Node.js 20 or newer for the local interactive CLI
• Scientific software installed separately as needed for your workflows

Example setup:

conda create -n quasar python=3.11 -y
conda activate quasar
conda install -c conda-forge qe lammps raspa3 raspalib -y
pip install --upgrade pip
pip install quasar-core

Launch QUASAR:

export WORKSPACE_DIR=<workspace_directory>
quasar

Run a headless prompt:

export MODEL=<model_name>
export MODEL_API_KEY=<api_key>
export WORKSPACE_DIR=<workspace_directory>
quasar "Your research prompt here"

Interactive sessions can fill missing MODEL and MODEL_API_KEY values through the built-in \settings panel. Headless runs should still provide required variables before launch.

The first run in a new workspace can be slower because QUASAR may prepare documentation assets, retrieval indexes, and embedding resources.

CLI Reference

Command	What it does
quasar	Starts the interactive terminal UI.
quasar "..."	Runs a direct prompt in headless mode.
quasar --resume	Resumes the active checkpoint.
quasar --clear	Clears the active checkpoint and current workspace state while preserving archives and docs.
quasar --fresh	Clears current workspace state and archived runs while preserving docs and hidden cache directories.
quasar --history	Opens the interactive per-task checkpoint history browser.
quasar --config	Prints the current configuration values.
quasar --config validate	Verifies required configuration such as MODEL_API_KEY.
quasar --info	Prints system and workspace information.
quasar --no-rag "..."	Runs a prompt without documentation retrieval for that session.

Configuration Snapshot

Variable	Purpose	Default
MODEL	Required model name.	None
MODEL_API_KEY	Required provider API key.	None
OPENAI_API_BASE	Optional base URL for OpenAI-compatible endpoints.	None
ACCURACY	Planning and execution rigor: eco, standard, pro.	standard
GRANULARITY	Task decomposition depth: low, medium, high.	medium
CONTEXT_THRESHOLD	Context-compression trigger level.	medium
ENABLE_RAG	Enable documentation retrieval.	true
CHECK_INTERVAL	Minutes between long-run check-ins. Leave unset or use 0 to disable.	Disabled
AUTO_IMPROVE_CYCLES	Automatic follow-up refinement cycles after a successful run.	0
NUM_CORES	Override detected physical core count.	Auto
PMG_MAPI_KEY	Materials Project API key for pymatgen.	None
HF_TOKEN	Optional Hugging Face token for authenticated retrieval access.	None
IF_RESTART	Resume from the last checkpoint.	false

Per-agent overrides are also available:

Agent	Model	API key	Base URL
Strategist	STRATEGIST_MODEL	STRATEGIST_MODEL_API_KEY	STRATEGIST_API_BASE_URL
Operator	OPERATOR_MODEL	OPERATOR_MODEL_API_KEY	OPERATOR_API_BASE_URL
Evaluator	EVALUATOR_MODEL	EVALUATOR_MODEL_API_KEY	EVALUATOR_API_BASE_URL

QUASAR is currently optimized for Gemini-oriented setups. Other providers may work, especially through supported integrations and compatible endpoints, but they are not yet the primary compatibility target.

Workspace Outputs

QUASAR writes all outputs into the mounted workspace directory:

workspace/
├── final_results/              # Final outputs and analysis from the current run
│   └── summary.md              # Main written summary
├── logs/                       # Execution logs and run reports
│   ├── usage_report.md
│   ├── execution_overview.md
│   ├── input_messages.md
│   └── conversation/
├── archive/                    # Historical runs preserved across normal cleanup
│   ├── run_1/
│   └── run_N/
├── docs/                       # Downloaded documentation
├── .rag_index/                 # Cached retrieval index and embeddings
├── checkpoints.sqlite          # Checkpoint database
├── checkpoint_settings.json    # Run settings and token statistics
└── ...

When a run completes, QUASAR archives the workspace state, removes active checkpoint files, and keeps reusable assets such as archive/, docs/, and hidden cache directories available for future runs.

Resume and Cleanup

• Use quasar --resume to continue an interrupted run.
• Use quasar --clear to remove the active checkpoint and current workspace state while keeping archived runs and docs.
• Use quasar --fresh to remove current workspace state and archived runs while preserving docs and hidden cache directories.

Checkpoint metadata restores non-secret settings such as model choice, accuracy, granularity, and retrieval options. API keys should still be supplied through environment variables or the interactive \settings panel before resuming.

Acknowledgements

QUASAR builds on a strong open-source scientific software ecosystem. In particular, the project draws on tools and libraries including Quantum ESPRESSO, ASE, MACE, pymatgen, LAMMPS, and RASPA3.

Citation

If QUASAR is useful in your research, please cite:

Yang, Fengxu, and Jack D. Evans. "QUASAR: A Universal Autonomous System for Atomistic Simulation and a Benchmark of Its Capabilities." arXiv:2602.00185, 2026. https://doi.org/10.48550/arXiv.2602.00185

@misc{yang2026quasar,
  title={QUASAR: A Universal Autonomous System for Atomistic Simulation and a Benchmark of Its Capabilities},
  author={Fengxu Yang and Jack D. Evans},
  year={2026},
  eprint={2602.00185},
  archivePrefix={arXiv},
  primaryClass={physics.chem-ph},
  url={https://arxiv.org/abs/2602.00185}
}

Contact

• Technical issues and feature requests: GitHub Issues
• Collaboration, advanced features, beta access, or partnership inquiries: [e-mail]