Skip to content

Quickstart

This guide verifies the model connection, runs a lookup, performs a small EMT calculation, and shows where results are stored.

1. Install ChemGraph

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install chemgraph

Prefer uv? Use it to create the same environment and install ChemGraph:

uv venv
source .venv/bin/activate              # Windows: .venv\Scripts\activate
uv pip install chemgraph

See Installation if you need source or optional-extra setup.

2. Choose one model route

For OpenAI:

export OPENAI_API_KEY="..."

For Argonne's Argo gateway:

export ARGO_USER="<anl-username>"

Or start Ollama locally and use --model llama3.2 without an API key. See Models and authentication for other providers and exact model IDs.

List registered models and check credentials:

chemgraph models
chemgraph run --check-keys

The commands below use the default gpt-4o-mini. For Argo, add --model argo:gpt-4o to each chemgraph run command.

3. Run a lookup

chemgraph run -q "What is the SMILES string for aspirin?"

This request uses an LLM and PubChem, so it requires network access. Add -v for INFO diagnostics or -vv for DEBUG output.

4. Run a small calculation

EMT is bundled, fast, and requires no model download:

chemgraph run \
  --output last_message \
  -q "Build water from SMILES O, optimize it with EMT, and report the final energy."

Agent-generated tool selection is probabilistic. Explicitly naming EMT makes this a more reliable installation check than asking the agent to choose any calculator.

5. Inspect results

Each run creates a session directory under cg_logs/, for example:

cg_logs/session_20260101_120000_a1b2c3d4/

Depending on the tools called, it can contain structures, trajectories, JSON or CSV results, spectra, and HTML reports. Direct artifacts elsewhere by setting the environment variable before starting ChemGraph:

export CHEMGRAPH_LOG_DIR="$PWD/my_chemgraph_runs"

6. Continue

  • Learn output, session, and interactive options in the CLI guide.
  • Compare agent architectures in Workflows.
  • Review model and scientific-engine requirements in Calculators.
  • Use ChemGraph from an application with the Python API.
  • Diagnose setup problems with Troubleshooting.