/****************************************************************************
**  CUBE        http://www.scalasca.org/                                   **
*****************************************************************************
**  Copyright (c) 1998-2021                                                **
**  Forschungszentrum Juelich GmbH, Juelich Supercomputing Centre          **
**                                                                         **
**  Copyright (c) 2009-2013                                                **
**  German Research School for Simulation Sciences GmbH,                   **
**  Laboratory for Parallel Programming                                    **
**                                                                         **
**  This software may be modified and distributed under the terms of       **
**  a BSD-style license.  See the COPYING file in the package base         **
**  directory for details.                                                 **
****************************************************************************/


/** @page examples Examples of CubePL expressions

@section example1 Simple Examples
<ol>
<li> Calculation of an arithmetical expression
@code
 123.4 + 234 -( 23)^2
 @endcode
</li>
<li>
Calculation of an arithmetical expression with different functions
@code
 sin(23 + ln(12))
 @endcode
</li>
</ol>
@section example2 Complex Examples
@subsection example3 Different made-up expressions
<ol>
<li>Definition of a constant function
@code
 { return 24; }
 @endcode
</li>
<li>Definition of a more complex function
@code
 { return sin ({ return 1; }); }
 @endcode
</li>
<li>Definition of a function with an access to one variable
@code
 {${a}=123; return ${a}; }
 @endcode
</li>
<li>Definition of a function with a control structure
@code
 {
  ${a}=metric::visits();
  ${b}=0;
  if (${a}>100)
    { ${b}=metric::time(); };
 return ${b};
 }
 @endcode
</li>
<li>Definition of a function with a loop structure
@code
 {
  ${a}=0; ${b}=0;
  while (${a}<123)
   {
      ${b}=${b}+metric::time();
      ${a}=${a}+1;
   };
 return ${b};
 }
 @endcode
</li>
<li>Definition of a function with a access to predefined variable
@code
 {
  ${a}=0;
  if (${calculation::region::name}[${calculation::callpath::id}] =~ /^MPI_/)
   {
      ${a}=metric::time();
   };
 return ${a};
 }
 @endcode
</li>
</ol>
@subsection specialmetrics Special metrics of Scalasca
<ol>
<li>Calculation of an average runtime of a call path (Kenobi metric, postderived)
@code
metric::time(i)/metric::visits(e)
 @endcode
</li>
<li>Calculation of the time, spend in MPI synchronization calls
<ol>
<li>(initialization )
@code
{
    global(mpi_synchronization);
    ${i}=0;
    while( ${i}  < ${cube::#callpaths} )
    {
        ${mpi_synchronization}[${i}] = 0;
        ${regionid} = ${cube::callpath::calleeid}[${i}] ;
        if (
            (${cube::region::paradigm}[ ${regionid} ] seq "mpi")
            and
            (
            (${cube::region::name}[${regionid} ] seq "mpi_barrier" )
            or
            (${cube::region::name}[${regionid} ] seq "mpi_win_post" )
            or
            (${cube::region::name}[${regionid} ] seq "mpi_win_wait" )
            or
            (${cube::region::name}[${regionid} ] seq "mpi_win_start" )
            or
            (${cube::region::name}[${regionid} ] seq "mpi_win_complete" )
            or
            (${cube::region::name}[${regionid} ] seq "mpi_win_fence" )
            or
            (${cube::region::name}[${regionid} ] seq "mpi_win_lock" )
            or
            (${cube::region::name}[${regionid} ] seq "mpi_win_unlock" )
            )
            )
        {
                ${mpi_synchronization}[${i}] = 1;
        };
        ${i} = ${i} + 1;
    };
    return 0;
}
 @endcode
</li>
<li> (actual calculation )
@code
{
    ${a}=0;
    if ( ${mpi_synchronization}[${calculation::callpath::id} ]== 1 )
    {
            ${a} = metric::time(*,*)-metric::omp_idle_threads(*,*);
    };
    return ${a};
}
 @endcode
</li>
</ol>
</li>
<li>Calculation of thecComputational load imbalance (single participant)

-- NO EXAMPLE YET --
</li>
</ol>
*/
