How to use tool

These are just examples. The tool is still in development phase. Once we agree that current status is what we are looking for, we will release it.

Publicly available copy of private database can be created using createpublicdb_imas.

> createpublicdb_imas

To get basic help, run the tool following way

> createpublicdb_imas --help

Example usage

Create description file

Create a text file with name description.txt that contains a plain-text description of the database you want to save - it can be arbitrary text, it is supposed to give basic information about your pulse file.

Load environment

> module load imasenv
> module load imas-publicdb/rc


$IMASPUBLICDBHOME points to /gw/swimas/shared/imasdb
$IMASPUBLICDBMETADATA points to /gw/swimas/shared/metadata/

Use dry mode

Run the tool in dry mode first:

# You have to provide basic information related to your pulse file
# createpublicdb_imas -n <USER> <TOKAMAK> <DATAVERSION> <SHOT> <RUN> description.txt

# example - for user g2dfigat - make sure to use your own user name and proper shot/run numbers;
#           version of database is also mandatory

> createpublicdb_imas -n g2dfigat jet 3 12 12 description.txt

This will output the actions that will be taken and the metadata file that will be created on stdout.

In case of error: 
ERROR - Public database not set up for tokamak <TOKAMAK>and data version <DATAVERSION>
ERROR - You have to run
create_public_imas_dir <TOKAMAK> <DATAVERSION>


Please run:
create_public_imas_dir <TOKAMAK> <DATAVERSION>

Run the tool

Once you are ready to run the tool (everything what you have seen in dry-mode  seems to be fine) you can perform actual copy of data.

> createpublicdb_imas g2dfigat jet 3 12 12 description.txt

Check the result

Check the output with imasdbs application

> imasdbs -u public -t jet -v 3


This should now list the shot (in this case 12)

Content of description.txt is stored in $IMASPUBLICDBMETADATA in a file created according to the scheme: <DATAVERSION>_<TOKAMAK>_<SHOT>_<RUN>.
It contains the section: DATABASE DESCRIPTION. The description content is saved there.

Test environment

Please note that for now we are working with artificially created environment - to make sure we don't access public database location yet.


The tool is meant to modify the public database, which carries the risk of corrupting important data.  For testing the tool, or practicing its use, a test environment is foreseen. In this test environment a test copy of the public database is used. Below are instructions how to use the test environment.

Switch to development environment

module purge
module load cineca
module load imasenv
cd /pfs/work/g2dfigat/archiving_scripts/R3-imas
source environment

Check that you have the development database selected:

env | grep PUBLICDB

This should give:

IMASPUBLICDBHOME=/pfs/work/g2dfigat/archiving_scripts/imasdb/public
IMASPUBLICDBMETADATA=/pfs/work/g2dfigat/archiving_scripts/imasdb/meta


IMPORTANT: If you don't check this, you risk overwriting the real public database!

Run the tool

bin/createpublicdb_imas --help

This should give you some basic documentation.

use tool to create entries in the public database

createpublicdb_imas <USER> <TOKAMAK> <DATAVERSION> <SHOT> <RUN> description.txt

Note that in case you are trying to populate non existing database it might be required to create database inside publicly available space.

In case of error: 
ERROR - Public database not set up for tokamak <TOKAMAK>and data version <DATAVERSION>
ERROR - You have to run
create_public_imas_dir <TOKAMAK> <DATAVERSION>


Please run:
./create_public_imas_dir <TOKAMAK> <DATAVERSION>

check the results

Make sure to check that the public database was correctly published in public area

ls -l $IMASPUBLICDBHOME/<TOKAMAK>/3/0/

or

imasdbs -u public -t <TOKAMAK> -v 3

please report any problems you find.