Skip to content

Overview

This document describes how to use the collection of matlab functions and scripts, collectively called the Tokamak System toolbox or simply TokSys, which provides tools for tokamak system modeling and simulation, model validation, data analysis, and control design.

Help

If any description is incorrect or confusing, please contact Mike Walker at walker@fusion.gat.com.

This document focuses on the description of those portions of TokSys that are applicable to plasma shape and position control design, testing, and data analysis because the methods for those applications have been largely standardized. However, TokSys also contains a number of tools relevant for other control development and analysis tasks, both general (e.g. data access and signal processing) and specific (e.g., for control of NTMs, RWMs, ONFR, etc.).

All models produced using the tools described in this document use the convention that a positive toroidal current is a counter-clockwise current flow when viewed from above. Conductor voltages V are assumed connected such that V>0 causes coil currents Icoil to increase (in the absence of plasma). All data contained in the models described in this document use MKS units by default, i.e. Amps for current, Webers for flux, and Tesla for magnetic field. However, there is an option provided in some of the model calculation tools to produce data objects with currents in Mega-Amp-turns.

Any talks or publications containing results derived from the use of the TokSys toolset should contain an attribution for GA TokSys.

Linearized plasma models for boundary control development

The model building environment consists of matlab functions and scripts to perform the following major functions: - Construct tokamak data objects such as conductor resistances, mutual inductances, and other Green functions, which are all defined by the device geometry in the absence of plasma. - Read in a plasma equilibrium around which a linearized model will be generated. - Combine the tokamak information in (a) with the specified plasma in (b) to generate the linearized model (See equation 1). - Compare the derived linearized model with experimentally measured data, as part of a model validation process.

The TokSys toolbox has been used to derive models for the ITER, EAST, KSTAR, NSTX, MAST-U, DIII-D, SST-1, and Pegasus tokamaks, and the proposed Fusion Development Facility (FDF), among others. The developed models have been validated on DIII-D and NSTX and have been used to develop plasma controllers on DIII-D, ITER, EAST, KSTAR and Pegasus. Although even unvalidated or partially-validated models have proven very useful for developing and testing control software, use in a model-based control design requires that a real model-validation effort must be undertaken and completed before such controllers can be used with confidence in controlling plasmas. Model validation must include testing of individual component models, not just the final integrated model. Large integrated models are virtually never correct the first time used (or the 2nd, 3rd, ...) and typically cannot be made correct without identifying the source(s) of model discrepancy. Identifying sources of model discrepancy requires investigating individual components of the model.

The development and use of a common toolset for multiple devices has significant advantages beyond the obvious issue of software re-use. In all cases, the models generated are first principles physics models, constructed without any "tuning" or "fudge factors", except for use of direct measurements of certain quantities such as coil resistance or inductance. Validation of this type of model versus experimental data on existing devices provides confidence in both the modeling approach and the model implementation when using the tools to extrapolate to model generation for devices that do not yet exist.

Section 3 describes the modeling approach used by TokSys. Section 4 provides an overview of the organization and structure of the many modeling, analysis, and design functions. Section 5 provides instructions for how to make the Toksys tools available in your Matlab session. Section 6 provides a high-level summary list of device-independent modeling and analysis functions that are available when the Toksys tools are available in your session. Section 7 describes the process of constructing plasma response models, outlined in steps (a) through (c) above. Section 8 describes how the core set of generic modeling tools are used and expanded upon for modeling specific tokamaks and plasmas. Section 9 describes the process used for validation of TokSys models and the TokSys tools available to support this process. Section 10 describes a methodology employed to connect simulations constructed using TokSys models with a version of the real-time plasma control system (PCS), for those devices whose PCS is derived from the DIII-D PCS. Section 11 provides further details for some of the modeling tools. This section will be expanded in future versions of this document.

Plasma Control Modeling Approach

The set of modeling tools in this toolbox automate the majority of the process of generating dynamic models for the tokamak and plasma poloidal field systems involved in plasma shape, position, and plasma current control. Key products of the model development process are linear models of the form

\[\begin{equation} \begin{aligned} \dot{I} &= \mathbf{A}I + \mathbf{B}v + \mathbf{F}w \\\ y &= \mathbf{C}I + \mathbf{D}v + \mathbf{H}w \end{aligned} \label{eq:dynamics} \end{equation}\]

that represent the dynamics of evolution of currents in toroidal conductors (control coils, passive structure, and plasma) within the tokamak and include the effect of the nonstationary plasma on these dynamics. Here, \(I\) represents the toroidal currents in coils, passive conductors, and the bulk plasma, \(v\) represents coil power supply voltages, \(y\) represents magnetic measurements such as flux, field, or current, and \(w\) represents disturbance inputs which can be used to model the effect of changes in \(\beta_p\), \(l_i\) , or of noise. The matrices \(\mathbf{A} = -(\mathbf{M}^*)^{-1}\mathbf{R}\) and \(\mathbf{B} = (\mathbf{M}^*)^{-1}\mathbf{V}\) are computed from the conductor resistance matrix \(\mathbf{R}\), a plasma-modified mutual inductance matrix \(\mathbf{M}^*\) (see [2]), and a matrix \(\mathbf{V}\) that maps power supply source voltages into voltages applied to control coils. The matrix \(\mathbf{C}\) is given primarily by the Green functions from currents to magnetic diagnostics, and \(\mathbf{D}\) is usually 0.

