]> SALOME platform Git repositories - modules/yacs.git/blob - doc/rappels.rst
Salome HOME
0022328: [CEA 942] Worrying traces at YACS launch and SALOME closure
[modules/yacs.git] / 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, VISU,YACS  
60 Architecture                           GUI       KERNEL                  MED, GEOM, SMESH, VISU,YACS  
61 Architecture                           MED       KERNEL, GUI             SMESH, VISU
62 Geometry                               GEOM      KERNEL, GUI             SMESH
63 Mesh                                   SMESH     KERNEL, GUI, GEOM, MED
64 Supervision                            YACS      KERNEL, GUI
65 Visualization                          VISU      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