diff --git a/use_cases/tokamak_stability/AGENTS.md b/use_cases/tokamak_stability/AGENTS.md index f2f4ea1..a8a2d2e 100644 --- a/use_cases/tokamak_stability/AGENTS.md +++ b/use_cases/tokamak_stability/AGENTS.md @@ -1,8 +1,8 @@ # Agent Guide - tokamak_stability -## Codes +## Tools -This subdirectory provides python modules containing functions for interacting with HDF5 data files created by the M3D-C1 finite-element simulation code. Before using these functions, and in particular before registering them as CLI codes, read the agent skill file at `skills/m3dc1-skill/SKILL.md` for calling conventions, input/output formats, and examples. +This subdirectory provides python modules containing functions for interacting with HDF5 data files created by the M3D-C1 finite-element simulation code. Before using these functions, and in particular before registering them as CLI tools, read the agent skill file at `skills/m3dc1-skill/SKILL.md` with respect to this directory, for calling conventions, input/output formats, and examples. If you cannot find the skill file, stop and ask the user for guidance before continuing. The three python modules containing useful functions are: `m3dc1_tools.py`, `m3dc1_plots.py`, and `hdf5.py`. diff --git a/use_cases/tokamak_stability/README.md b/use_cases/tokamak_stability/README.md index 214b8dd..cf45769 100644 --- a/use_cases/tokamak_stability/README.md +++ b/use_cases/tokamak_stability/README.md @@ -1,17 +1,41 @@ -# Fusion energy use case +--- +title: Tokamak Stability +domain: Fusion energy - explore finite-element simulation data +summary: >- + Register tools for reading, analyzing, and visualizing data from the + M3D-C1 finite-element code. Use DSAgt to explore an example dataset, + produce a range of plots, and generate and repackage secondary data products. + Save the pipeline as a script that can be rerun across other similar datasets. +--- -> **Estimated time:** advanced / not a 10-minute demo. Setup is the cost: -> building the **fusion-io** C/C++ library from source and downloading a -> Google-Drive-hosted **M3D-C1** dataset. Budget an hour+ for first-time setup; -> the agent session itself is ~15 minutes once dependencies and data are in -> place. + +# Tokamak Stability - a fusion energy use case + +> **Estimated time:** involved / not a 10-minute demo. Setup is the cost: +> building the **fusion-io** C/C++ library from source. Additionally, an **M3D-C1** +> dataset is packaged with this use case's necessary text/source files on OSF.io. +> Budget roughly an hour for first-time setup; the agent session itself is ~15 minutes once +> dependencies and data are in place. Here we're going to use dsagt to investigate the stability properties of a tokamak configuration. We'll be looking at linear MHD simulation data produced by the [M3D-C1](https://sites.google.com/pppl.gov/m3d-c1) unstructured-mesh finite-element code. The session below has been tested with Claude Code. +## Example data + +A demonstration dataset, consisting of a single M3D-C1 simulation output, +is available in [this OSF.io directory](https://osf.io/gak3v/files/) as +`tokamak_stability.tar.gz`; an account is not needed for access. +The tarball also includes all necessary source files, so you can +run this use case using a pip-installed dsagt without cloning the repository. +The dataset is courtesy of Alvaro Sanchez-Villar (asvillar@pppl.gov). + +Untar the .tar.gz file somewhere convenient; it will create a `tokamak_stability/` +directory. + + ## Dependencies -In addition a standard dsagt installation you'll also need to build and install the fusion-io library from [https://github.com/nferraro/fusion-io](https://github.com/nferraro/fusion-io). The top commit of the main branch will work. Use these environment variables to point to the fusion-io installation: +In addition to a standard dsagt installation you'll also need to build and install the fusion-io library from [https://github.com/nferraro/fusion-io](https://github.com/nferraro/fusion-io). The top commit of the main branch will work. Use these environment variables to point to the fusion-io installation: ``` export FIO_INSTALL_DIR=/path/to/your/fusion-io/install/ @@ -22,52 +46,49 @@ export DYLD_LIBRARY_PATH=$FIO_INSTALL_DIR/lib:$DYLD_LIBRARY_PATH This use case also comes with a wrapper python module called `m3dc1`, which you may want to add to your PYTHONPATH: ``` -export PYTHONPATH=/path/to/dsagt/use_cases/tokamak_stability:$PYTHONPATH +export PYTHONPATH=/path/to/your/tokamak_stability:$PYTHONPATH ``` -## Example data - -You can download a [demonstration dataset](https://drive.google.com/file/d/1ZghND-G2SInuovLqrg-DVPyECEASPTSq/view?usp=sharing), consisting of a single M3D-C1 simulation output. -This dataset is courtesy of Alvaro Sanchez-Villar (asvillar@pppl.gov). Untar the .tar.gz file somewhere convenient. - ## Getting started - -With dsagt installed, activate the virtual environment from the repository root: +Install dsagt with pip: ``` -source .venv/bin/activate +python3 -m venv +source /bin/activate +pip install "git+https://github.com/AI-ModCon/dsagt.git" ``` -Now create a new dsagt project and associated directory, here called `fusion-use-case`: +Now create a new dsagt project and associated project directory: ``` -dsagt init fusion-use-case --agent claude --location ~/data/ +dsagt init ``` -Here we're using Claude Code; see the dsagt [documentation](https://ai-modcon.github.io/dsagt/) for guidelines for using other agents. The created project directory will be a subdirectory of `~/data/`; omitting this will place your project directories in `~/dsagt-projects/`. +Project directories are placed in `$HOME/dsagt-projects/` by default. If you prefer a different location either give a directory name (in which case the project directory is placed in the current directory or in an appropriate subdirectory) or a full absolute path; do not use `~` or `$HOME` as they will be interpreted literally. Select your agent of choice. + +Every tool execution and agent turn is logged automatically to an SQLite MLflow store `mlflow.db` +in the project directory. We'll use this to reconstruct the session later. -Observability is serverless — there is nothing to start. Every code execution -and agent turn is logged automatically to a SQLite MLflow store at -`~/data/fusion-use-case/mlflow.db`, which we'll use to reconstruct the session -later. Now enter the project directory and start the agent: +Now start the agent and dsagt's MCP server: ``` -cd ~/data/fusion-use-case -claude +dsagt start ``` +Note that here we use the project name and not the name of the project directory, which you choose separately. + ## An example session Inside the agent, enter these prompts one at a time, replacing the placeholder directory paths with the corresponding paths on your system: -- There are three python files in the `/path/to/your/dsagt/use_cases/tokamak_stability` directory containing functions for dealing with HDF5 datasets produced by the M3D-C1 code: `hdf5.py`, `m3dc1_tools.py`, and `m3dc1_plots.py`. Register these functions as codes and print a summary here. Read the `AGENTS.md` file in that directory first. +- Read the `AGENTS.md` file in the `/path/to/your/tokamak_stability` directory. This directory contains three python files with functions for dealing with HDF5 datasets produced by the M3D-C1 code: `hdf5.py`, `m3dc1_tools.py`, and `m3dc1_plots.py`. Register these functions as tools and print a summary here. -Creating and registering the codes may take several minutes. +Creating and registering the tools may take several minutes. -- Using your codes, tell me about the data in the `/path/to/your/m3dc1_data` directory. +- Using your tools, tell me about the data in the `/path/to/your/tokamak_stability/m3dc1_data/` directory. - What are the Miller parameters for this configuration? @@ -75,7 +96,7 @@ Creating and registering the codes may take several minutes. - Make plots of the t=1 fields of the electron temperature, all components of the current density, and the perturbations of the density and magnetic flux. -Plots will go in the `/path/to/fusion-use-case/plots/` subdirectory of your project directory by default. Instruct the agent if you prefer an alternative location. +Plots will go in a `plots/` subdirectory of your project directory by default. Instruct the agent if you prefer an alternative location. - Create plots of the standard poloidal spectra and the kinetic energy trace. @@ -85,24 +106,17 @@ New data products will go to a `processed_data/` subdirectory of your project di - Extract the electron temperature and electron density data at t=1 and place them in an HDF5 file `electrons.h5`. -- Using the MLflow traces in the `mlflow.db` store, create a shell script that recreates this session's code executions on a general data directory that is set at the top of the script. Save as `dsagt_session_script.sh`. +- Using the MLflow traces in the `mlflow.db` store, create a shell script that recreates this session's tool executions on a general data directory that is set at the top of the script. Save as `dsagt_session_script.sh`. -(You can browse those traces any time with -`mlflow ui --backend-store-uri sqlite:///~/data/fusion-use-case/mlflow.db`.) +(You can browse those traces any time by running `mlflow ui --backend-store-uri sqlite:///mlflow.db` from the project directory.) -Now exit the agent session as usual (there is no server to stop — the store is -serverless). +Now exit the agent session as usual (e.g. with the `exit` command). -The project name (here "fusion-use-case") is registered in `~/dsagt-projects/projects.yaml` (default location). You can unregister the project name with +The project name is registered in `~/dsagt-projects/projects.yaml` (default location). You can unregister the project name with ``` -dsagt rm fusion-use-case +dsagt rm ``` You will be asked whether you want to delete the project directory. - - - - -