Changes between Version 1 and Version 2 of WikiStart

Timestamp:

12/02/10 18:03:59 (14 years ago)

Author:

mmatloka

Comment:

readme

WikiStart

@@ -1 @@
-= Welcome to Trac 0.12 =
-
-Trac is a '''minimalistic''' approach to '''web-based''' management of
-'''software projects'''. Its goal is to simplify effective tracking and handling of software issues, enhancements and overall progress.
-
-All aspects of Trac have been designed with the single goal to 
-'''help developers write great software''' while '''staying out of the way'''
-and imposing as little as possible on a team's established process and
-culture.
-
-As all Wiki pages, this page is editable, this means that you can
-modify the contents of this page simply by using your
-web-browser. Simply click on the "Edit this page" link at the bottom
-of the page. WikiFormatting will give you a detailed description of
-available Wiki formatting commands.
-
-"[wiki:TracAdmin trac-admin] ''yourenvdir'' initenv" created
-a new Trac environment, containing a default set of wiki pages and some sample
-data. This newly created environment also contains 
-[wiki:TracGuide documentation] to help you get started with your project.
-
-You can use [wiki:TracAdmin trac-admin] to configure
-[http://trac.edgewall.org/ Trac] to better fit your project, especially in
-regard to ''components'', ''versions'' and ''milestones''. 
-
-
-TracGuide is a good place to start.
-
-Enjoy! [[BR]]
-''The Trac Team''
-
-== Starting Points ==
-
- * TracGuide --  Built-in Documentation
- * [http://trac.edgewall.org/ The Trac project] -- Trac Open Source Project
- * [http://trac.edgewall.org/wiki/TracFaq Trac FAQ] -- Frequently Asked Questions
- * TracSupport --  Trac Support
-
-For a complete list of local wiki pages, see TitleIndex.
+= PSNC DRMAA for SLURM =
+== Introduction ==
+
+PSNC DRMAA for [#slurm Simple Linux Utility for Resource Management (SLURM)] is an implementation of [#open_grid_forum Open Grid Forum] [#drmaa DRMAA 1.0] (Distributed Resource Management Application API) [#specification specification]
+for submission and control of jobs to [#slurm Simple Linux Utility for Resource Management (SLURM)].  Using DRMAA,
+grid applications builders, portal developers and ISVs can use the same
+high-level API to link their software with different cluster/resource
+management systems.
+
+This software also enables the integration of [#smoa_comp SMOA Computing] with the
+underlying SLURM system for remote multi-user job submission and control
+over Web Services.
+
+
+== Installation ==
+
+To compile and install the library just go to main source directory
+and type::
+{{{
+#!sh
+  $ ./configure [options] && make
+  $ sudo make install
+}}}
+The library was tested with Simple Linux Utility for Resource Management version 2.1.13.
+If you encountered any problems using the library on the different systems, please use 
+the contact e-mails for reporting the problem.
+
+Notable `./configure` script options:
+
+  `--with-slurm-inc` SLURM_INCLUDE_PATH
+    Path to SLURM header files (i.e. directory containing `slurm/slurm.h` ). By default the library tries 
+    to guess the `SLURM_INCLUDE_PATH` and `SLURM_LIBRARY_PATH` based on location
+    of the `srun` executable.
+
+  `--with-slurm-lib` SLURM_LIBRARY_PATH
+    Path to SLURM libraries (i.e. directory containing `libslurm.a` ).
+
+  `--prefix` INSTALLATION_DIRECTORY
+    Root directory where PSNC DRMAA for SLURM shall be installed.
+    When not given library is installed in `/usr/local`.
+
+  `--enable-debug`
+    Compiles library with debugging enabled (with debugging symbols not
+    stripped, without optimizations, and with many log messages enabled).
+    Useful when you are to debug DRMAA enabled application
+    or investigate problems with DRMAA library itself.
+
+There are no unusual requirements for basic usage of library: ANSI C
+compiler and standard make program should suffice.  If you have taken
+sources directly from SVN repository or wish to run test-suite you would
+need additional [#dev_tools developer tools].  For further information regarding
+GNU build system see the INSTALL file.
+
+
+== Configuration ==
+
+During DRMAA session initialization (`drmaa_init`) library tries to
+read its configuration parameters from locations: `/etc/slurm_drmaa.conf`,
+`~/.slurm_drmaa.conf` and from file given in `SLURM_DRMAA_CONF` environment
+variable (if set to non-empty string).  If multiple configuration
+sources are present then all configurations are merged with values
+from user-defined files taking precedence (in following order:
+`$SLURM_DRMAA_CONF`, `~/.slurm_drmaa.conf`, `/etc/slurm_drmaa.conf`).
+
+Currently recognized configuration parameters are:
+
+  cache_job_state
+    According to DRMAA specification every `drmaa_job_ps()` call should
+    query DRM system for job state.  With this option one may optimize
+    communication with DRM.  If set to positive integer `drmaa_job_ps()`
+    returns remembered job state without communicating with DRM for
+    `cache_job_state` seconds since last update.  By default library
+    conforms to specification (no caching will be performed).
+
+    Type: integer, default: 0
+
+  job_categories
+    Dictionary of job categories.  It's keys are job categories names
+    mapped to [#native_specification native specification] strings.  Attributes set by job
+    category can be overridden by corresponding DRMAA attributes or
+    native specification.  Special category name `default` is used when
+    `drmaa_job_category` job attribute was not set.
+
+    Type: dictionary with string values, default: empty dictionary
+        
+
+=== Configuration file syntax ===
+
+Configuration file is in form a dictionary.
+Dictionary is set of zero or more key-value pairs.
+Key is a string while value could be a string, an integer
+or another dictionary.
+
+{{{
+  configuration: dictionary | dictionary_body
+  dictionary: '{' dictionary_body '}'
+  dictionary_body: (string ':' value ',')*
+  value: integer | string | dictionary
+  string: unquoted-string | single-quoted-string | double-quoted-string
+  unquoted-string: [^ \t\n\r:,0-9][^ \t\n\r:,]*
+  single-quoted-string: '[^']*'
+  double-quoted-string: "[^"]*"
+  integer: [0-9]+
+}}}
+
+[=#native_specification]
+== Native specification ==
+
+DRMAA interface allows to pass DRM dependent job submission options.
+Those options may be specified directly by setting `drmaa_native_specification` job
+template attribute or indirectly by the `drmaa_job_category` job template attribute. 
+The legal format of the native options looks like::
+{{{
+  -A My_job_name -s -N 1=10
+}}}
+
+||= Native specification =||= Description =||
+||  `-A, --account=`\name   ||      Charge job to specified accounts ||
+||  `--acctg-freq`             ||   Define  the  job accounting sampling interval ||
+||  `--comment`                ||   An arbitrary comment ||
+||  `-C, --constraint=`\list   ||   Specify a list of constraints ||
+||  `--contiguous`             ||   If  set,  then  the  allocated nodes must form a contiguous set ||
+||  `--exclusive`              ||   Allocate nodenumber of tasks to invoke on each nodes in exclusive mode when cpu consumable resource is enabled ||
+||  `--mem=`\MB                ||   Minimum amount of real memory ||
+||  `--mem-per-cpu=`\MB        ||   Maximum mount of real memory per allocated cpu required by a job ||
+||  `--mincpus=`\n             ||   Minimum number of logical processors (threads) per node ||
+||  `-N, --nodes=`\N           ||   Number of nodes on which to run (N = min[-max]) ||
+||  `--ntasks-per-node=`\n     || Number of tasks to invoke on each node  || 
+||  `-p, --partition=`\partition ||  Partition requested ||
+||  `--qos=`\qos               ||   Quality of Serice ||
+||  `--requeue`                ||   If set, permit the job to be requeued ||
+||  `--reservation=`\name      ||   Allocate resources from named reservation ||
+||  `-s, --share`              ||   Job allocation  can  share  nodes with other running jobs ||
+||  `-w, --nodelist=`\hosts    ||   Request a specific list of hosts ||
+
+  
+Description of each parameter can be found in `man sbatch`.
+
+== Release notes ==
+
+ * 1.0.0 - first public release
+
+=== Known bugs and limitations ===
+
+
+Library covers all [#specification DRMAA 1.0 specification] with exceptions listed
+below.  It was successfully tested with [#slurm Simple Linux Utility for Resource Management (SLURM) 2.1.13] on Linux and passes 44/44 tests of the [#testsuite official DRMAA test-suite] (running as SLURM administrator).
+Using regular user account SLURM DRMAA passes 40/44 tests of the official DRMAA test-suite. 
+
+Known limitations:
+
+ * `drmaa_control` options `DRMAA_CONTROL_HOLD`, `DRMAA_CONTROL_SUSPEND`, `DRMAA_CONTROL_RELEASE`, `DRMAA_CONTROL_RESUME` are only available for users being SLURM administrators
+ * `drmaa_wct_slimit` not implemented
+ * optional attributes `drmaa_deadline_time`, `drmaa_duration_hlimit`, `drmaa_duration_slimit`, `drmaa_transfer_files` not implemented
+
+
+=== Authors ===
+
+The library was developed by:
+
+ * Michal Matloka - core implementation
+
+This library relies heavily on the ''Fedstage DRMAA utils'' code developed by:
+
+ * Lukasz Ciesnik.
+
+[=#dev_tools]
+=== Developer tools ===
+
+Although not needed for library user the following tools may be required
+if you intend to develop PSNC DRMAA for SLURM:
+
+ * GNU autotools (autoconf, automake, libtool),
+ * [#bison Bison] parser generator,
+ * [#docutils Docutils] for processing this `README`,
+ * [#latex LaTeX] for creating documentation in PDF format,
+ * [#doxygen Doxygen] for generating source code documentation.
+
+=== Links ===
+
+[=#bison] Bison:     http://www.gnu.org/software/bison/ \\
+[=#docutils] Docutils:  http://docutils.sourceforge.net/ \\
+[=#latex] LaTeX:     http://www.latex-project.org/ \\
+[=#doxygen] Doxygen:   http://www.stack.nl/~dimitri/doxygen/ \\
+[=#drmaa] DRMAA: http://www.drmaa.org/ \\
+[=#open_grid_forum] Open Grid Forum: http://www.gridforum.org/ \\
+[=#specification] DRMAA 1.0 specification: http://www.ogf.org/documents/GFD.133.pdf \\
+[=#testsuite] Official DRMAA test-suite: http://drmaa.org/testsuite.php \\
+[=#smoa_comp] SMOA Computing: http://larix.man.poznan.pl/wiki/SMOA_Computing \\
+[=#slurm] Simple Linux Utility for Resource Management (SLURM): https://computing.llnl.gov/linux/slurm/ \\
+
+
+=== License ===
+
+Copyright (C) 2009-2010  Poznan Supercomputing and Networking Center 
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see http://www.gnu.org/licenses/.