============================================================
README for:
* Randomizer module : version 0.2
* Sierpinsky module : version 0.2
============================================================

Contents of this file:

1. Introduction.
2. Prerequisites.
3. Installation.
4. Launching.
5. Functionality.
6. Testing.

=======================================================
1. Introduction.
=======================================================

Randomizer and Sierpinsky SALOME-based modules implement simple interface to calculate Sierpinsky fields.

=======================================================
2. Prerequisites.
=======================================================

SALOME platform.
All other products are those used by SALOME.

=======================================================
3. Installation.
=======================================================

The compilation procedure is exactly the same as for other SALOME modules:

3.1. install SALOME with all prerequisite products;
3.2. unpack Randomizer and Sierpinsky modules sources;
3.3  set environment:

   source <salome_install_dir>/env_products.csh

   where <salome_install_dir> is a directory where SALOME is installed to.

3.4 create build directory for Randomizer module:

   mkdir RANDOMIZER_BUILD
   cd RANDOMIZER_BUILD

3.5 make and install Randomizer module:

   cmake -DCMAKE_BUILD_TYPE=<Mode> -DCMAKE_INSTALL_PREFIX=${RANDOMIZER_install_dir} ${RANDOMIZER_src_dir}
   make
   make install

   where <Mode> is build mode (Release or Debug),
   <RANDOMIZER_src_dir> is a Randomizer module sources directory and 
   <RANDOMIZER_install_dir> is a directory where you want to install the Randomizer module.

3.6. Repeat 3.4, 3.5 steps for Sierpinsky module.

Launch 'cmake --help' command to learn more about configuration options.

=======================================================
4. Launching.
=======================================================

To launch SALOME application the following steps should be performed:

4.1. set environment:

   source <salome_install_dir>/env_products.csh

   where <salome_install_dir> is a directory where SALOME is installed to.

4.3. add Randomizer and Sierpinsky modules environment:

   setenv RANDOMIZER_ROOT_DIR <RANDOMIZER_install_dir>
   setenv SIERPINSKY_ROOT_DIR <SIERPINSKY_install_dir>

   where <RANDOMIZER_install_dir> and <SIERPINSKY_install_dir> are the directories where
   you have installed Randomizer and Sierpinsky modules correspondingly (see paragraph 3 above).

4.4. launch SALOME:

   ${KERNEL_ROOT_DIR}/bin/salome/runSalome --modules=SMESH,VISU,RANDOMIZER,SIERPINSKY
   
=======================================================
5. Functionality.
=======================================================

5.1 Randomizer module

Randomizer module is implemented as pure Python module. It does not have any GUI.
The IDL interface includes two methods:

- void InitPoint( out double theX, out double theY );

  to generate a random 2D point; X and Y coordinates are in [0,1) range;

- long NextIteration();

  to calculate next random iteration step: the integer value in range {1,3}.

  The functionality of this module is used by Sierpinsky module to calculate Sierpinsky fields.

5.2. Sierpinsky module.

The engine interface includes the following methods:

- void Init( in double X1, in double Y1, in double X2, in double Y2, in double X3, in double Y3 );

  to initialize the engine with three points which will be used as reference points in the calculations;

- void Reset();

  to initializes the engine with three default reference points: (0.5, 1), (0, 0), (1, 0);

- void NextPoint( in double X, in double Y, in long iter, out double nextX, out double nextY );

  calculates next iteration point, basing on the previous one and the iteration step given from 
  Randomizer engine; this method is called subsequently in the loop to generate the points cloud;

- boolean ExportToJPEG( in string fileName, in long size );

  exports the collected points data to the JPEG file;

- boolean ExportToMED( in string fileName, in double size );

  exports the collected points data to the MED file.

  The Init() and Reset() methods clear the collected points data and prepare engine to the new calculations.
  The JPEG file can be viewed with help of any image viewer supporting JPEG format.
  The MED files created by ExportToMED() method can be then imported in the Post-Pro (VISU) module for the
  visualization (see below).

=======================================================
6. Testing.
=======================================================

6.1. GUI mode.

Launch SALOME (see paragraph 4) and create a new study. To activate Sierpinsky module click the corresponding
button on the 'Components' toolbar or select it in the components combo-box.

The only action of the Sierpinsky module's GUI is available via 'Sierpinsky' main menu - it is a 'Run' command
(there is also corresponding button on the toolbar).
This command opens 'Run Sierpinsky Algo' dialog box which allows:

- to define a start point for the calculations; if 'Random' checkbox is turned on, the start point will
be generated automatically via Randomizer module functionality;

- to define three reference points for the algo; if 'Random' checkbox is turned on, the reference points
will be generated automatically via Randomizer module functionality; if 'Default' checkbox is turned on
the default values will be used;

- to enter the number of the points to be calculated;

- to create JPEG image after calculcations finishing; 'Image size' parameter defines the size of the image side
in pixels;

- to export results to the MED file after calculcations finishing; 'Mesh size' parameter defines the mesh range.

- to import generated MED file automatically to the Post-Pro (VISU) module for the further visualisation.

After pressing the 'Start' button the calculation begins. It is possible to stop the calculation by pressing 
'Stop' button. The progress bar in the lower part of the dialog box displays the calculation status.

6.2. Visualization.

Activate Post-Pro (VISU) module by clicking the corresponding button on the 'Components' toolbar.
Select 'File - Import from file' menu command. Select the MED file, click 'Open' button. The MED file is imported
to the study.
Note: the MED file can be automatically imported to the study after finishing of the calculations
(see previous paragraph).

Select 'Post-Pro/<med_file>.med/Sierpinsky/Families/onNodes' object in the Object Browser, invoke context popup
menu by mouse right-button click and select 'Display Only' command. The cloud of points is displayed in the viewer.
Note: the visualizaion of mesh is only possible in the VTK viewer.

6.3. Supervision.

Activate YACS module by clicking the corresponding button on the 'Components' toolbar.
There are two sample YACS schemas which allow to test the Randomizer and Sierpinsky modules
functionality. These files can be found in the <SIERPINSKY_install_dir>/share/salome/resources directory
where <SIERPINSKY_install_dir> is the directory where you have installed Sierpinsky module (see paragraph 3).

Call 'YACS - Import Schema' menu command, then browse to the 'schema1.xml' or 'schema2.xml' file and click 'Open' button.
To prepare the schema for execution, call 'YACS - Run Current Schema' menu command or just click the corresponding toolbar button.
Then launch the ready schema by calling 'YACS - Start/Resume execution' menu command.

The both schemas implement simple loop to perform calculations. The first schema uses default parameters and 
exports the generated data to the JPEG file after calculation finishing.

The second schema is some more complicated. It uses random start and reference points. After the calculations finishing
it exports the data to the JPEG file and to the MED file, then automatically imports the MED file to the Post-Pro
module and displays it in the new 3d viewer (the 'ImportToVisu' inline node performs the importation and visualizing).