.. _rappels:
================================================================
-Rappels sur la plate-forme SALOME
+Reminders about the SALOME platform
================================================================
-Définitions
+Definitions
================================================================
- - **Module SALOME** : un module SALOME est un regroupement de composants SALOME. Il réside dans un répertoire
- dont la structure est standardisée. Ses composants sont décrits dans un fichier XML de nom <module>Catalog.xml.
-
- - **Composant SALOME** : c'est l'équivalent SALOME d'un code de calcul. Il peut prendre la forme d'une bibliothèque dynamique ou
- d'un module Python.
-
- - **Service SALOME** : chaque composant a un ou plusieurs services. Un service est l'équivalent d'une subroutine Fortran, d'une
- fonction C, d'une méthode C++ ou Python. Seuls les services de composant peuvent être couplés avec le coupleur YACS.
- Le couplage est réalisé en connectant les ports d'entrée-sortie dont sont dotés les services.
- Ces ports peuvent être de deux types : dataflow ou datastream.
-
- - **Port dataflow** : un port dataflow est un point de connexion pour l'échange de données. Il a un nom qui est le
- nom de la variable échangée, un type qui indique le type de donnée (double, long, string, ...) et un sens (entrée
- ou sortie). On peut connecter un port dataflow entrant avec un port dataflow sortant d'un type compatible.
- La variable portée par le port est échangée en fin de service (port sortant) et en début de service (port entrant).
- Aucun échange de donnée n'a lieu pendant l'exécution du service.
-
- - **Port datastream** : un port datastream permet l'échange de données pendant l'exécution. Comme un port dataflow, il
- a un nom, un type et un sens mais il a en plus un mode de dépendance itératif (I) ou temporel (T).
- On peut connecter un port datastream entrant uniquement avec un port datastream sortant de même type.
- Il peut exister plusieurs classes de port datastream.
- Ici, on ne traitera que des ports datastream CALCIUM.
-
- - **Coupleur YACS** : c'est un module SALOME qui permet d'éditer et d'exécuter des schémas de couplage qui sont
- principalement sous la forme d'un fichier XML. Le module fournit une interface utilisateur graphique pour
- éditer un schéma, l'exécuter et suivre son exécution.
-
- - **Instance de composant** : on peut avoir plusieurs exemplaires du même composant qui sont exécutés par SALOME
- dans une même session. Pour distinguer ces exemplaires, on parle d'instance de composant. On peut faire un parallèle
- avec les termes code de calcul (composant) et exécution (instance de composant).
-
- - **Container** : Processus SALOME qui exécute les composants. Il a la responsabilité de charger (bibliothèque dynamique
- ou module Python) et d'enregistrer les composants. Le choix des containers peut avoir de l'importance si on veut
- qu'un composant ne soit pas dans le même exécutable qu'un autre.
-
- - **Application SALOME** : ensemble de modules SALOME intégrés dans la plate-forme SALOME. Cette plate-forme
- est batie sur les modules de base KERNEL et GUI qui fournissent les services de lancement des composants
- et d'intégration dans l'IHM graphique. Une application SALOME fournit plusieurs scripts qui permettent
- de lancer l'application (runAppli), de se mettre dans l'environnement de l'application (runSession) et d'autres
- plus internes comme le lancement distant (runRemote)
-
-Modules et composants SALOME
+ - **SALOME module**: a SALOME module is a group of SALOME components. It is located in a directory with a standard structure.
+ Its components are described in an XML file named <module>Catalog.xml.
+ - **SALOME component**: this is the SALOME equivalent of a calculation code. It may be in the form of a dynamic
+ library or a Python module.
+ - **SALOME service**: each component has one or several services. A service is the equivalent of a Fortran
+ subroutine, a C function, a C++ method or a Python method. Only component services can be coupled with the YACS coupler.
+ Coupling is done connecting input-output ports with which services are provided. There are two types of these
+ ports, dataflow and datastream.
+ - **Dataflow port**: a dataflow port is a connection port for exchanging data. It has a name that is the name of the
+ exchanged variable, a type that indicates the data type (double, long, string, etc.) and a direction (input or output).
+ An input dataflow port can be connected with an output dataflow port of a compatible type. The variable carried by
+ the port is exchanged at the end of the service (output port) or at the beginning of the service (input port).
+ No data exchange takes place during execution of the service.
+ - **Datastream port**: a datastream port is used to exchange data during execution. Like a dataflow port, it has a name,
+ a type and a direction but it also has an iterative (I) or time (T) dependence mode. An input datastream port can only
+ be connected with an output datastream port of the same type. There may be several classes of datastream port.
+ In this description, we only deal with CALCIUM datastream ports.
+ - **YACS coupler**: this is a SALOME module that edits and executes coupling schemes that are mainly in the form of an
+ XML file. The module provides a graphic user interface to edit a scheme, to execute it and monitor its execution.
+ - **Component instance**: there can be several copies of the same component and they can be executed by SALOME in a
+ single session. A distinction between these copies is made by referring to a component instance. A parallel can be
+ made with the terms calculation code (component) and execution (component instance).
+ - **Container**: SALOME process that executes components. It loads (dynamic library or Python module) and saves
+ components. The choice of containers may be important if it is required that one component should not be in the same
+ executable as another.
+ - **SALOME application**: set of SALOME modules integrated into the SALOME platform. This platform is built on KERNEL
+ and GUI basic modules that provide component running and integration services in the graphic user interface. A SALOME application
+ provides several scripts to run the application (runAppli), enter the application environment (runSession) and other
+ more internal scripts such as remote run (runRemote).
+
+SALOME modules and components
==================================================
-Dans son principe, la plate-forme SALOME est décomposée en une plate-forme
-de base nommée module KERNEL et une collection de modules divers.
-
-Un module est un produit compilable et installable qui se concrétise par une arborescence source qui doit
-respecter les règles générales SALOME et qui comprend une procédure de construction, installation qui
-respecte également les règles SALOME.
-Chaque module est géré en configuration dans un module CVS
-indépendant. Chaque module peut livrer des versions à son rythme dans le respect des règles de
-cohérence de SALOME. A chaque module est associée une base de tests de non régression.
-
-Un module a des dépendances avec les autres modules (utilise, est utilisé).
-Le module KERNEL constitue la base de la plate-forme SALOME.
-Tous les autres modules dépendent du module KERNEL.
-
-===================================== ========= ============= ==================================
-Thèmes Modules Utilise Est utilisé par
-===================================== ========= ============= ==================================
-Architecture KERNEL MED, GEOM, SMESH, VISU,YACS
-Architecture MED KERNEL SMESH, VISU
-Géométrie GEOM KERNEL SMESH
-Maillage SMESH KERNEL, MED
-Supervision YACS KERNEL
-Visualisation VISU KERNEL, MED
-===================================== ========= ============= ==================================
-
-Un module contient un ou plusieurs composants SALOME. Un composant SALOME est un objet CORBA qui
-respecte les règles SALOME et qui est déclaré à SALOME au moyen d'un catalogue. Un composant SALOME
-peut être doté d'une interface utilisateur graphique (GUI) qui doit elle-même respecter les règles
-SALOME.
-
-Les containers
+In principle, the SALOME platform is broken down into a basic platform (composed of a KERNEL and a GUI modules)
+and a collection of various modules.
+
+A module is a compilable and installable product that is materialised by a source tree structure that must respect
+SALOME general rules and that includes a construction and installation procedure that also respects SALOME rules.
+Each module is managed in configuration in an independent CVS module. Each module can deliver versions at it own rate
+respecting SALOME consistency rules. A non-regression tests base is associated with each module.
+
+A module has dependencies with other modules (uses, is used). The KERNEL and GUI modules makes up the base of the SALOME platform.
+All other modules depend on these modules.
+
+===================================== ========= ======================= ==================================
+Theme Module Uses Is used by
+===================================== ========= ======================= ==================================
+Architecture KERNEL GUI, MED, GEOM, SMESH, PARAVIS,YACS
+Architecture GUI KERNEL MED, GEOM, SMESH, PARAVIS,YACS
+Architecture MED KERNEL, GUI SMESH, PARAVIS
+Geometry GEOM KERNEL, GUI SMESH
+Mesh SMESH KERNEL, GUI, GEOM, MED
+Supervision YACS KERNEL, GUI
+Visualization PARAVIS KERNEL, GUI, MED
+===================================== ========= ======================= ==================================
+
+A module contains one or several SALOME components. A SALOME component is a CORBA object that respects SALOME rules
+and that is declared to SALOME using a catalog. A SALOME component may be provided with a graphic user interface (GUI)
+that must itself respect SALOME rules.
+
+Containers
======================
-Dans SALOME, les composants sont dynamiquement chargeables. Cette propriété est obtenu
-en utilisant un mécanisme de container.
+In SALOME, components are dynamically loaded. This property is obtained by using a container mechanism.
-Dans ses grandes lignes, un container est un serveur CORBA dont l'interface dispose
-des méthodes nécessaires pour effectuer le chargement déchargement de l'implémentation
-d'un composant SALOME. Pour effectuer le chargement d'un composant, on appellera la méthode
-load_impl du container.
+In general, a container is a CORBA server with an interface that is provided with methods necessary to load
+and unload the implementation of a SALOME component. A component is loaded by calling the container load_impl method.
-La mécanique de base du chargement d'un composant est dépendante du langage d'implémentation choisi.
+The basic mechanism for loading a component depends on the chosen implementation language.
-En C++, la plate-forme utilise le chargement dynamique de bibliothèque (dlopen) et un mécanisme de fonction
-factory dont le nom doit être <Module>Engine_factory (par exemple GEOMEngine_factory, pour GEOM).
-Cette fonction doit retourner l'objet CORBA effectif qui est le composant SALOME.
+In C++, the platform uses dynamic library loading (dlopen) and a factory function mechanism that must be
+named <Component>Engine_factory (for example GEOMEngine_factory, for GEOM component type).
+This function must return the effective CORBA object that is the SALOME component.
-En Python, la plate-forme utilise le mécanisme d'import de Python (import <Module>) et instancie
-le composant SALOME Python en utilisant une classe (ou une factory) de même nom (<Module>) pour
-ce faire.
+In Python, the platform uses the Python import mechanism (import <Component>) and instantiates the Python SALOME
+component using a class (or a factory) with the same name (<Component>).
.. _appli:
-Construction et utilisation d'une application SALOME
+Construction and use of a SALOME application
=========================================================
-Ce document explique comment configurer, installer et utiliser votre propre
-application SALOME à partir d'une liste de modules préinstallés.
+This section explains how to configure, install and use your own SALOME application starting from a list of
+pre-installed modules (see more details in the on line documentation for the KERNEL module defining the
+application concept).
-Principes
+Principles
------------
+A SALOME application is built up from a list of platform basic modules (GEOM, SMESH, ASTER, etc.) or users.
+It consists of a set of shell scripts and directories used to execute the application in different contexts.
-Une application SALOME est construite à partir d'une liste de modules (GEOM, SMESH, ASTER...) de
-base de la plate-forme ou utilisateurs.
-Elle consiste en un jeu de scripts shell et de répertoires qui permettent d'exécuter l'application
-dans différents contextes.
-
-Un utilisateur peut définir plusieurs applications SALOME. Ces applications
-sont utilisables à partir d'un même compte utilisateur. Elles peuvent utiliser
-les mêmes modules (KERNEL ou autre). L'application SALOME est indépendante de KERNEL
-et **ne doit pas être installée dans KERNEL_ROOT_DIR**.
-
-Les prérequis utilisés par chaque application peuvent être différents.
-
-Une session SALOME lancée à partir d'une application SALOME peut s'exécuter
-sur plusieurs calculateurs.
+A user can define several SALOME applications. These applications can be used from several user accounts.
+They can use the same modules (KERNEL or other). The SALOME application is independent of KERNEL
+and **it must not be installed in KERNEL_ROOT_DIR**.
-Pour une installation d'application multi-machines, les modules et les prérequis
-doivent être installés sur toutes les machines impliquées. Il n'est pas nécessaire
-d'installer tous les modules sur toutes les machines à part KERNEL.
-L'utilisateur SALOME doit avoir un compte sur chaque machine. L'accès aux machines
-distantes est réalisé par rsh ou ssh. Ces accès doivent être configurés pour
-un usage sans password. Les comptes peuvent être différents sur les différentes
-machines.
+Prerequisites for each application may be different.
-.. raw:: latex
+A SALOME session run from a SALOME application can be executed on several computers.
- \makeatletter
- \g@addto@macro\@verbatim\small
- \makeatother
+For the installation of a multi-machine application, the modules and prerequisites must be installed on
+all machines involved. There is no need to install all modules on all machines except for KERNEL.
+The SALOME user must have an account on each machine. Remote machines are accessed by rsh or ssh.
+These accesses must be configured for use without a password. The accounts may be different on the different machines.
-
-Créer une application SALOME
+Creating a SALOME application
------------------------------
-On crée une application SALOME avec l'outil appli_gen.py que l'on trouve dans l'installation du module KERNEL.
-Cet outil construit l'application en partant d'un fichier de configuration au format XML qui décrit la liste
-des modules à utiliser (nom, chemin d'installation), le fichier qui positionne l'environnement
-pour les prérequis de SALOME et optionnellement le répertoire des exemples SALOME (SAMPLES_SRC).
+A SALOME application is created using the appli_gen.py tool located in the installation of the KERNEL module.
+This tool builds the application starting from a configuration file in the XML format that describes the list
+of modules to be used (name, installation path), the file that sets the environment for SALOME pre-requisites
+and optionally the SALOME examples directory (SAMPLES_SRC) and a catalog of resources.
+
+The following command is used:
-La commande à utiliser est la suivante::
+.. code-block:: sh
- python <KERNEL_ROOT_DIR>/bin/salome/appli_gen.py --prefix=<install directory> --config=<configuration file>
+ python <KERNEL_ROOT_DIR>/bin/salome/appli_gen.py --prefix=<install directory> \
+ --config=<configuration file>
-où <configuration file> est le nom du fichier de configuration et <install directory> est le nom du répertoire
-dans lequel on veut créer l'application. <KERNEL_ROOT_DIR> indique le répertoire d'installation du module KERNEL.
+where <configuration file> is the name of the configuration file and <install directory> is the name of the
+directory in which the application is to be created. <KERNEL_ROOT_DIR> indicates the directory in which
+the KERNEL module is installed.
-On peut créer le fichier de configuration en modifiant une copie du fichier ${KERNEL_ROOT_DIR}/bin/salome/config_appli.xml.
+The configuration file can be created by modifying a copy of the ${KERNEL_ROOT_DIR}/bin/salome/config_appli.xml file.
+For example:
-En voici un exemple::
+.. code-block:: xml
<application>
- <prerequisites path="/data/tmplgls/secher/SALOME_V4.1.1_MD08/env_products.sh"/>
+ <prerequisites path="/data/SALOME_V5/env_products.sh"/>
+ <resources path="myCata.xml"/>
<modules>
- <!-- variable name <MODULE>_ROOT_DIR is built with <MODULE> == name attribute value -->
+ <!-- variable name <MODULE>_ROOT_DIR is built
+ with <MODULE> == name attribute value -->
<!-- <MODULE>_ROOT_DIR values is set with path attribute value -->
- <!-- attribute gui (defaults = yes) indicates if the module has a gui interface -->
- <module name="KERNEL" gui="no" path="/data/SALOME_V4.1.1/KERNEL_INSTALL"/>
- <module name="GUI" gui="no" path="/data/SALOME_V4.1.1/GUI_4.1.1"/>
- <module name="MED" path="/data/SALOME_V4.1.1/MED_4.1.1"/>
- <module name="GEOM" path="/data/SALOME_V4.1.1/GEOM_4.1.1"/>
- <module name="SMESH" path="/data/SALOME_V4.1.1/SMESH_4.1.1"/>
- <module name="YACS" path="/data/SALOME_V4.1.1/YACS_4.1.1"/>
- <module name="VISU" path="/data/SALOME_V4.1.1/VISU_4.1.1"/>
- <module name="HELLO" path="/data/SALOME_V4.1.1/HELLO1_4.1.1"/>
- <module name="PYHELLO" path="/data/SALOME_V4.1.1PYHELLO1_4.1.1"/>
- <module name="NETGENPLUGIN" path="/data/SALOME_V4.1.1/NETGENPLUGIN_4.1.1"/>
+ <!-- attribute gui (defaults = yes) indicates if the module
+ has a gui interface -->
+ <module name="KERNEL" gui="no" path="/data/SALOME_V5/KERNEL_INSTALL"/>
+ <module name="GUI" gui="no" path="/data/SALOME_V5/GUI_5"/>
+ <module name="MED" path="/data/SALOME_V5/MED_5"/>
+ <module name="GEOM" path="/data/SALOME_V5/GEOM_5"/>
+ <module name="SMESH" path="/data/SALOME_V5/SMESH_5"/>
+ <module name="YACS" path="/data/SALOME_V5/YACS_5"/>
+ <module name="VISU" path="/data/SALOME_V5/VISU_5"/>
+ <module name="HELLO" path="/data/SALOME_V5/HELLO1_5"/>
+ <module name="PYHELLO" path="/data/SALOME_V5/PYHELLO1_5"/>
+ <module name="NETGENPLUGIN" path="/data/SALOME_V5/NETGENPLUGIN_5"/>
</modules>
- <samples path="/data/SALOME_V4.1.1/SAMPLES/4.1.1/SAMPLES_SRC"/>
+ <samples path="/data/SALOME_V5/SAMPLES/SAMPLES_SRC"/>
</application>
-Quelques règles à suivre
+Some rules to be followed
------------------------------
-
-Le répertoire d'application doit être créé sur tous les calculateurs qui devront exécuter des composants de cette application.
-La méthode la plus simple est de créer le répertoire d'application en utilisant le même chemin relatif par rapport au
-répertoire HOME sur chaque machine. Si ce n'est pas souhaité, il est possible d'utiliser des chemins différents suivant
-les calculateurs mais il faudra le préciser dans le fichier de configuration CatalogRessources.xml.
-
-Le répertoire d'application contient des scripts pour initialiser les variables d'environnement et faire des exécutions.
-
-L'environnement est initialisé par des scripts placés dans le sous répertoire env.d. Les scripts pour SALOME sont créés
-au moment de la création de l'application mais l'utilisateur peut ajouter ses propres scripts. Il suffit qu'ils aient
-comme suffixe .sh. Ces scripts doivent être installés sur toutes les machines de l'application.
-
-L'application SALOME fournit à l'utilisateur 4 scripts d'exécution :
-
- - **runAppli** lance une session SALOME (à la manière de ${KERNEL_ROOT_DIR}/bin/salome/runSalome).
- - **runSession** permet de se connecter, dans un shell avec un environnement conforme, à une session SALOME lancée
- précédemment. Sans argument, le script ouvre un shell interactif. Avec arguments, il exécute la commande
- fournie dans l'environnement de l'application SALOME.
- - **runConsole** ouvre une console python connectée à la session SALOME courante. Il est également possible d'utiliser
- runSession puis de lancer python.
-
-
-Les fichiers de configuration de l'application sont :
-
- - **SALOMEApp.xml** : ce fichier est semblable au fichier par défaut qui se trouve dans ${GUI_ROOT_DIR}/share/SALOME/resources/gui.
- Il peut être adapté aux besoins de l'utilisateur.
- - **CatalogRessources.xml** : ce fichier décrit tous les calculateurs que l'application peut utiliser. Le fichier initial
- ne contient que la machine locale. L'utilisateur doit ajouter les machines à utiliser. Si on veut utiliser
- des répertoires d'application quelconques sur les différents calculateurs, il faut préciser dans ce fichier
- leur localisation avec l'attribut appliPath::
-
- appliPath="my/specific/path/on/this/computer"
-
+The application directory must be created on all computers on which components of this application are to be executed.
+The simplest method is to create the application directory using the same relative path from the HOME directory on each machine.
+If this is not wanted, then different paths can be used on different computers, but these paths will have to be specified
+in the CatalogRessources.xml configuration file.
+
+The application directory contains scripts to initialize environment variables and to make executions.
+
+The environment is initialized by scripts placed in the env.d sub-directory. Scripts for SALOME are created at
+the time that the application is created but the user can add his own scripts. All that is necessary is that
+they have the .sh suffix. These scripts must be installed on all machines used by the application.
+
+The SALOME application provides the user with 3 execution scripts:
+ - **runAppli** runs a SALOME session (in the same way as ${KERNEL_ROOT_DIR}/bin/Salome/runSalome).
+ - **runSession** connects to a running SALOME session, in a shell with a conforming environment. If there is no argument, the
+ script opens an interactive shell. If there are arguments, it executes the command supplied in the environment of the SALOME application.
+ - **runConsole** opens a python console connected to the current SALOME session. Another option is to use **runSession** and then to run Python.
+
+The application configuration files are:
+ - **SALOMEApp.xml**: this file is similar to the default file located in ${GUI_ROOT_DIR}/share/SALOME/resources/gui.
+ It can be adapted to the user’s needs.
+ - **CatalogResources.xml**: this file describes all computers that the application might use. The initial file only
+ contains the local machine. The user must add the machines to be used. If it is required to use arbitrary
+ application directories on the different computers, their location must be specified in this file using the appliPath attribute::
+
+ appliPath="/my/specific/path/on/this/computer"
+
+Configuring a SALOME application for remote components
+----------------------------------------------------------
+If you have a multi-machine application, it is possible that some modules (and components) are only available on remote
+computers. In this case, you need to configure your application for this situation by using the **update_catalogs.py** script provided by the
+SALOME application.
+
+The first thing to do is to create a file named **CatalogResources.base.xml** that will contain all information about your multi-machine
+configuration.
+
+Example of **CatalogResources.base.xml** file:
+
+.. code-block:: xml
+
+ <!DOCTYPE ResourcesCatalog>
+ <resources>
+ <machine name="res1" hostname="localhost" >
+ <component name="GEOM_Superv" moduleName="GEOM"/>
+ <modules moduleName="YACS"/>
+ </machine>
+
+ <machine name="res2" hostname="computer1" userName="user" protocol="ssh" appliPath="/home/user/SALOME514/appli_V5_1_4" >
+ <modules moduleName="AddComponent"/>
+ </machine>
+ </resources>
+
+In this file, we say that we have 2 resources **res1** and **res2** on localhost and computer1. On the remote machine, we give
+the SALOME application path and we give, for each resource, the list of available components or modules : GEOM_Superv and YACS on localhost
+and AddComponent on computer1.
+
+Starting from this file, the **update_catalogs.py** script gets all remote catalogs, puts them in local directories (remote_catalogs/<resource name>),
+builds an updated **CatalogResource.xml** file and adds a new environment variable (**SALOME_CATALOGS_PATH** in env.d/configRemote.sh) to the
+SALOME application. With these 3 elements the application is now correctly configured for a multi-machine use.