We refer to the first equation in \(\eqref{eq:dynamics}\) as the "dynamics equation" because it describes how the dynamical system defined by the collection of toroidal conductor and plasma currents evolves. We refer to the second equation in \(\eqref{eq:dynamics}\) as the "output equation" because it defines how the multiple magnetic diagnostics (B-probes, flux loops, coil and vessel Rogowskis, etc) depend on the toroidal currents and input voltages. The most basic and most mature plasma model construction method we use is based on the rigid plasma model approach described in [2]. Alternatives to this approach, including a nonrigid linear model [3] or nonlinear models [4] have also been integrated in this environment. Use of the nonrigid model requires only small variations from use of the rigid model, so we will confine the discussion in this document primarily to rigid plasma model development.

Note

Use of the nonlinear models will not be described here.

TokSys Toolbox File Structure

The TokSys toolbox consists of a large collection of matlab functions organized into separate Linux directories according to similar functionality. There are three types of matlab files used for modeling:

  1. TokSys Matlab functions and models, generically applicable to any tokamak.
  2. Device-specific matlab functions and models, which invoke the TokSys modeling tools.
  3. General Matlab functions, which are invoked by both of the above.

A TokSys installation consists of all three of these function sets plus additional tools for other related modeling and analysis purposes. The directory structure for such an installation is illustrated below.

Figure 1: Illustration of TokSys installation directory structure

The TokSys general modeling functions and generic matlab functions are located under the matlab path in the above figure. Device-specific functions are located under the tokamaks path.

In addition to these two sets of directories, the TokSys toolset sits "on top" of the ITER PCSSP (Plasma Control System Simulation Platform) toolset, whose directories are structured similarly (see below).

Figure 2: Illustration of PCSSP installation directory structure

Codes and models specific to ITER are maintained as part of PCSSP, using the same separation between generally-applicable and device-specific functions and models.

The structure shown in the figures above represent the installation at DIII-D. Most installations will have only one of the device directories under the "tokamaks" branch of Toksys, i.e. corresponding to the device local to where the toolset is installed.

TokSys follows the usual matlab convention for providing on-line documentation to users in the form of function header documentation and Contents.m files. Each subdirectory in TokSys contains a Contents.m file that provides a summary of functions available in that directory. This summary of functions is available at the matlab command line by typing "help" followed by the directory name. Each function or script contains a standard format header, which describes how to use the function. This description is available at the matlab command line by typing "help" followed by the function name.

Note

These tools can serve as the foundation for the construction of your own specialized set of functions for tokamak modeling. Source code for all functions is provided and therefore can be modified locally.

Warning

DO NOT modify the source files in the installed area. Instead, make a copy of the source file in a separate directory, modify it there, then add that directory name to the matlab path in front of the TokSys directories. Matlab executes the first version of a file that it finds in its search path.

TokSys Generic Function Directories

We provide here a list of the subdirectories of the matlab directory shown in Figure 1. These subdirectories are intended to contain matlab scripts and functions that are applicable to any of the tokamak models we support and, in many cases, generally applicable to any tokamak. While this objective has been essentially reached for most sub-directories, there are a few of the functional areas listed below that are still evolving.

3d
Three-dimensional electromagnetic analysis calculations
breakdown
Generic plasma breakdown/rampup calculations
circuit_models
Conductor circuit modeling functions
comm_tbx
Public domain Communications Toolbox (not well-tested)
design
Control design tools
dcontrol
Public domain Digital Control toolbox (not well-tested)
dina
Functions related to DINA plasma simulation code (not maintained)
dmp
Matlab DMP tools
efit
Functions related to EFIT reconstruction code.
GAcomm
GA-developed communication functions (mostly Ultra-Wideband)
GAcontrol
GA-developed control design utility functions.
GAgraphics
GA-developed graphics functions
GAsignal
GA-developed signal processing functions
geom
Tokamak geometry manipulation tools
jfit
Functions related to JFIT Magnetics Fitting Code
mag
Magnetics Calculation Tools
math
Math calculations
mdsplus
MDSplus data extraction and manipulation functions
ntm
NTM control functions
PCS
Generic functions for interaction with PCS. Applicable to any installation of the DIII-D PCS.
plasma_models
Functions for generating plasma (or plasma+device) models.
plresp
(NOT Generic yet)
pubgraphics
Public domain graphics functions.
RWM
Functions for developing or analyzing RWM control (not currently available)
regression
Functions for regression
simserver
Functions for creating simserver simulations (to connect with PCS).
teq
Functions for interacting with Corsica and TEQ. (NOT Generic yet)
tok_models
Functions for generating plasma (or plasma+device) models
toksim
Toksim library and support functions
utilities
Utility functions
validation
Functions for model validation