diff --git a/doc/component_guides/component_guides.rst b/doc/component_guides/component_guides.rst deleted file mode 100644 index 2fb5e5a9..00000000 --- a/doc/component_guides/component_guides.rst +++ /dev/null @@ -1,39 +0,0 @@ -Component Guides -================ - -This directory contains documentation for the use and development of the various components. - -To component documentation writers: - Documentation should include - - * Information on how to use components in the IPS - - * config file settings - * other component inputs - * component outputs - * point(s) of contact - * location of relevant files - * settings and modes of execution - * execution characteristics or limitations - * (brief) description of the role it plays in a coupled simulation - - * Pointers - - * underlying application documentation - * other relevant information - -List of Components: - - * Monitor Component - (location of documentation) (brief description) - * Portal Bridge Component - (location of documentation) (brief description) - * Runspace Init Component - (location of documentation) (brief description) - * FTB Bridge Component - (location of documentation) (brief description) - * AORSA - (location of documentation) (brief description) - * TSC - (location of documentation) (brief description) - * NUBEAM - (location of documentation) (brief description) - * GENRAY - (location of documentation) (brief description) - - -.. toctree:: - :hidden: - diff --git a/doc/getting_started/getting_started_new.rst b/doc/getting_started/getting_started_new.rst deleted file mode 100644 index 03e83802..00000000 --- a/doc/getting_started/getting_started_new.rst +++ /dev/null @@ -1,340 +0,0 @@ -Getting Started with the Simyan Branch -====================================== - -This document will guide you through the process of running an IPS -simulation and describe the overall structure of the IPS. It is -designed to help you build and run your first IPS simulation. It will -serve as a tutorial on how to get, build, and run your first IPS -simulation, but not serve as a general reference for constructing and -running IPS simulations. See the :doc:`Basic User -Guides<../user_guides/user_guides>` for a handy reference on running and -constructing simulations in general, and for more in-depth explanations -of how and why the IPS works. - -^^^^^^^^^^^^^^^^^^^ -Dependencies -^^^^^^^^^^^^^^^^^^^ - -**IPS Proper** - -The valtools repo will build the entire dependency tree for IPS, -related repos, and the dependencies using Bilder_. See the main -documentation for the dependencies. - -For more inf - -**Portal** - -The portal is a web interface for monitoring IPS runs and requires only -a connection to the internet and a web browser. Advanced features on -the portal require an OpenID account backed by ORNL's XCAMS. -Information on getting an XCAMS backed OpenID can be found on the SWIM -website. There are also visualization utilities that can be accessed -that require Elvis_ or PCMF (see below). - -:::::::::::::::: -Other Utilities -:::::::::::::::: - -**PCMF** - This utility generates plots from monitor component files for visual analysis of runs. It can be run locally on your machine and generates plots like this one of the thermal profiles of an ITER run: - - Requires: Matplotlib_ (which requires `Numpy/Scipy`_) - - - .. image:: thermal_profiles.png - :alt: thermal profiles of an ITER run - -**Resource Usage Simulator (RUS)** - This is a utility for simulation the execution of tasks in the IPS - for research purposes. - - Requires: Matplotlib_ (which requires `Numpy/Scipy`_) - -**Documentation** - The documentation you are reading now was created by a Python-based - tool called Sphinx. - - Requires: Sphinx_ (which requires docutils_) - - -***Plus*** anything that the components or underlying codes that you are using need (e.g., MPI, math libraries, compilers). For the example in this tutorial, all packages that are needed are already available on the target machines and the shell configuration script sets up your environment to use them. - -.. _Sphinx: http://sphinx.pocoo.org/ -.. _Matplotlib: http://matplotlib.sourceforge.net/ -.. _Numpy/Scipy: http://numpy.scipy.org/ -.. _Elvis: http://w3.pppl.gov/elvis/ -.. _docutils: http://docutils.sourceforge.net/ -.. _ConfigObj: http://www.voidspace.org.uk/python/configobj.html -.. _Python: http://python.org/ -.. _processing: http://pypi.python.org/pypi/processing -.. _multiprocessing: http://docs.python.org/library/multiprocessing.html -.. _Bilder: https://ice.txcorp.com/trac/bilder - -===================================================== -Building and Setting up Your Environment Using Bilder -===================================================== - -The IPS code is currently located in the SWIM project's Subversion (SVN) -repository. In this documentation, we will discuss using it from the -Tech-X repos to discuss the new repos. IPS is currently part of the -Simyan repo which is svn:external'd from the ValtoolsAll repo. The -valtoolsall repo is for enabling a simplified environment for python -packages. To check out the valtoolsall repo:: - - svn co https://ice.txcorp.com/svnrepos/code/valtoolsall/trunk valtoolsall - -Using bilder and the valtoolsall project:: - - cd valtoolsall - ./mkvaltoolsall-default.sh -n - -After running bilder, the output file will tell you where things are -installed () and where things are built (). To -configure your environment, you need to source the configuration files. -For bash users:: - - source /valtoolsall.sh - -For tcsh users:: - - source /valtoolsall.csh - -To test the builds:: - - cd /simyan/ser - make test - -This will run all of the tests. The documentation, assuming the `-D` -flag was passed to bilder, will be in the webdocs build directory -(`/simyan/webdocs`). - - -=========================================================== -Building and Setting up Your Environment direct from repo -=========================================================== - -Assuming you have the dependencies installed, you can jst check out the -repo and configure directly. To obtain the rep:: - - https://ice.txcorp.com/svnrepos/code/simyan/trunk ips - -#. Assuming your dependencies are installed in /usr/local or /contrib, - you can configure the file in a build subdirectory - -:: - - mkdir build - cd build - cmake \ - -DCMAKE_INSTALL_PREFIX:PATH=$INSTALL_DIR/simyan \ - -DCMAKE_BUILD_TYPE:STRING=RELEASE \ - -DCMAKE_VERBOSE_MAKEFILE:BOOL=TRUE \ - -DCMAKE_INSTALL_ALWAYS:BOOL=TRUE \ - -DSUPRA_SEARCH_PATH='/usr/local;/contrb' \ - -DENABLE_WEBDOCS:BOOL=ON \ - -DMPIRUN:STRING=aprun \ - -DNODE_DETECTION:STRING=manual \ - -DCORES_PER_NODE:INTEGER=4 \ - -DSOCKETS_PER_NODE:INTEGER=2 \ - -DNODE_ALLOCATION_MODE:SHARED=shared \ - $PWD/.. - -# After configuring, to build IPS, the documentation, and run the tests -respectively - -:: - - make - make docs - make test - make install - -The documentation may be found at docs/html/index.html. The -tests are located in the tests subdirectory. - -Now you are ready to set up your configuration files, and run simulations. - - -=================================== -Running Your First IPS Simulations -=================================== - -This section will take you step-by-step through running a "hello world" example -and a "model physics" example. These examples contain all of the -configuration, batch script, component, executables and input files needed to -run them. To run IPS simulations in general, these will need to be borrowed, -modified or created. See the :doc:`Basic User -Guides<../user_guides/user_guides>` for more information. - -Before getting started, you will want to make sure you have a copy of the ips checked out and built on either Franklin or Stix. - - On **Franklin** you will want to work in your ``$SCRATCH`` directory and move to having the output from more important runs placed in the ``/project/projectdirs/m876/*`` directory. - - On **Stix** you will want to work in a directory within ``/p/swim1/`` that you own. You can keep important runs there or in ``/p/swim1/data/``. - -^^^^^^^^^^^^^^^^^^^^ -Hello World Example -^^^^^^^^^^^^^^^^^^^^ - -This example simply uses the IPS to print "Hello World," using a single driver -component and worker component. The driver component (hello_driver.py) invokes -the worker component (hello_worker.py) that then prints a message. The -implementations of these components reside in -``ips/components/drivers/hello/``, if you would like to examine them. In this -example, the *call()* and *launch_task()* interfaces are demonstrated. In this -tutorial, we are focusing on running simulations and will cover the internals -of components and constructing simulation scenarios in the various User Guides -(see :doc:`Index<../index>`). - -1. Copy the following files to your working directory: - - * Configuration file:: - - /ips/doc/examples/hello_world.config - - * Batch script:: - - /ips/doc/examples//sample_batchscript. - -2. Edit the configuration file: - - * Set the location of your web-enabled directory for the portal to watch and for you to access your data via the portal. If you do not have a web-enabled directory, you will have to create one using the following convention: on Franklin: ``/project/projectdirs/m876/www/``; on Stix: ``/p/swim/w3_html/``. - - Franklin:: - - USER_W3_DIR = /project/projectdirs/m876/www/ - USER_W3_BASEURL = http://portal.nersc.gov/project/m876/ - - Stix:: - - USER_W3_DIR = /p/swim/w3_html/ - USER_W3_BASEURL = http://w2.pppl.gov/swim/ - - This step allows the framework to talk to the portal, and for the portal to access the data generated by this run. - - * Edit the *IPS_ROOT* to be the absolute path to the IPS checkout that you built. This tells the framework where the IPS scripts are:: - - IPS_ROOT = /path/to/ips - - - * Edit the *SIM_ROOT* to be the absolute path to the output tree that will be generated by this simulation. Within that tree, there will be work directories for each of the components to execute for each time step, along with other logging files. For this example you will likely want to place the *SIM_ROOT* as the directory where you are launching your simulations from, and name it using the *SIM_NAME*:: - - SIM_ROOT = /current/path/${SIM_NAME} - - * Edit the *USER* entry that is used by the portal, identifying you as the owner of the run:: - - USER = - - -3. Edit the batch script such that *IPS_ROOT* is set to the location of your IPS checkout:: - - IPS_ROOT=/path/to/ips - -4. Launch batch script:: - - head_node: ~ > qsub hello_batchscript. - - -Once your job is running, you can monitor is on the portal_. - -.. image:: swim_portal.png - :alt: Screen shot of SWIM Portal - -When the simulation has finished, the output file should contain:: - - Starting IPS - Created - Created - HelloDriver: beginning step call - Hello from HelloWorker - HelloDriver: finished worker call - -^^^^^^^^^^^^^^^^^^^^^^ -Model Physics Example -^^^^^^^^^^^^^^^^^^^^^^ - -This simulation is intended to look almost like a real simulation, short of requiring actual physics codes and input data. Instead typical simulation-like data is generated from simple analytic (physics-less) models for most of the plasma state quantities that are followed by the *monitor* component. This "model" simulation includes time stepping, time varying scalars and profiles, and checkpoint/restart. - -The following components are used in this simulation: - - * ``minimal_state_init.py`` : simulation initialization for this model case - * ``generic_driver.py`` : general driver for many different simulations - * ``model_epa_ps_file_init.py`` : model equilibrium and profile advance component that feeds back data from a file in lieu of computation - * ``model_RF_IC_2_mcmd.py`` : model ion cyclotron heating - * ``model_NB_2_mcmd.py`` : model neutral beam heating - * ``model_FUS_2_mcmd.py`` : model fusion heating and reaction products - * ``monitor_comp.py`` : real monitor component used by many simulations that helps with processing of data and visualizations that are produced after a run - -First, we will run the simulation from time 0 to 20 with checkpointing turned on, and then restart it from a checkpoint taken at time 12. - -1. Copy the following files to your working directory: - - * Configuration files:: - - /ips/doc/examples/seq_model_sim.config - /ips/doc/examples/restart_12_sec.config - - * Batch scripts:: - - /ips/doc/examples/model_sim_bs. - /ips/doc/examples/restart_bs. - -2. Edit the configuration files (you will need to do this in BOTH files, unless otherwise noted): - - * Set the location of your web-enabled directory for the portal to watch and for you to access your data via the portal. - - Franklin:: - - USER_W3_DIR = /project/projectdirs/m876/www/ - USER_W3_BASEURL = http://portal.nersc.gov/project/m876/ - - Stix:: - - USER_W3_DIR = /p/swim/w3_html/ - USER_W3_BASEURL = http://w2.pppl.gov/swim/ - - This step allows the framework to talk to the portal, and for the portal to access the data generated by this run. - - * Edit the *IPS_ROOT* to be the absolute path to the IPS checkout that you built. This tells the framework where the IPS scripts are:: - - IPS_ROOT = /path/to/ips - - - * Edit the *SIM_ROOT* to be the absolute path to the output tree that will be generated by this simulation. Within that tree, there will be work directories for each of the components to execute for each time step, along with other logging files. For this example you will likely want to place the *SIM_ROOT* as the directory where you are launching your simulations from, and name it using the *SIM_NAME*:: - - SIM_ROOT = /current/path/${SIM_NAME} - - * Edit the *RESTART_ROOT* in ``restart_12_sec.config`` to be the *SIM_ROOT* of ``seq_model_sim.config``. - - * Edit the *USER* entry that is used by the portal, identifying you as the owner of the run:: - - USER = - - -3. Edit the batch script such that *IPS_ROOT* is set to the location of your IPS checkout:: - - IPS_ROOT=/path/to/ips - -4. Launch batch script for the original simulation:: - - head_node: ~ > qsub model_sim_bs. - - -Once your job is running, you can monitor is on the portal_ and it should look like this: - -.. image:: swim_portal_orig.png - :alt: Screenshot of model run - -When the simulation has finished, you can run the restart version to restart the simulation from time 12:: - - head_node: ~ > qsub restart_bs. - -The job on the portal should look like this when it is done: - -.. image:: swim_portal_restart.png - :alt: Screenshot of restart run - - -.. _Franklin: http://www.nersc.gov/users/computational-systems/franklin/ -.. _portal: http://swim.gat.com:8080/display/ diff --git a/doc/getting_started/thermal_profiles.png b/doc/getting_started/thermal_profiles.png deleted file mode 100644 index fb5f9b87..00000000 Binary files a/doc/getting_started/thermal_profiles.png and /dev/null differ diff --git a/doc/index.rst b/doc/index.rst index 6bfe357f..31305e6e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,10 +13,7 @@ Contents: intro getting_started/getting_started - getting_started/getting_started_new user_guides/user_guides - component_guides/component_guides - the_code Indexes and tables diff --git a/doc/user_guides/advanced_guide_new.rst b/doc/user_guides/advanced_guide_new.rst deleted file mode 100644 index a75f30b0..00000000 --- a/doc/user_guides/advanced_guide_new.rst +++ /dev/null @@ -1,85 +0,0 @@ -Developing Drivers and Components for IPS Simulations -===================================================== - -This section is for those who wish to modify and write drivers and components to construct a new simulation scenario. It is expected that readers are familiar with IPS terminology, the directory structure and have looked at some existing drivers and components before attempting to modify or create new ones. This guide will describe the elements of a simulation, how they work together, the structure of drivers and components, IPS services API, and a discussion of control flow, data flow and fault management. - --------------------------- -Elements of a Simulation --------------------------- - -When constructing a new simulation scenario, writing a new component or even making small modifications to existing components and drivers, it is important to consider and understand how the pieces of an IPS simulation work together. An IPS simulation scenario is specified in the *configuration file*. This file tells the framework how to set up the output tree for the data files, which components are needed and where the implementation is located, time loop and checkpoint parameters, and input and output files for each component and the simulation as a whole are specified. The *framework* uses this information to find the pieces of code and data that come together to form the simulation, as well as provide this information to the components and driver to manage the simulation and execution of tasks. - -The framework provides *services* that are used by components to perform data, task, resource and configuration management, and provides an event service for exchanging messages with internal and external entities. While these services are provided as a single API to component writers, the documentation (and underlying implementation) divides them into groups of methods to perform related actions. *Data management* services include staging input, output and plasma state files, changing directories, and saving task restart files, among others. The framework will perform these actions for the calling component based on the files specified in the configuration file and within the method call maintaining coherent directory spaces for each component's work, previous steps, checkpoints and globally accessible data to insure that name collisions do not corrupt data and that global files are accessed in a well-defined manner. - -Services for *task management* include methods for component method invocations, or *calls*, and executable launch on compute nodes, or *task launches*. The task management portion of the framework works in conjunction with the IPS resource manager to execute multiple parallel executables within a single batch allocation, allowing IPS simulations to efficiently utilize compute resources, as data dependencies allow. The IPS task manager provides blocking and non-blocking versions of ``call`` and ``launch_task``, including a notion of *task pools* and the ability to wait for the completion of any or all calls or tasks in a group. These different invocation and launch methods allow a component writer to manage the control flow and implement data dependencies between components and tasks. - -This task management interface hides the resource management, platform specific, task scheduling, and process interactions that are performed by the framework, allowing component writers to express their simulations and component coupling more simply. The *configuration manager* primarily reads the configuration file and instantiates the components for the simulation so that they can interact over the course of the simulation. It also provides an interface for accessing key data elements from the configuration file, such as the time loop, handles to components and any component specific items listed in the configuration file. - ------------------ -Workflow Concepts ------------------ - -The following sections provide descriptions for how to use IPS to manage complex workflows and multiple runs. - -^^^^^^^^^^^^^^^^^^^^^^ -Creating New Runspaces -^^^^^^^^^^^^^^^^^^^^^^ - -Creating new runspaces from a simulation configuration file is simple by invoking the following from the command line: - - ``ips.py --create-runspace --simulation=simulation_conf.ips`` - -This will create a new directory using the simulation contained in the ``SIM_NAME`` variable. Within this directory, a subdirectory named ``work`` will be created that will house the working directories for all of the components used in the simulation. In addition, a directory named ``simulation_setup`` will be created that houses the component scripts for the simulation. - -All configuration files, the ``platform.conf`` and ``simulation_conf.ips`` files, will be copied into the simulation base directory. Additionally, any data files that are needed by the simulation's components will be staged into the working directories for their respective components. - -^^^^^^^^^ -Run-setup -^^^^^^^^^ - -After a runspace has been created, additional tasks may need to be performed in the parsing of input files, interpolating of data, or trasforming of datapoints between coordinate spaces. These steps may be time or computation intensive, and consist of all of the data preparation that is necessary before a run can begin. As such, these steps should be relegated to a run-setup stage of a workflow. - -Run-setup steps that need to be performed should be contained in the ``init()`` implementation of simulation driver component. To perform only the run-setup step, invoke the following on the command line: - - ``ips.py --run-setup --simulation=simulation_conf.ips`` - -This will invoke only the ``driver.init()`` method, which will perform only run-setup related tasks. - -^^^^^^^ -Running -^^^^^^^ - -Once run-setup has been completed, a run can be performed by invoking the following on the command line: - - ``ips.py --run --simulation=simulation_conf.ips`` - -This will invoke the ``step()`` and ``finalize()`` methods on the driver component, which will execute the run. - -^^^^^^^ -Cloning -^^^^^^^ - -All of the inputs necessary to duplicate a run are stored in a container file named with the ``SIM_NAME`` variable. Given a container file, a clone of a run can be created by invoking the following on the command line: - - ``ips.py --clone=simulation.ctz --sim_name=new_simulation`` - -This creates a new simulation_conf.ips with the name passed in the ``sim_name`` command line option.The Framework will open the container file, copy the ``simulation_conf.ips`` file contained within, replace the ``SIM_NAME`` value in this file with the passed in ``sim_name`` value, and unzip the required files into the new directory. - -^^^^^^^^^^^^^ -Multiple Runs -^^^^^^^^^^^^^ - -From a single command line invocation, multiple runs can be performed by utilizing comma-separated values. In the following example: - - ``ips.py --create-runspace --simulation=a.ips,b.ips`` - -Two simulation files, ``a.ips`` and ``b.ips``, are used to create runspaces for two new simulations. - -The Framework can also allow the handling of multiple clones, as in the following example: - - ``ips.py --clone=a.ctz,b.ctz --sim_name=x,y`` - -Two container files ``a.ctz`` and ``b.ctz`` are used to clone two simulations ``a`` and ``b``, and the clones are renamed ``x`` and ``y`` respectively. - - - diff --git a/doc/user_guides/config_file_new.rst b/doc/user_guides/config_file_new.rst deleted file mode 100644 index f298ba9c..00000000 --- a/doc/user_guides/config_file_new.rst +++ /dev/null @@ -1,549 +0,0 @@ -=================================== -The Configuration Files - Explained -=================================== - -This section will detail the different sections and fields of the -configuration file and how they relate to a simulation. The -configuration file is designed to let the user to easily set data items -used by the framework, components, tasks, and the portal from run to -run. There are user specific, platform specific, and component specific -entries that need to be modified or verified before running the IPS in -the given configuration. After a short overview of the syntax of the -package used by the framework to make sense of the configuration file, a -detailed explanation of each line of the configuration file is -presented. - -------------------------------- -Syntax and the ConfigObj module -------------------------------- - -ConfigObj_ is a Python package for reading and writing config files. -The syntax is similar to shell syntax (e.g., use of $ to reference -variables), uses square brackets to create named sections and nested -subsections, comma-separated lists and comments indicated by a "#". - -In the example configuration file below, curly braces (``{}``) are used -to clarify references to variables with underscores (``_``). Any -left-hand side value can be used as a variable after it is defined. -Additionally, any platform configuration value can be referenced as a -variable in the configuration file as well. - -.. _ConfigObj : http://www.voidspace.org.uk/python/configobj.html - - ----------------------------------- -The 3 files in a nutshell ----------------------------------- - -There are 3 types of configuration files: - - 1. `platform.conf` file: This specifies things specific for a platform file. - It changes very rarely and depends on the installation of that - platforms on the installation of that platform. - - 1. `component-*.conf` file: This specifies things specific to a component, or collection of components - - 1. simulation.ips file: This is changes from simulation-to-simulation - and is meant to be editted frequently. - -The files are parsed sequentially, and parameters from the previous -files can be overwritten in the subsequent files. Thus, it can be -important to understand how to locate your platform.conf file and know -the parameters in the file to understand how to override those values. -This is discussed further below. - ---------------------------- -Platform Configuration File ---------------------------- - -The platform configuration file contains platform specific information -that the framework needs. Typically it does not need to be changed for -one user to another or one run to another (except for manual -specification of allocation resources). For *most* of the platforms -above, you will find platform configuration files of the form -``/share/platform.conf`` (or if testing a build directory, -it will be -``/share/platform.conf`` - -:: - - ####################################### - # framework setting for node allocation - ####################################### - # MUST ADHERE TO THE PLATFORM'S CAPABILITIES - # * EXCLUSIVE : only one task per node - # * SHARED : multiple tasks may share a node - # For single node jobs, this can be overridden allowing multiple - # tasks per node. - NODE_ALLOCATION_MODE = EXCLUSIVE # SHARED | EXCLUSIVE - - ####################################### - # LOCATIONS - ####################################### - IPS_ROOT = /scratch/scratchdirs/skruger/software/simyan - PORTAL_URL = http://swim.gat.com:8080/monitor - RUNID_URL = http://swim.gat.com:4040/runid.esp - - ####################################### - # Parallel environment - ####################################### - MPIRUN = aprun - NODE_DETECTION = checkjob - CORES_PER_NODE = 4 - SOCKETS_PER_NODE = 1 - NODE_ALLOCATION_MODE = @NODE_ALLOCATION_MODE@ - - ####################################### - # Provenance - ####################################### - HOST = Franklin - USER = skruger - HOME = /u/global/skruger - SCRATCH = /scratch/scratchdirs/skruger - -**HOST** - name of the platform. Used by the portal. -**MPIRUN** - command to launch parallel applications. Used by the task - manager to launch parallel tasks on compute nodes. If you - would like to launch a task directly without the parallel - launcher (say, on a SMP style machine or workstation), set - this to "eval" -- it tells the task manager to directly launch the task as `` ``. -**\*_ROOT** - locations of data and binaries. Used by the configuration - file and components to run the tasks of the simulation. -**\*_URL** - portal URLs. Used to connect to and communicate with the - portal. -**NODE_DETECTION** - method to use to detect the number of nodes and processes in - the allocation. If the value is "manual," then the manual - allocation description is used. If nothing is specified, all - of the methods are attempted and the first one to succeed will - be used. Note, if the allocation detection fails, the - framework will abort, killing the job. -**CORES_PER_NODE** - number of cores per node [#nochange]_. -**SOCKETS_PER_NODE** - number of sockets per node [#nochange]_. -**NODE_ALLOCATION_MODE** - 'EXCLUSIVE' for one task per node, and 'SHARED' if more than - one task can share a node [#nochange]_. Simulations, - components and tasks can set their node usage allocation - policies in the configuration file and on task launch. - - -.. [#nochange] This value should not change unless the machine is - upgraded to a different architecture or implements different - allocation policies. - -.. [#manual_alloc_ppn] Used in manual allocation detection and will - override any detected ppn value (if smaller than the machine - maximum ppn). - -.. [#manual_alloc_node] Only used if manual allocation is specified, - or if no detection mechanism is specified and none of the other - mechansims work first. It is the *users* responsibility for this - value to make sense. - -.. note : the node allocation and detection values in this file can be overriden by command line options to the ips ``--nodes`` and ``--ppn``. *Both* values must be specified, otherwise the platform configuration values are used. - ----------------------------------- -Components file ----------------------------------- - -The component configuration file contains information on where to -find the location of physics binaries for a given collection of -components. The purpose is to enable flexibility in installing -components in different locations; e.g., either for a different -collection, or for a different set of builds (pathscale versus pgi -for example. They can be found at: -``/share/component-generic.conf`` (or if testing a build directory, -it will be -``/share/component-generic.conf`` -They should be renamed according to the component collection; e.g., -``/share/component-facets.conf``. One can then specify the -component collection at runtime (by default, it will use the generic -one). - -An example component collection will look like this:: - - ####################################### - # CONTAINTER FILE - ####################################### - CONTAINER_FILE_EXT = .ctz - - ####################################### - # LOCATIONS - ####################################### - BIN_PATH = /scratch/scratchdirs/ssfoley/ips/bin - PHYS_BIN_ROOT = /project/projectdirs/m876/bin - DATA_TREE_ROOT = /project/projectdirs/m876/data - -These are not strictly required, but rather are useful convention for -use in the simulation files as discussed below - ------------------------------------ -Simulation file File - Line by Line ------------------------------------ - -User Data Section -~~~~~~~~~~~~~~~~~ - -The following items are specific to the user and should be changed -accordingly. They will help you to identify your runs in the portal -(*USER*), and also store the data from your runs in particular -web-enabled locations for post-processing (*USER_W3_DIR* on the local -machine, *USER_W3_BASEURL* on the portal). All of the items in this -section are optional. - -:: - - USER_W3_DIR = /project/projectdirs/m876/www/ssfoley - USER_W3_BASEURL = http://portal.nersc.gov/project/m876/ssfoley - USER = ssfoley # Optional, if missing the unix username is used - - -Simulation Information Section -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -These items describe this configuration and is used for describing and -locating its output, information for the portal, and location of the -source code of the IPS. - -\*\* Mandatory items: *SIM_ROOT*, *SIM_NAME*, *LOG_FILE*, *RUN_COMMENT* - -*RUN_ID*, *TOKOMAK_ID*, *SHOT_NUMBER* - identifiers for the simulation -that are helpful for SWIM users. They ore often used to form a -hierarchical name for the simulation, identifying related runs. - -*OUTPUT_PREFIX* - used to prevent collisions and overwriting of -different simulations using the same *SIM_ROOT*. - -*SIM_NAME* - used to identify the simulation on the portal, and often to -name the output tree. - -*SIM_ROOT* - location of output tree, which should include the SIM_NAME -(see below). This directory will be created if -it does not exist. If the directory already exists, then data files -will be added, possibly overwriting existing data. - -*LOG_FILE* - name of the log file for this simulation. The framework -log file is specified at the command line. - -*LOG_LEVEL* - sets the logging level for the simulation. If empty, the -framework log level is used, which defaults to *WARNING*. See -:ref:`logging-api` for details on the logging capabilities in the IPS. -Possible values: *DEBUG*, *INFO*, *WARNING*, *ERROR*, *EXCEPTION*, -*CRITICAL*. - - -In the example below, we show how to use non-needed variables (e.g., -RUN_ID) to construct needed variables. Considerable flexibility is -provided to the user. - -:: - - RUN_ID = Model_seq # Identifier for this simulation run - TOKAMAK_ID = ITER - SHOT_NUMBER = 1 # Identifier for specific case for this tokamak - - SIM_NAME = ${RUN_ID}_${TOKAMAK_ID}_${SHOT_NUMBER} - # Simulation root - path of the simulation directory that will be constructed - # by the framework - SIM_ROOT = ${SCRATCH}/${SIM_NAME} # Scratch comes from platform.conf - - OUTPUT_PREFIX = - LOG_FILE = ${RUN_ID}_sim.log - LOG_LEVEL = DEBUG # Default = WARNING - - # Description of the simulation for the portal - SIMULATION_DESCRIPTION = sequential model simulation using generic driver.py - RUN_COMMENT = sequential model simulation using generic driver.py - TAG = sequential_model # for grouping related runs - - -Simulation Mode -~~~~~~~~~~~~~~~ - -This section describes the mode in which to run the simulation. All values are optional. - -*SIMULATION_MODE* - describes whether the simulation is starting from -*init* (*NORMAL*) or restarting from a checkpoint (*RESTART*). The -default is *NORMAL*. For RESTART, a restart time and directory must be -specified. These values are used by the driver to control how the -simulation is initialized. *RESTART_TIME* must coincide with a -checkpoint save time. *RESTART_DIRECTORY* may be $SIM_ROOT if there is -an existing current simulation there, and the new work will be appended, -such that it looks like a seamless simulation. - -:: - - SIMULATION_MODE = NORMAL # NORMAL | RESTART - RESTART_TIME = 12 # time step to restart from - RESTART_ROOT = ${SIM_ROOT} - - -**Parallel Parameters** - - -**TOTAL_PROCS** - number of processes in the allocation [#manual_alloc_node]_. -**NODES** - number of nodes in the allocation [#manual_alloc_node]_. -**PROCS_PER_NODE** - number of processes per node (ppn) for the framework - [#manual_alloc_ppn]_. -**Platform Configuration Override Section** - It is possible for the configuration file to override entries in the platform configuration file. It is rare and users should use caution when overriding these values. See :doc:`Platform Configuration File - Explained` for details on these values. - -**Plasma State Section** - -The locations and names of the plasma state files are specified here, along with the directory where the global plasma state files are located in the simulation tree. It is common to specify groups of plasma state files for use in the component configuration sections. These files should contain all the shared data values for the simulation so that they can be managed by the driver. - -:: - - PLASMA_STATE_WORK_DIR = ${SIM_ROOT}/work/plasma_state - - # Config variables defining simulation specific names for plasma state files - CURRENT_STATE = ${SIM_NAME}_ps.cdf - PRIOR_STATE = ${SIM_NAME}_psp.cdf - NEXT_STATE = ${SIM_NAME}_psn.cdf - CURRENT_EQDSK = ${SIM_NAME}_ps.geq - CURRENT_CQL = ${SIM_NAME}_ps_CQL.dat - CURRENT_DQL = ${SIM_NAME}_ps_DQL.nc - CURRENT_JSDSK = ${SIM_NAME}_ps.jso - - # List of files that constitute the plasma state - PLASMA_STATE_FILES1 = ${CURRENT_STATE} ${PRIOR_STATE} ${NEXT_STATE} ${CURRENT_EQDSK} - PLASMA_STATE_FILES2 = ${CURRENT_CQL} ${CURRENT_DQL} ${CURRENT_JSDSK} - PLASMA_STATE_FILES = ${PLASMA_STATE_FILES1} ${PLASMA_STATE_FILES2} - - -**Ports Section** - -The ports section identifies which ports and their associated -implementations that are to be used for this simulation. The ports -section is defined by ``[PORTS]``. *NAMES* is a list of port names, -where each needs to appear as a subsection (e.g., ``[[DRIVER]]``). Each -port definition section must contain the entry *IMPLEMENTATION* whose -value is the name of a component definition section. These are case -sensitive names and should be named such that someone familiar the -components of this project has an understanding of what is being -modeled. The only mandatory port is *DRIVER*. It should be named -*DRIVER*, but the implementation can be anything, as long as it is -defined. If no *INIT* port is defined, then the framework will produce -a warning to that effect. There may be more port definitions than -listed in *NAMES*. - -:: - - [PORTS] - NAMES = INIT DRIVER MONITOR EPA - - # Required ports - DRIVER and INIT - [[DRIVER]] - IMPLEMENTATION = GENERIC_DRIVER - - [[INIT]] - IMPLEMENTATION = minimal_state_init - - [[MONITOR]] - IMPLEMENTATION = monitor_comp_4 - - # Physics ports - [[EPA]] - IMPLEMENTATION = model_EPA - - -**Component Configuration Section** - -Component definition and configuration is done in this "section." Each -component configuration section is defined as a section (e.g., -``[model_EPA]``). Each entry in the component configuration section -is available to the component at runtime using that name (e.g., -*self.NPROC*), thus these values can be used to create specific -simulation cases using generic components. Variables defined within a -component configuration section are local to that section, but values -may be defined in terms of the simulation values defined above (e.g., -*PLASMA_STATE_FILES*, and *IPS_ROOT*). - -\*\* Mandatory entries: *SCRIPT*, *NAME*, *BIN_PATH*, *INPUT_DIR* - -*CLASS* - commonly this is the port name or the first directory name in -the path to the component implementation in ``ips/components/``. - -*SUB_CLASS* - commonly this is the name of the code or method used to -model this port, or the second directory name in the path to the -component implementation in ``ips/components/``. - -*NAME* - name of the class in the Python script that implements this component. - -*NPROC* - number of processes on which to launch tasks. - -*BIN_PATH* - path to script and any other helper scripts and binaries. This is used by the framework and component to find and execute helper scripts and binaries. - -*BINARY* - the binary to launch as a task. Typically, these binaries are found in the - -*PHYS_BIN* or some subdirectory therein. Otherwise, you can make your own variable and put the directory where the binary is located there. - -*INPUT_DIR* - directory where the input files (listed below) are found. -This is used during initialization to copy the input files to the work -directory of the component. - -*INPUT_FILES* - list of files (relative to *INPUT_DIR*) that need to be -copied to the component work directory on initialization.
 -*OUTPUT_FILES* - list of output files that are produced that need to be -protected and archived on a call to -:py:meth:`services.ServicesProxy.stage_output_files`. - -*PLASMA_STATE_FILES* - list of plasma state files used and modified by -this component. If not present, then the files specified in the -simulation entry *PLASMA_STATE_FILES* is used. - -*RESTART_FILES* - list of files that need to be archived as the -checkpoint of this component. - -*NODE_ALLOCATION_MODE* - sets the default execution mode for tasks in -this component. If the value is *EXCLUSIVE*, then tasks are assigned -whole nodes. If the value is *SHARED*, sub-node allocation is used so -tasks can share nodes thus using the allocation more efficiently. If no -value or entry is present, the simulation value for -*NODE_ALLOCATION_MODE* is used. It is the users responsibility to -understand how node sharing will impact the performance of their tasks. -This can be overridden using the *whole_nodes* and *whole_sockets* -arguments to :py:meth:`services.ServicesProxy.launch_task`. - -Additional values that are specific to the component may be added as -needed, for example certain data values like *PPN*, paths to and names -of other executables used by the component or alternate *NPROC* values -are examples. It is the responsibility of the component writer to make -sure users know what values are required by the component and what the -valid values are for each. - -:: - - [model_EPA] - CLASS = epa - SUB_CLASS = model_epa - NAME = model_EPA - NPROC = 1 - BIN_PATH = ${IPS_ROOT}/bin - INPUT_DIR = ${DATA_TREE_ROOT}/model_epa/ITER/hy040510/t20.0 - INPUT_STATE_FILE = hy040510_002_ps_epa__tsc_4_20.000.cdf - INPUT_EQDSK_FILE = hy040510_002_ps_epa__tsc_4_20.000.geq - INPUT_FILES = model_epa_input.nml ${INPUT_STATE_FILE} ${INPUT_EQDSK_FILE} - OUTPUT_FILES = internal_state_data.nml - PLASMA_STATE_FILES = ${CURRENT_STATE} ${NEXT_STATE} ${CURRENT_EQDSK} - RESTART_FILES = ${INPUT_FILES} internal_state_data.nml - SCRIPT = ${BIN_PATH}/model_epa_ps_file_init.py - - [monitor_comp_4] - CLASS = monitor - SUB_CLASS = - NAME = monitor - NPROC = 1 - W3_DIR = ${USER_W3_DIR} # Note this is user specific - W3_BASEURL = ${USER_W3_BASEURL} # Note this is user specific - TEMPLATE_FILE= basic_time_traces.xml - BIN_PATH = ${IPS_ROOT}/bin - INPUT_DIR = ${IPS_ROOT}/components/monitor/monitor_4 - INPUT_FILES = basic_time_traces.xml - OUTPUT_FILES = monitor_file.nc - PLASMA_STATE_FILES = ${CURRENT_STATE} - RESTART_FILES = ${INPUT_FILES} monitor_restart monitor_file.nc - SCRIPT = ${BIN_PATH}/monitor_comp.py - - -**Checkpoint Section** - -This section describes when checkpoints should be taken by the -simulation. Drivers should be written such that at the end of each step -there is a call to -:py:meth:`services.ServicesProxy.checkpoint_components`. This way the -services use the settings in this section to either take a checkpoint or -not. - -Selectively checkpoint components in *comp_id_list* based on the -configuration section *CHECKPOINT*. If *Force* is ``True``, the -checkpoint will be taken even if the conditions for taking the -checkpoint are not met. If *Protect* is ``True``, then the data from -the checkpoint is protected from clean up. *Force* and *Protect* are -optional and default to ``False``. - -The *CHECKPOINT_MODE* option controls determines if the components -checkpoint methods are invoked. Possible *MODE* options are: - -WALLTIME_REGULAR: - checkpoints are saved upon invocation of the service call - ``checkpoint_components()``, when a time interval greater than, or - equal to, the value of the configuration parameter - WALLTIME_INTERVAL had passed since the last checkpoint. A - checkpoint is assumed to have happened (but not actually stored) - when the simulation starts. Calls to ``checkpoint_components()`` - before WALLTIME_INTERVAL seconds have passed since the last - successful checkpoint result in a NOOP. - -WALLTIME_EXPLICIT: - checkpoints are saved when the simulation wall clock time exceeds - one of the (ordered) list of time values (in seconds) specified in - the variable WALLTIME_VALUES. Let [t_0, t_1, ..., t_n] be the list - of wall clock time values specified in the configuration parameter - WALLTIME_VALUES. Then checkpoint(T) = True if T >= t_j, for some j - in [0,n] and there is no other time T_1, with T > T_1 >= T_j such - that checkpoint(T_1) = True. If the test fails, the call results - in a NOOP. - -PHYSTIME_REGULAR: - checkpoints are saved at regularly spaced - "physics time" intervals, specified in the configuration parameter - PHYSTIME_INTERVAL. Let PHYSTIME_INTERVAL = PTI, and the physics - time stamp argument in the call to checkpoint_components() be - pts_i, with i = 0, 1, 2, ... Then checkpoint(pts_i) = True if - pts_i >= n PTI , for some n in 1, 2, 3, ... and - pts_i - pts_prev >= PTI, where checkpoint(pts_prev) = True and - pts_prev = max (pts_0, pts_1, ..pts_i-1). If the test fails, the - call results in a NOOP. - -PHYSTIME_EXPLICIT: - checkpoints are saved when the physics time - equals or exceeds one of the (ordered) list of physics time values - (in seconds) specified in the variable PHYSTIME_VALUES. Let [pt_0, - pt_1, ..., pt_n] be the list of physics time values specified in - the configuration parameter PHYSTIME_VALUES. Then - checkpoint(pt) = True if pt >= pt_j, for some j in [0,n] and there - is no other physics time pt_k, with pt > pt_k >= pt_j such that - checkpoint(pt_k) = True. If the test fails, the call results in a - NOOP. - -The configuration parameter NUM_CHECKPOINT controls how many -checkpoints to keep on disk. Checkpoints are deleted in a FIFO manner, -based on their creation time. Possible values of NUM_CHECKPOINT are: - - * NUM_CHECKPOINT = n, with n > 0 --> Keep the most recent n checkpoints - * NUM_CHECKPOINT = 0 --> No checkpoints are made/kept (except when *Force* = ``True``) - * NUM_CHECKPOINT < 0 --> Keep ALL checkpoints - -Checkpoints are saved in the directory ``${SIM_ROOT}/restart`` - -:: - - [CHECKPOINT] - MODE = WALLTIME_REGULAR - WALLTIME_INTERVAL = 15 - NUM_CHECKPOINT = 2 - PROTECT_FREQUENCY = 5 - -**Time Loop Section** - -The time loop specifies how time progresses for the simulation in the driver. It is not required by the framework, but may be required by the driver. Most simulations use the time loop section to specify the number and frequency of time steps for the simulation as opposed to hard coding it into the driver. It is a helpful tool to control the runtime of each step and the overall simulation. It can also be helpful when looking at a small portion of time in the simulation for debugging purposes. - -*MODE* - defines the following entries. If mode is *REGULAR* -- *START*, *FINISH* and *NSTEP* are used to generate a list of times of length *NSTEP* starting at *START* and ending at *FINISH*. If mode is *EXPLICIT* -- *VALUES* contains the (whitespace separated) list of times that are are to be modeled. - -:: - - [TIME_LOOP] - MODE = REGULAR - START = 0.0 - FINISH = 20.0 - NSTEP = 5 diff --git a/doc/user_guides/platform.rst b/doc/user_guides/platform.rst index 425abc12..025731fb 100644 --- a/doc/user_guides/platform.rst +++ b/doc/user_guides/platform.rst @@ -365,11 +365,6 @@ The platform configuration file contains platform specific information that the HOST = franklin MPIRUN = aprun - PHYS_BIN_ROOT = /project/projectdirs/m876/phys-bin/phys/ - DATA_TREE_ROOT = /project/projectdirs/m876/data - DATA_ROOT = /project/projectdirs/m876/data/ - PORTAL_URL = http://swim.gat.com:8080/monitor - RUNID_URL = http://swim.gat.com:4040/runid.esp ####################################### # resource detection method @@ -407,12 +402,6 @@ The platform configuration file contains platform specific information that the would like to launch a task directly without the parallel launcher (say, on a SMP style machine or workstation), set this to "eval" -- it tells the task manager to directly launch the task as `` ``. -**\*_ROOT** - locations of data and binaries. Used by the configuration - file and components to run the tasks of the simulation. -**\*_URL** - portal URLs. Used to connect to and communicate with the - portal. **NODE_DETECTION** method to use to detect the number of nodes and processes in the allocation. If the value is "manual," then the manual @@ -474,11 +463,6 @@ In addition to these files, there is ``ips/workstation.conf``, a sample platform HOST = workstation MPIRUN = mpirun # eval - PHYS_BIN_ROOT = /home//phys-bin - DATA_TREE_ROOT = /home//swim_data - DATA_ROOT = /home//swim_data - #PORTAL_URL = http://swim.gat.com:8080/monitor - #RUNID_URL = http://swim.gat.com:4040/runid.esp ####################################### # resource detection method diff --git a/doc/user_guides/user_guides.rst b/doc/user_guides/user_guides.rst index 41d1e041..5c815b32 100644 --- a/doc/user_guides/user_guides.rst +++ b/doc/user_guides/user_guides.rst @@ -13,9 +13,6 @@ This directory has all of the user guides for using the IPS (see the component a :doc:`Introduction to the IPS` A handy reference for constructing and running applications, this document helps users through the process of running a simulation based on existing components. It also includes: terminology, examples, and guidance on how to translate a computational or scientific question into a series of IPS runs. -:doc:`The Configuration Files (simulation, component and platform files) Explained`: - Annotated version of the configuration file with explanations of how and why the values are used in the framework and components. - :doc:`The Configuration File - Explained`: Annotated version of the configuration file with explanations of how and why the values are used in the framework and components. @@ -28,9 +25,6 @@ This directory has all of the user guides for using the IPS (see the component a :doc:`The IPS for Driver and Component Developers`: This guide contains the elements of components and drivers, suggestions on how to construct a simulation, how to add the new component to a simulation and the repository, as well as, an IPS services guide to have handy when writing components and drivers. This guide is for components and drivers based on the *generic driver* model. More sophisticated logic and execution models are covered in the following document. -:doc:`The New IPS for Simulators and Developers`: - This guide contains the elements of a simulation and an introduction to complex workflow management and the use of the Framework for managing multiple runs. - .. **User Guides Table of Contents** .. toctree:: @@ -39,8 +33,6 @@ This directory has all of the user guides for using the IPS (see the component a basic_guide advanced_guide - advanced_guide_new config_file - config_file_new platform