*************
TRUST scripts
*************

To run the TRUST tools, TRUST environment must be initialized.

To initialize the TRUST environment :
cd TRUST
source ./env_TRUST.sh


****************
data set support
****************

Notice first that the reference manual which contains the information needed to carry out 
a data set is TRUST_Generic_documentation.pdf (located in $TRUST_ROOT/doc/TRUST)


-EditData : to support user when carrying out a data set by indicating keywords specific to each object
	    located in $TRUST_ROUT/Outils/TRIOXDATA
	    
	syntax : EditData jdd.data
	      or trust -xedit jdd


-VerifData : to support user when writing a data by checking keywords specific to each object
	     located in $TRUST_ROUT/Outils/TRIOXDATA
	    
	syntax : VerifData jdd.data
	      or trust -xcheck jdd
 
 
-cherche.ksh : to identify all the data sets from the no regression data base (Reference, Validation, Verification, ...)
	       which contain some sepcified keywords (word1 word2...wordn)
	       located in $TRUST_ROOT/bin/KSH
	
	syntax : cherche.ksh [-reference_only] word1 word2 ...wordn
	      or trust -search word1 word2 ...wordn
		 The identified data set are listed in the file 'liste_cherche'
		
	remarks : Use the @ character to replace blank between two words
		  Use the * character to look for incomplete words
		  Use the -reference_only option to look for only from the Reference data base
 
 
-Qui : to know the list of test cases to run for a class or method modified
       located in $TRUST_ROOT/bin/KSH
	
	syntax : Qui class|class::method
	      or trust -check class|class::method
		 The identified data set are listed in the file 'liste_cas'


-copie_cas_test : to copy a test case directory from the tests database under the present directory
                  located in $TRUST_ROOT/bin/KSH
       
        syntax : copie_cas_test jdd [$TRUST_TESTS]
              or trust -copy jdd
		  
		  
-make_PAR.data : to generate data sets used for sequential calculation - cutting domain - parallel calculation.
		 located in $TRUST_ROOT/bin/KSH
	
	syntax : make_PAR.data jdd [nb_procs]
	      or trust -partition jdd [nb_procs]
		 => creates SEQ_jdd.data : used to perform sequential calculation
		 => creates DEC_jdd.data : used to carry out domain cutting
		    (moreover the script uses DEC_jdd data set to create the .Zones files)
		 => creates PAR_jdd.data : used to perform parallel calculation
		
	remarks : Use the nb_procs option to specify a number of parts other than that stated in the datafile
		  The jdd (data set) must be previously prepared with the following markers
		  (see a data set from the no regression data base as an example)
		  # BEGIN MESH #
		  ...
		  # END MESH #
		  # BEGIN PARTITION
		  ...
		  END PARTITION #
		  # BEGIN SCATTER
		  ...
		  END SCATTER #
		  
		  
		  
********************
to run a calculation
********************

-trust : to perform a calculation
	 located in $TRUST_ROOT/bin
	 
	syntax : trust [option] jdd [1>jdd.out 2>jdd.err] for sequential calculation
		 identical to : $exec jdd [ 1>jdd.out 2>jdd.err ]
		 
	 	 trust PAR_jdd nb_procs [ 1>par_jdd.out 2>par_jdd.err ] for parallel calculation
		 identical to : mpirun -np nb_procs $exec PAR_jdd nb_procs [ 1>par.out 2>par.err ]
		
	remarks : Use the -help option to list the available options
                  source env_TRUST.sh       => access to TRUST's binary  + TRUST's cases tests
                  source env_BALTIK.sh      => access to BALTIK's binary + BALTIK's cases test
                  source full_env_BALTIK.sh => access to BALTIK's binary + BALTIK and TRUST's cases test
		 		 	 
		 
-lance_test : to run a case from the no regression data base and compare the results to the reference ones.
	      located in $TRUST_ROOT/bin

	syntax : echo jdd | lance_test [-print] [-distant] [-nomail] [-efface] [-no_timeout] [$exec] [$directory]
	      or trust -check jdd
	
	remarks : echo 0 | lance_test to apply lance_test to all the no regression cases
	       or trust -check all
		  echo liste | lance_test to apply lance_test to the cases listed in the liste file
	       or trust -check liste
		  The reporting file (.tests_TRUST_mpi[_opt]) of the comparison with the reference results is 
		  located in /home/user/.tmp_TRUST_name_view/tests


-Run_fiche : to run a validation case
             located in $TRUST_ROOT/bin
       
        syntax : Run_fiche [-help]
               For jupyter's validation forms (new formalism since v1.9.0):
                 A validation_file.ipynb must exist in  $TRUST_ROOT/Validation/Rapports_automatiques/.../.../my_validation_form/
                 my_validation_form should contain src folder with a datafile at least
                 trust -jupyter => to create ipynb file
                 cd $TRUST_ROOT/Validation/Rapports_automatiques/.../.../my_validation_form/
                 Run_fiche => will open the notebook in a web browser
                 Run_fiche -export_pdf => will create a rapport.pdf in the build directory
                 Run_fiche -export_tex => will create a rapport.tex in the build directory

               For .prm validation forms (FOR APPLICATIONS BASED ON TRUST ONLY!):
		 A validation_file.prm must exist in $TRUST_ROOT/Validation/Rapports_automatiques/.../.../my_validation_form/src
                 trust -prm jdd => to create a prm file
                 A rapport.pdf file is created in $TRUST_ROOT/Validation/Rapports_automatiques/.../.../my_validation_form/build


-Plot2d.sh : IHM to run a calculation and to post-process some fields
             located in $TRUST_ROOT/exec/TRUST_PLOT2D
       
        syntax : bash Plot2d.sh jdd
              or trust -evol jdd
		 A jdd.data must exist
		    
 
 
***************************
to post-process some fields
***************************

-Run_sonde : to post_process probes (and eventually run the calculation) 
	     located in $TRUST_ROOT/bin
	     
	syntax : Run_sonde [$exec] jdd
	      or trust -probes jdd
		 If executable file is specified it is necessary to specify the study and eventually the data set.
		 In that case the calculation is started and the post-processing tool is opened. If no executable
		 file is specified only the post-processing tool is activated.
		   -select the directory which contains the probes files ("." for current directory)
		   -select a number N to post-process the probe wich is associated to this number
		   -select -N to close the probe
		   -select # sign to close the Run_sonde post-processing tool 
		
	remarks : -number N=0 is dedicated to visualization of the convergence criteria
		  -in the case of a segment probe the vizualisation corresponds to the last post-processed time
		  -&n : scale the plot n
		  -nF : animate the plot profile n
		  -A: to rename result files  
		  
		  
-extrait_coupe : to extract a segment probe at a specific time
		 located in $TRUST_ROOT/bin
		 
	syntax : extrait_coupe jdd PROBE_NAME [time] 	
	      or trust -probes jdd
		 A jdd_PROBE_NAME.coupe[.time] file is created	   
		 
	remarks : PROBE_NAME corresponds to the name given to the probe in the data set (jdd)
	 	  and caps must be used to indicate this name when using extrait_coupe tool