quasar-core 0.1.0

QUASAR: Quantum Universal Autonomous System for Atomistic Research

Quantum Universal Autonomous System for Atomistic Research

A research-ready autonomous computational chemistry agentic system. QUASAR covers the full atomistic simulation pipeline with integrated tools including Density Functional Theory (DFT), Machine Learning Potentials (MLP), Molecular Dynamics (MD), and Grand Canonical Monte Carlo (GCMC), allowing scientists to rapidly iterate on hypotheses, explore large design spaces, and accelerate the discovery of novel materials and phenomena.

Quick Start

1. Install Docker or Singularity

• Docker: Docker Desktop (Mac/Windows) or Docker Engine (Linux).
• HPC: Singularity for cluster environments.

2. Pull the Image

Get the latest version from Docker Hub:

docker pull fengxuyang/quasar:<tag>

3. Choose Your Interface

• CLI — Terminal-based interactive interface with essential functionalities; see CLI below.

• Batch — Headless automated execution for background or HPC tasks; see Batch Jobs below.

• Web — A premium web-based experience offering advanced usage, fine-grained control, and rich visualisation; currently in private beta, contact us at [e-mail] for early access.

CLI

Run QUASAR interactively from the terminal or inspect run history.

Docker — Interactive

docker run -it --rm \
  -e MODEL_API_KEY=<api_key> \
  -e MODEL=<model_name> \
  -v "<workspace_path>:/workspace" \
  fengxuyang/quasar:<tag> \
  quasar

Singularity (HPC) — Interactive

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

quasar history

After a run (or when resuming from a checkpoint), the CLI can show per-task run history from the current workspace checkpoint. This is useful to review what the operator and evaluator did for each task without re-running.

• Command: quasar history
• Requires: A workspace with an existing checkpoint (from a current or past run).
• Behavior: Starts an interactive view that lists all tasks (e.g. task_1, task_2, …). Use ↑/↓ to select a task and Enter to open it. For the selected task you see the full step-by-step history: task description, operator tool calls (e.g. code snippets, file reads, searches), code outputs, and the evaluator’s summary for that task. Use ESC to go back to the task list; Ctrl+C or Ctrl+D to exit.

If no checkpoint exists, quasar history reports that you need to run quasar first or resume an interrupted session.

Batch Jobs

Automate your research with one-off batch jobs for headless execution.

Docker — Batch (headless)

Pass a prompt as an argument for automated jobs:

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

Singularity (HPC) — Batch (headless)

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

Configuration

Configure the system via environment variables (Web and CLI):

Variable	Description	Default
MODEL_API_KEY	Required. Your API key (Gemini, Claude, OpenAI, etc.).	-
MODEL	Required. Model name.	-
ACCURACY	eco (fast/balanced) or pro (maximum rigor).	eco
GRANULARITY	Workflow task breakdown level (low, medium, high).	medium
ENABLE_RAG	Enable/disable documentation search.	true
IF_RESTART	Resume from the last checkpoint.	false
PMG_MAPI_KEY	Materials Project API key for pymatgen.	-
CHECK_INTERVAL	Minutes between LLM check-ins for long Python runs.	15

Workspace Structure

All outputs are saved within the mounted workspace directory:

workspace/
├── final_results/      # Final outputs and analysis from the current run
│   └── summary.md      # Results summary
├── logs/               # Execution logs and usage reports
│   ├── usage_report.md # Token usage and cost breakdown
│   ├── overview.md     # High-level run summary
│   ├── input_messages.md # Input prompts sent to the agent
│   └── conversation/   # Conversation history
├── checkpoints.sqlite  # Checkpoint database for resumption
├── checkpoint_settings.json  # Run settings and token stats
├── archive/            # Historical runs (preserved across runs)
│   ├── run_1/          # First completed run
│   │   ├── final_results/
│   │   ├── logs/
│   │   └── ...         # All workspace files from that run
│   └── run_N/          # Subsequent runs
└── docs/               # Downloaded documentation (preserved)

When a run completes:

1. All workspace files are copied to archive/run_N/
2. Checkpoint files are removed from the workspace
3. The archive/ and docs/ directories are preserved for future runs

Restart

QUASAR automatically checkpoints progress during execution. To resume from the last checkpoint:

Docker:

docker run --rm -e IF_RESTART=true \
  -v "<workspace_path>:/workspace" \
  fengxuyang/quasar:<tag> quasar

Singularity:

singularity exec --cleanenv \
  --env IF_RESTART=true \
  -B "<workspace_path>:/workspace" \
  --home "<workspace_path>:/workspace" \
  <tag>.sif quasar

When changing hardware (e.g., moving to a different node or GPU):

1. Ensure the same workspace path is mounted
2. Set IF_RESTART=true to resume from the checkpoint
3. The system will continue from exactly where it left off

Note: Checkpoints are stored in checkpoints.sqlite within the workspace. Completed runs are archived to archive/run_N/ with their checkpoint data preserved.

Acknowledgements

QUASAR is built upon a foundation of powerful open-source tools and research. We gratefully acknowledge the following projects: Quantum ESPRESSO, ASE, MACE, pymatgen, LAMMPS, and RASPA3.

Citation

If you find QUASAR useful for your research, please cite our benchmark paper:

Yang, Fengxu, and Jack D. Evans. "QUASAR: A Universal Autonomous System for Atomistic Simulation and a Benchmark of Its Capabilities." arXiv:2602.00185, 30 Jan. 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

For inquiries, advanced features, or beta access, please reach out to: [e-mail]