Table Of Contents

This Page

ASCEM : Akuna Startup, Navigation and Utilities

  1. ASCEM
  2. Tutorials

ASCEM : Akuna Startup, Navigation and Utilities


Akuna is an integrated suite of software tools that enable a user to build, organize, share and analyze subsurface models. Akuna is open-source and platform-independent. It supports a complete workflow for model development and execution. At the center of this customized environment is the Velo software, which is installed on a networked machine and supports user and team collaboration and connectivity to remote servers where the simulator (Amanzi) is executed. The user installs the Akuna software on a local machine, but logs into the client program on the ASCEM server to access data and analysis applications. A request for an account can be made when launching the software (see Figure 1).


Figure 1. Akuna login screen. Account requests can be made by clicking

Request Account. | Akuna is used to set up models and control the execution of the Amanzi simulator. To execute Amanzi, the user will need to have access to a server where both Amanzi and the simulation controller, Agni, are installed. Many users will be using Hopper, a NERSC computer, which will require a user account separate from the user’s Akuna account (see Figure 2). Information for requesting a NERSC account can be found on the Akuna download page.


Figure 2. Schematic of user access to remote resources. The user installs the Akuna Client locally, but requires an account on the Akuna server, as well as a distinct account on a server which has the ASCEM simulator (Amanzi) and ASCEM simulator controller (Agni) already installed. Separate login credentials will be required.

Several screenshots from a Mac operating system (OS) running Akuna are used. Depending on the OS used, the look and feel of the java interface may differ from what is presented in this tutorial.


This tutorial provides an overview on how to navigate within Akuna and access utilities and toolsets. This tutorial only provides an overview of capabilities, and does not provide specific instructions for performing model setup and simulation execution. It is recommended that the user read this tutorial in its entirety before proceeding to subsequent tutorials, as it provides useful background information. The user can access existing files located in the shared directory (projects) on the Akuna server, if needed for reference.

Functions in Akuna Exercised

In this first tutorial of the series, guidance is provided on the functions:

  1. Create and organize projects and folders
  2. Access toolsets such as single runs (SR), sensitivity analyses (SA), parameter estimation (PE) and uncertainty quantification (UQ).
  3. Utilize tools for job launching and file viewing.
  4. Increase logging level.
  5. Perform software updates.


The user is expected to have installed Akuna on a local machine, and have obtained an account to access the ASCEM server.

Akuna Startup and Navigation

Getting Started

