Skip to content

BMD Agent

Jump to bottom
Lee Burton edited this page Sep 29, 2026 · 6 revisions

BMD Agent is the BMD Lab's interface for working with the group's computational infrastructure, scientific tools, and research evidence.

Public ChatGPT is useful for general scientific conversation. It can explain materials science, help write code, and answer broad questions. BMD Agent is for questions that depend on the BMD environment: real BMD Compute runs, VASP artifacts produced on PowerSLURM under BMD/TAU permissions, authorized calculation files, BMDex scientific tools and curated evidence, and, where configured, calculation history or approved institutional databases and APIs.

The point is not that BMD Agent's language model is inherently smarter than a public assistant. Its value is that reasoning can be connected to BMD-specific evidence and approved tools that a public assistant cannot legitimately or practically access.

BMD Agent does not replace BMD Compute, BMDex, BMDwiki, or the BMD Lab website. It connects information from those systems while preserving where evidence came from and which system is authoritative for what.

Not all long-term integrations exist yet. The current command-line functions are listed below.

When to use it

Use public ChatGPT for general questions, such as learning a concept, drafting Python code, or asking how VASP, pymatgen, SLURM, or DFT usually work.

Use BMD Agent when the question is specific to BMD Lab evidence or infrastructure, for example:

  • What actually happened in my BMD Compute/VASP calculation?
  • Why did my PowerSLURM calculation terminate?
  • How does this run compare with another one?
  • What can BMD Compute currently execute?
  • What settings does BMD Compute generate for a calculation?
  • Has the group calculated something related before?
  • Eventually: can approved institutional literature or database tools find prior work on this material?

The current command-line tool supports the calculation and infrastructure inspection tasks described below. BMDex search, calculation-history search, and institutional literature or database tools depend on configured or future integrations and should not be assumed to work in every deployment.

How the BMD sources fit together

  • BMD Compute - the executable calculation implementation. It decides what calculation stages and workflows run, and with which settings.
  • PowerSLURM and VASP artifacts - evidence of what physically executed and what files or results were produced.
  • BMDex - curated supporting data, evidence and tools: datasets, reference evidence, reusable scientific resources, scripts, examples, and approved scientific tools, including API or search utilities where appropriate.
  • BMDwiki - tutorials, explanations, onboarding, and historical or contextual guidance. Its examples are for learning; it is not authoritative over BMD Compute or BMDex.
  • BMD Agent - observes and reasons across these sources while preserving provenance and authority boundaries.

BMD Compute is authoritative for how BMD VASP calculations are generated and executed. BMDex supplies curated supporting data, evidence and tools. Scientific validation and adoption are separate human review. BMDwiki explains things for people.

What Agent tries to separate

When inspecting a calculation or resource, BMD Agent tries to distinguish:

  • what was requested;
  • what actually executed;
  • what the scheduler observed;
  • what artifacts exist;
  • what can independently be derived from those artifacts;
  • what evidence is unavailable.

This distinction matters. "Unavailable" is better than inventing evidence or silently filling gaps with assumptions.

Current access and safety

BMD Agent currently operates read-only. It can inspect authorized BMD resources and provide evidence-backed analysis, but it does not currently submit or cancel calculations, alter authoritative repositories, adopt methodology, deploy services, publish information, or expose arbitrary cluster shell access.

Scientific conclusions still require human validation. The agent should keep important distinctions clear, for example:

  • an ML prediction is not a DFT result;
  • a completed calculation is not automatically a validated calculation;
  • a tutorial example, or a calculation set up outside BMD Compute, does not show how BMD Compute generates calculations;
  • absence from a database does not prove novelty;
  • negative formation energy is not the same as thermodynamic stability against competing phases.

Command-line use

Where BMD Agent is installed and configured, the normal interface is three forms:

bmd-agent            # analyse the calculation in the current directory
bmd-agent JOB_ID     # inspect a SLURM job
bmd-agent PATH       # analyse a calculation or workflow at PATH
  • No target - analyses the calculation in your current working directory.
  • JOB_ID - a SLURM job ID (a positive whole number). Agent inspects that job and links it to its BMD Compute run when the available evidence allows.
  • PATH - an existing calculation or workflow directory on the machine where you run bmd-agent, for example a local or copied calculation.

For example:

cd /path/to/calculation
bmd-agent

bmd-agent 21853598
bmd-agent ./copied-calculation

By default Agent prints a short diagnosis. Add --verbose to any of the three forms for the detailed evidence, including provenance, parser limitations and scheduler accounting:

bmd-agent --verbose
bmd-agent 21853598 --verbose
bmd-agent ./copied-calculation --verbose

For job inspection, --profile adds developer-oriented performance telemetry; you do not need it for normal use.

Advanced usage

Expert subcommands remain available for specific tasks. You do not need them for normal use:

bmd-agent status
bmd-agent job <SLURM_JOB_ID> [--trajectory-json | --verbose [--profile] | --profile]
bmd-agent queue
bmd-agent compute
bmd-agent structure <remote-directory>
bmd-agent inspect-run <remote-flow-root>
bmd-agent compare-runs <flow-a> <flow-b> [<flow-c> ...]
bmd-agent diagnose-run <remote-flow-root>

What the advanced subcommands are for:

  • status - check the configured BMD repositories that Agent is allowed to inspect.
  • queue - summarize the configured BMD PowerSLURM queue view.
  • job - the explicit form of bmd-agent JOB_ID, with extra output options such as --trajectory-json.
  • compute - show what BMD Compute currently advertises as executable.
  • structure - read structural information from an authorized remote calculation directory.
  • inspect-run - ask "what happened?" for a BMD Compute run by collecting available provenance, scheduler, artifact, and parsed-result evidence.
  • compare-runs - ask "what changed?" between related run directories.
  • diagnose-run - ask "what was happening while the calculation ran?" using descriptive termination and trajectory evidence.

diagnose-run is descriptive. It should not be read as a prediction that a calculation will converge, or as a claim that adding walltime will solve the problem.

The remote-path subcommands read only from authorized PowerSLURM locations.

Permissions and future direction

BMD Agent is intended to work within BMD and TAU permissions. It must respect VASP licensing, POTCAR restrictions, database and API licensing, institutional permissions, credentials, and PowerSLURM access rules.

The long-term goal is for approved tools to use required access without exposing credentials to users or making credentials part of the agent's reasoning context.

Possible future capabilities include approved BMDex literature, API, and database tools; searching BMD calculation history; evidence-based convergence assistance; broader BMD Compute workflows such as phonons and defects; calculation planning; and evidence-aware recommendations.

These are directions, not promises about current functionality.

Related tutorials

Clone this wiki locally