KeplerActors
The kepleractors project under GForge is used for exchanging
Kepler actors among ITM users.
This project and its associated SVN repository have been created related to the GForge project
Keplerworkflows for enhancing traceability
and reproducibility of simulations.
We describe here a complete procedure that is recommended for traceability purpose. The goal is to be able to keep track of how the actor has been generated (Gforge project of the source code, FC2K parameters, ...).
For public releases a unique name shall be assigned to the actor:
All public actors should be generated (and thus appear in Kepler)
with a name which is the concatenation of
actor_base_name + actor_public_version.
actor_base_name: this can be chosen arbitrarily, though we suggest
that it corresponds to project name under Gforge, i.e. the name of the source code's project
under Gforge when there is a one-to-one link between the Gforge project and the actor.
actor_public_version: is the number of public release for this particular actor.
actor_name: concatenation of actor_base_name and actor_public_version
Structure of the actor repository
The actor repository is under SVN under the Gforge project kepleractors .The policy is that people use SVN/trunk for development versions, while official releases should be done under tags.
To check out the repository please do
svn checkout https://gforge6.eufus.eu/svn/kepleractors target_dir
The structure of the actor_repository directory is:
kepleractors/trunk/datastructure_version/IMP/physics_topic/actor_base_name/ \ actor_public_version/IMP: is imp12 .. imp5 or isip. IMPs can add another level fo more detailed classification, e.g. fixed boundary equilibrium, free boundary equilibrium, linear MHD, etc.
It is the responsibility of the actor provider to create the appropriate directories under SVN.
Currently the kepleractors repository has the following subdirectories for the UAL release versions:
- 4.07b - 4.07c - 4.08a - 4.08b - 4.09a
Each UAL release version hosts the following subdirectories for the ITM projects:
- amns - edrg - isip - imp12 - imp3 - imp4 - imp5 - ism
Below these the following physics topics are currently defined:
imp12: - fixed_boundary_equilibrium - free_boundary_equilibrium - linear_MHD - NTM - numerical_tools - RWM - sawtooth
Content of the actor repository
All files are stored at the bottom level of the tree structure. These are:- actor TAR file generated by the extract_actor script (via the put_repository script)
- actor_info.xml file generated by the put_repository script
- FC2K parameter XML file (the FC2K parameters with which the actor has been created, obtained by selecting save in the FC2K menu)
- actor_doc file (PDF or TAR). Any useful and up-to-date documentation file (PDF recommended) should be gathered in a TAR archive with standardised name actor_doc.tar.
The actor_info.xml file is in an XML file gathering the following information (aiming at establishing a bookkeeping link between the actor files and the source code, as stored in Gforge:
- Actor_name (as defined above)
- Gforge project name: name of the source code's project under Gforge
- SVN_rev: revision number of the source code in the SVN repository
- SVN_path: path of the source code in the SVN repository (e.g. tag/v4.0)
- FC2K_version: evaluated on the fly from $FC2K
- datastructure_version: evaluated on the fly from $UAL
- KEPLER_version: in ITM numbering
Procedure to put an actor in the actor repository
This procedure describes how to proceed to update the kepleractor repository according to the above organization.Pre-requisites
- Have a copy of Kepler installed in your environment
- Run the script ITMv1 to specify the working kepler directory (private) and set the environment variables (for FC2K and the UAL )
- Go into a directory in which you have write permission
How to
When you have generated a Kepler actor with FC2K, using the name convention as indicated above (actor_name), you can update the SVN repository :- Prepare any actor_doc file (PDF or TAR)
- Run the script put_repository
put_repository actor_name Gforge_project_name SVN_rev SVN_path
The actions done by the put_repository script are:
- Run the extract_actor script to take out the actor from the private Kepler, and generate an actor TAR file
- Generate the actor_info.xml file, evaluating some information on the fly from environment variables as stated above
- Use the standard SVN commands to move in the relevant place in the SVN kepleractors repository the following files :
- the FC2K parameter file
- the actor.tar file generated by the put_repository script
- the actor_doc.tar file
- the actor_info.xml file generated by the put_repository script
Procedure to get an actor from the actor repository
The script import_actor allows to import an existing actor
directly from the kepleractors SVN repository into your own distribution of Kepler.
The script search the actor repository under the Gforge project kepleractors
(in the trunk and in the tags sections). Its content (actor TAR file, actor_info.xml
file, and actor_doc file if exists) is copied in the current working directory
and the actor extracted from the TAR file is added in the private copy of Kepler.
Pre-requisites
- Have a copy of Kepler installed in your environment
- Run the script ITMv1 to specify the working kepler directory (private) and set the environment variables (for the UAL)
- Go into a directory in which you have write permission
How to import an actor from svn repository
- You do not know the location of the actor in the repository
Usage:
import_actor -R actor_name
Example:
import_actor -R gray
path_to_the_actor_in_the_svn_repository is trunk/4.08b/imp5/electron_physics/gray
actor_name is gray
The script displays the location(s) of the actor in the svn repository (under trunk and tags subdirectories) and the user can choose the item he wants to import
- You know the location of the actor in the repository
Usage:
import_actor -d path_to_the_actor_in_the_svn_repository actor_name
Example:
import_actor -d trunk/4.08b/imp5/electron_physics/gray gray
path_to_the_actor_in_the_svn_repository is trunk/4.08b/imp5/electron_physics/gray
actor_name is gray
How to import an actor from local location
Using the script import_actor, it is also possible
to put into your private copy of Kepler an actor which is not stored in
the SVN kepleractors repository.
In this case, you need an actor TAR file generated by the script
extract_actor. This method is not recommended because
the reproducibility of simulations cannot be ensured.
- Copy into the current directory or locate the tar file that contains the actor.
The file does not have to be in your own directory. Only read permission is needed.
Usage:
import_actor [path]actor_name
Example:import_actor ~/private/ACTORS/gray
path is ~/private/ACTORS
actor_name is gray
path is only necessary if the tar file that contains the actor is not located in the current directory.
last update: 2019-01-31 by g2dpc