When Akuna is started, the user will see Akuna’s startup screen (Figure 3). This  window is divided into six separate panels: Home, Tutorials, My Workspace, Search, Users and Teams. The Home panel provides access to features that will help you get started using the ASCEM toolsets (Figure 3). In general, the green arrows provide hyperlinks to different perspectives within Akuna. However, clicking on the Report a Problem link will not result in a new perspective, but will provide an email link for reporting issues with the software (email to


Figure 3.  Home Screen.

Direct access to Akuna’s tutorials is provided on the Home screen.  Tutorials can also be accessed by clicking on the Tutorials tab at the top of the window.  Tutorials provide guidance on Navigation, Model setup and the four simulation toolsets (SR, SA, PE and UQ) (Figure 4).


Figure 4.  Tutorial Panel.

Clicking on Browse My Projects or My Workspace at the top of the window, will display the directory tree structure for both shared and private user workspaces (Figure 5). The tutorial folder is located in the shared projects directory, which contain the completed simulations described in this tutorial. This directory is read-only, but the contents of this folder can be copied to another location. Located above the directory structure window are icons and menu items that are used to create items in the directory structure. The right half of the main window provides summary information for the item currently highlighted in the directory structure on My Workspace. An item can be a folder, a conceptual model or a toolset, as demonstrated later in this tutorial.  Search, Users and Teams are shown in other panels respectively.


Figure 5.  My Workspace perspective.

Creating/Editing a Conceptual Model

To get started, a user must first create a conceptual model. It is recommended that a folder is first created to store the model;

  1. Highlight the top-level directory where the model is to be created. This may be in the shared projects directory, or within the users private home image13 directory.
  2. Create a new folder in the workspace by clicking the folder icon image14 located just below the My Workspace labeled tab. Or right-click in the workspace then choose New Folder.
  3. Specify a directory name in the pop-up window to create a new directory. Note that it may be necessary to click on the refresh icon image15 to make the new folder visible in the directory tree.

To create a conceptual model in the folder;

  1. Highlight the new folder just created.
  2. Click the image16 icon for creating a new conceptual model. Or right-click in the workspace then choose New Model.
  3. Enter a name for the new conceptual model in the pop-up window.
  4. Clicking the OK button in this window will launch the Model Setup window.

Alternatively, to edit an existing conceptual model;

  1. Double click on the conceptual model icon image17 . This action opens the Model Setup window and the user may edit any of the conceptual model’s parameter

For instructions on continuing the model setup process, the user is referred to the Model Setup tutorial.

Creating/Editing a Toolset

After a conceptual model is created, the user can proceed to use different toolsets. To start a toolset;

  1. Highlight the conceptual model icon image18 .
  2. Click one of the toolset icons (SR, PE, SA or UQ) located just below the My Workspace labeled tab. Or right-click the conceptual model icon |image19| then select New SR, New SA, New PE or New UQ.
  3. Specify a toolset name in the pop-up window. Note that it may be necessary to click on the refresh icon image20 to make the new toolset in the directory tree.

For specific instructions on setting up the different toolsets, the user is referred to the SR (single-run), SA (sensitivity analysis),  PE (parameter estimation) and UQ (uncertainty quantification) tutorials.

Job Monitoring

Once a simulation (or set of simulations) is launched, Akuna will monitor the job(s) on the remote server. Status information is provided in the Summary tab in the bottom right panel, as well as in the data browser in My Workspace. The following operations are supported;

  1. When a job has been submitted, but not yet launched, its status appears as In Queue. In My Workspace, it appears in brackets image21 next to the name of the simulation in the data browser. In the Summary tab, it appears as shown in Figure 6.
  2. When a job is still in process, it is statused as Running, in both the Summary tab and My Workspace, in the same manner as described for In Queue.
  3. As simulations complete, the Summary tab will status the number of runs that are still running, have completed or failed. In the My Workspace pane, the runs are statused with a text tag (e.g., Success, Running, Killed, Faild) next to the run directory (Figures 7 and 8). Note that the user needs to navigate to the Outputs directory located within the directory from where the runs were launched.
Figure 6. In Queue Job Status in Summary tab.


Figure 7.  Run status in My Workspace.


Figure 8. Run status in Summary tab.

  1. If a user executes a simulation (or set of simulations), then modifies the conceptual model, then simulations that were executed are not in sync with conceptual model. The simulations will then status this inconsistency as a Model Conflict in the My Workspace Pane ( image25 ).
  2. Once a simulation is launched, the user may wish to terminate it before it launches, or during simulation. This can be accomplished by clicking on the Terminate button in the Summary tab (see Figure 8), or by clicking on the Terminate image26 button on the upper right of the My Workspace panel. Should a user terminate a simulation, or if the simulation is killed remotely because of insufficient time, then this status is shown with a killed text tag next to the simulation run ( image27 ).
  3. If a user closes Akuna after launching a simulation, or somehow gets disconnected from the remote server that is running the Amanzi simulator, the user can re-establish the connection by clicking on the Reconnect image28 button, located to the left of the Terminate image29 button. The user may be required to enter the user name and password for the remote computer. The disconnect from within Akuna does not impact the status of the job running remotely. Only the monitoring of the job is interrupted, and the status of the run and the transfer of output files from the remote server to the Akuna server will not occur until the user reconnects to the remote server.

Window Behavior

Windows within Akuna can be adjusted for size, moved to another location or removed from view, depending on the user’s preference. The following options are some of the ways that windows can be arranged:

  1. Tab-dock windows. For example, drag the My Workspace window to the Summary window and release.
  2. Float a released window over or outside Akuna. For example, drag the My Workspace window from its original location and release in a non-tab location.
  3. Hide windows by clicking the image30 in the window tab.
  4. Display windows on different monitors.

Reset window placement to the default layout by selecting Reset Perspective from the Akuna Windows menu. Other windows, such as within Model Setup and Akuna’s plotting tool, can also be re-docked and re-sized.

Viewing and Comparing Text Files

Based on inputs to Model Setup, Akuna generates an Amanzi input file, which gets uploaded to the remote server for execution. This file, as well as any other input or output files, can be viewed within Akuna. To demonstrate the use of the Akuna viewer and comparison tools, a brief description of the file structure within a simulation (or set of simulations) is provided (see Figure 9);

Inputs folder. This folder contains the Amanzi input file (amanzi.xml), the Agni (the simulation controller) input file (agni.xml), as well as any other files used to generate parameter ensembles (design.des, design.xml). Agni generates unique Amanzi input files using the design files on the remote machine where Amanzi is executed. If any additional input files are used in the simulation (e.g., an external geology file or measured data), then this file is also stored in the Inputs directory.

Outputs folder. Upon successful completion of a simulation, this folder contains the screen echo from Amanzi (sim.out), the generated input file from Agni (amanzi.xml), and the observation data output file (amanzi.out) from Amanzi. The amanzi.out file contains point data over time. By default, files containing spatial output are left on the remote server because they can be large.

Analysis folder. Using the amanzi.out files, Akuna’s plotting tool can be used to plot data from multiple simulation runs. If a sensitivity analysis is executed successfully, then data used to generate the sensitivity plots are stored in the Analysis folder.

Imported folder. If an existing Amanzi input file is read into Akuna, then the imported file is stored in this directory.

Akuna provides a file viewer, but editing files within Akuna is not permitted. To view files, the following operations are required;

  1. Navigate to the location of the file within the directory structure.
  2. Click on the file to highlight.
  3. The file contents will appear in the Preview Pane at the bottom left of the Akuna startup window (Figure 9).

Figure 9. Preview pane.

Akuna also provides a utility for comparing two different files. This is useful for identifying differences between individual simulation runs. To compare two different text files, the following operations are required;

  1. From the File Menu at top, select Window - Open View - Scratch Pad.  This will launch the Scratch Pad viewer, which will be placed in the upper right hand corner of the Akuna window.
  2. Navigate to the location of the files within the directory structure. Drag the files to the Scratch Pad (Figure 10).
  3. Highlight both files; control-click in Windows, command-click in Mac. Once both files are highlighted, right click and choose Compare with Each Other. The files will appear side-by-side in the Preview Pane. Differences in the files will be highlighted (Figure 11).


Figure 10. Scratch Pad.


Figure 11. File Comparison Utility.

Automatic Updating

Akuna has an automatic update feature that will notify the user of updates after logging in. If software updates exist, a message will appear in the lower right corner of the Akuna startup screen. To update, the user must click on the notification box, and accept the license agreement to install. Although the user is asked to restart or continue working, it is strongly recommended to restart Akuna once installation is complete. It is also recommended to install software updates as they become available.

Error Reporting

If an error occurs while working in Akuna, an exception will be thrown and a pop-up window indicating its occurrence will appear as shown in Figure 12. If the user clicks on the Send Report button, then an email dialog will appear with a copy of the error message. The user can then edit the email before sending, if desired, to provide more information as to what caused the error to occur.

Figure 12. Exception/error indicator. Pressing Send Report will

allow the user to send a copy of the error message via email to the Akuna development team.

Recording Events for Debugging

By default, Akuna only records critical events and error events to a log file located in the user’s home directory. This information can be useful for if error messaging within Akuna is not sufficient. If insufficient information is recorded at the default level, then it may be necessary to increase the verbosity level of logged messages to help diagnose and resolve possible problems. To increase the verbosity level, the Toggle Logging image35 button is provided, and is located at the top of My Workspace.