doc/rappels.rst

   1
   2 :tocdepth: 3
   3
   4 .. _rappels:
   5
   6 ================================================================
   7 Reminders about the SALOME platform
   8 ================================================================
   9
  10 Definitions
  11 ================================================================
  12
  13    - **SALOME module**:  a SALOME module is a group of SALOME components. It is located in a directory with a standard structure.
  14      Its components are described in an XML file named <module>Catalog.xml.
  15    - **SALOME component**:  this is the SALOME equivalent of a calculation code.  It may be in the form of a dynamic
  16      library or a Python module.
  17    - **SALOME service**:  each component has one or several services.  A service is the equivalent of a Fortran
  18      subroutine, a C function, a C++ method or a Python method.  Only component services can be coupled with the YACS coupler.
  19      Coupling is done connecting input-output ports with which services are provided.  There are two types of these
  20      ports, dataflow and datastream.
  21    - **Dataflow port**:  a dataflow port is a connection port for exchanging data.  It has a name that is the name of the
  22      exchanged variable, a type that indicates the data type (double, long, string, etc.) and a direction (input or output).
  23      An input dataflow port can be connected with an output dataflow port of a compatible type.  The variable carried by
  24      the port is exchanged at the end of the service (output port) or at the beginning of the service (input port).
  25      No data exchange takes place during execution of the service.
  26    - **Datastream port**:  a datastream port is used to exchange data during execution.  Like a dataflow port, it has a name,
  27      a type and a direction but it also has an iterative (I) or time (T) dependence mode.  An input datastream port can only
  28      be connected with an output datastream port of the same type.  There may be several classes of datastream port.
  29      In this description, we only deal with CALCIUM datastream ports.
  30    - **YACS coupler**:  this is a SALOME module that edits and executes coupling schemes that are mainly in the form of an
  31      XML file.  The module provides a graphic user interface to edit a scheme, to execute it and monitor its execution.
  32    - **Component instance**:  there can be several copies of the same component and they can be executed by SALOME in a
  33      single session.  A distinction between these copies is made by referring to a component instance.  A parallel can be
  34      made with the terms calculation code (component) and execution (component instance).
  35    - **Container**:  SALOME process that executes components.  It loads (dynamic library or Python module) and saves
  36      components.  The choice of containers may be important if it is required that one component should not be in the same
  37      executable as another.
  38    - **SALOME application**:  set of SALOME modules integrated into the SALOME platform.  This platform is built on KERNEL
  39      and GUI basic modules that provide component running and integration services in the graphic user interface.  A SALOME application
  40      provides several scripts to run the application (runAppli), enter the application environment (runSession) and other
  41      more internal scripts such as remote run (runRemote).
  42
  43 SALOME modules and components
  44 ==================================================
  45 In principle, the SALOME platform is broken down into a basic platform (composed of a KERNEL and a GUI modules)
  46 and a collection of various modules.
  47
  48 A module is a compilable and installable product that is materialised by a source tree structure that must respect
  49 SALOME general rules and that includes a construction and installation procedure that also respects SALOME rules.
  50 Each module is managed in configuration in an independent CVS module.  Each module can deliver versions at it own rate
  51 respecting SALOME consistency rules.  A non-regression tests base is associated with each module.
  52
  53 A module has dependencies with other modules (uses, is used). The KERNEL and GUI modules makes up the base of the SALOME platform.
  54 All other modules depend on these modules.
  55
  56 ===================================== ========= ======================= ==================================
  57 Theme                                  Module     Uses                       Is used by
  58 ===================================== ========= ======================= ==================================
  59 Architecture                           KERNEL                            GUI, MED, GEOM, SMESH, PARAVIS,YACS
  60 Architecture                           GUI       KERNEL                  MED, GEOM, SMESH, PARAVIS,YACS
  61 Architecture                           MED       KERNEL, GUI             SMESH, PARAVIS
  62 Geometry                               GEOM      KERNEL, GUI             SMESH
  63 Mesh                                   SMESH     KERNEL, GUI, GEOM, MED
  64 Supervision                            YACS      KERNEL, GUI
  65 Visualization                          PARAVIS   KERNEL, GUI, MED
  66 ===================================== ========= ======================= ==================================
  67
  68 A module contains one or several SALOME components.  A SALOME component is a CORBA object that respects SALOME rules
  69 and that is declared to SALOME using a catalog.  A SALOME component may be provided with a graphic user interface (GUI)
  70 that must itself respect SALOME rules.
  71
  72 Containers
  73 ======================
  74 In SALOME, components are dynamically loaded.  This property is obtained by using a container mechanism.
  75
  76 In general, a container is a CORBA server with an interface that is provided with methods necessary to load
  77 and unload the implementation of a SALOME component.  A component is loaded by calling the container load_impl method.
  78
  79 The basic mechanism for loading a component depends on the chosen implementation language.
  80
  81 In C++, the platform uses dynamic library loading (dlopen) and a factory function mechanism that must be
  82 named <Component>Engine_factory (for example GEOMEngine_factory, for GEOM component type).
  83 This function must return the effective CORBA object that is the SALOME component.
  84
  85 In Python, the platform uses the Python import mechanism (import <Component>) and instantiates the Python SALOME
  86 component using a class (or a factory) with the same name (<Component>).
  87
  88 .. _appli:
  89
  90 Construction and use of a SALOME application
  91 =========================================================
  92 This section explains how to configure, install and use your own SALOME application starting from a list of
  93 pre-installed modules (see more details in the on line documentation for the KERNEL module defining the
  94 application concept).
  95
  96 Principles
  97 ------------
  98 A SALOME application is built up from a list of platform basic modules (GEOM, SMESH, ASTER, etc.) or users.
  99 It consists of a set of shell scripts and directories used to execute the application in different contexts.
 100
 101 A user can define several SALOME applications.  These applications can be used from several user accounts.
 102 They can use the same modules (KERNEL or other).  The SALOME application is independent of KERNEL
 103 and **it must not be installed in KERNEL_ROOT_DIR**.
 104
 105 Prerequisites for each application may be different.
 106
 107 A SALOME session run from a SALOME application can be executed on several computers.
 108
 109 For the installation of a multi-machine application, the modules and prerequisites must be installed on
 110 all machines involved.  There is no need to install all modules on all machines except for KERNEL.
 111 The SALOME user must have an account on each machine.  Remote machines are accessed by rsh or ssh.
 112 These accesses must be configured for use without a password.  The accounts may be different on the different machines.
 113
 114 Creating a SALOME application
 115 ------------------------------
 116 A SALOME application is created using the appli_gen.py tool located in the installation of the KERNEL module.
 117 This tool builds the application starting from a configuration file in the XML format that describes the list
 118 of modules to be used (name, installation path), the file that sets the environment for SALOME pre-requisites
 119 and optionally the SALOME examples directory (SAMPLES_SRC) and a catalog of resources.
 120
 121 The following command is used:
 122
 123 .. code-block:: sh
 124
 125    python <KERNEL_ROOT_DIR>/bin/salome/appli_gen.py --prefix=<install directory> \
 126                                --config=<configuration file>
 127
 128 where <configuration file> is the name of the configuration file and <install directory> is the name of the
 129 directory in which the application is to be created.  <KERNEL_ROOT_DIR> indicates the directory in which
 130 the KERNEL module is installed.
 131
 132 The configuration file can be created by modifying a copy of the ${KERNEL_ROOT_DIR}/bin/salome/config_appli.xml file.
 133
 134 For example:
 135
 136 .. code-block:: xml
 137
 138   <application>
 139   <prerequisites path="/data/SALOME_V5/env_products.sh"/>
 140   <resources path="myCata.xml"/>
 141   <modules>
 142      <!-- variable name <MODULE>_ROOT_DIR is built
 143           with <MODULE> == name attribute value -->
 144      <!-- <MODULE>_ROOT_DIR values is set with path attribute value -->
 145      <!-- attribute gui (defaults = yes) indicates if the module
 146                                           has a gui interface -->
 147      <module name="KERNEL"       gui="no"  path="/data/SALOME_V5/KERNEL_INSTALL"/>
 148      <module name="GUI"          gui="no"  path="/data/SALOME_V5/GUI_5"/>
 149      <module name="MED"                    path="/data/SALOME_V5/MED_5"/>
 150      <module name="GEOM"                   path="/data/SALOME_V5/GEOM_5"/>
 151      <module name="SMESH"                  path="/data/SALOME_V5/SMESH_5"/>
 152      <module name="YACS"                   path="/data/SALOME_V5/YACS_5"/>
 153      <module name="VISU"                   path="/data/SALOME_V5/VISU_5"/>
 154      <module name="HELLO"                  path="/data/SALOME_V5/HELLO1_5"/>
 155      <module name="PYHELLO"                path="/data/SALOME_V5/PYHELLO1_5"/>
 156      <module name="NETGENPLUGIN"           path="/data/SALOME_V5/NETGENPLUGIN_5"/>
 157   </modules>
 158   <samples path="/data/SALOME_V5/SAMPLES/SAMPLES_SRC"/>
 159   </application>
 160
 161 Some rules to be followed
 162 ------------------------------
 163 The application directory must be created on all computers on which components of this application are to be executed.
 164 The simplest method is to create the application directory using the same relative path from the HOME directory on each machine.
 165 If this is not wanted, then different paths can be used on different computers, but these paths will have to be specified
 166 in the CatalogRessources.xml configuration file.
 167
 168 The application directory contains scripts to initialize environment variables and to make executions.
 169
 170 The environment is initialized by scripts placed in the env.d sub-directory.  Scripts for SALOME are created at
 171 the time that the application is created but the user can add his own scripts.  All that is necessary is that
 172 they have the .sh suffix.  These scripts must be installed on all machines used by the application.
 173
 174 The SALOME application provides the user with 3 execution scripts:
 175  - **runAppli** runs a SALOME session (in the same way as ${KERNEL_ROOT_DIR}/bin/Salome/runSalome).
 176  - **runSession** connects to a running SALOME session, in a shell with a conforming environment.  If there is no argument, the
 177    script opens an interactive shell.  If there are arguments, it executes the command supplied in the environment of the SALOME application.
 178  - **runConsole** opens a python console connected to the current SALOME session.  Another option is to use **runSession** and then to run Python.
 179
 180 The application configuration files are:
 181  - **SALOMEApp.xml**:  this file is similar to the default file located in ${GUI_ROOT_DIR}/share/SALOME/resources/gui.
 182    It can be adapted to the user’s needs.
 183  - **CatalogResources.xml**:  this file describes all computers that the application might use.  The initial file only
 184    contains the local machine.  The user must add the machines to be used.  If it is required to use arbitrary
 185    application directories on the different computers, their location must be specified in this file using the appliPath attribute::
 186
 187         appliPath="/my/specific/path/on/this/computer"
 188
 189 Configuring a SALOME application for remote components
 190 ----------------------------------------------------------
 191 If you have a multi-machine application, it is possible that some modules (and components) are only available on remote
 192 computers. In this case, you need to configure your application for this situation by using the **update_catalogs.py** script provided by the
 193 SALOME application.
 194
 195 The first thing to do is to create a file named **CatalogResources.base.xml** that will contain all information about your multi-machine
 196 configuration.
 197
 198 Example of **CatalogResources.base.xml** file:
 199
 200 .. code-block:: xml
 201
 202   <!DOCTYPE ResourcesCatalog>
 203   <resources>
 204      <machine name="res1" hostname="localhost" >
 205         <component name="GEOM_Superv" moduleName="GEOM"/>
 206         <modules moduleName="YACS"/>
 207      </machine>
 208
 209      <machine name="res2" hostname="computer1" userName="user" protocol="ssh" appliPath="/home/user/SALOME514/appli_V5_1_4" >
 210         <modules moduleName="AddComponent"/>
 211      </machine>
 212   </resources>
 213
 214 In this file, we say that we have 2 resources **res1** and **res2** on localhost and computer1. On the remote machine, we give
 215 the SALOME application path and we give, for each resource, the list of available components or modules : GEOM_Superv and YACS on localhost
 216 and AddComponent on computer1.
 217
 218 Starting from this file, the **update_catalogs.py** script gets all remote catalogs, puts them in local directories (remote_catalogs/<resource name>),
 219 builds an updated **CatalogResource.xml** file and adds a new environment variable (**SALOME_CATALOGS_PATH** in env.d/configRemote.sh) to the
 220 SALOME application. With these 3 elements the application is now correctly configured for a multi-machine use.
 221
 222
 223
 224
 225