.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "LUCIOLE 1"
.TH LUCIOLE 1 "2020-02-06" "lustre v4, release III.a" "Lustre V4 Distribution"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
luciole, simec \- Lustre graphical simulation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBluciole\fR \fIfile\fR\fB.lus\fR \fBnode\fR [ \fBoptions\fR]
.PP
\&\fBluciole\fR \fIfile\fR\fB.ec\fR [ \fBoptions\fR ]
.PP
\&\fBsimec\fR \fIfile\fR\fB.ec\fR [ \fBoptions\fR ]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Lustre graphical simulation is based on the same
library than the file-to-file simulator \fBecexe\fR.
The main tool is \fBsimec\fR, based on tcl-tk for the graphical
aspects.
.PP
When called with a lustre file name, the script \fBluciole\fR calls
\&\fBlus2ec\fR and then \fBsimec\fR with the remaining options
(otherwise it behaves like \fBsimec\fR).
.SS "Main window"
.IX Subsection "Main window"
\&\fBsimec\fR opens a main window containing a widget for each input
and each output of the ec program. Input widgets allow the user
to set the input values, while output widgets just show the current
values of the program output. Basically, Boolean inputs are implemented by
buttons, while numerical inputs are implemented by \*(L"scale widgets\*(R".
.SS "Boolean mode: auto step vs compose"
.IX Subsection "Boolean mode: auto step vs compose"
The behavior of Boolean inputs depend on the \fImode\fR:
.IP "\(bu" 4
In \fIauto-step\fR mode, Boolean inputs are supposed to be exclusive,
and a step is performed as soon as an input button is pressed.
.IP "\(bu" 4
In \fIcompose\fR mode, Boolean inputs are displayed as \*(L"check buttons\*(R":
the user may select/deselect Boolean inputs without performing a
computation step.
.PP
Whatever is the current mode, the pre-defined button \fBStep\fR allows
the user to provoque a computation step.
.PP
The current mode can be changed via the \fBClocks\fR menu.
.SS "Input/output layout"
.IX Subsection "Input/output layout"
Input/output widgets are organized into lines and columns.
The tool normally opens a panel with a column for the inputs, and 
a column for the outputs, but the user may define a customized layout
by defining an associated \fIInput Output Panel\fR file (\fBiop\fR extension).
When called with \fIfoo.ec\fR, \fBsimec\fR first searches for a file
whose name is \fIfoo.iop\fR, and tries to use it as a layout description.
.PP
Since no specific tool is available, the best way to customize the
input/output panel for a program \fIfile.ec\fR is to first get the 
default \fIiop\fR description by using the \fBsave file.iop\fR command
in the \fBFiles\fR menu, and then edit the resulting file.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-h\fR" 4
.IX Item "-h"
(help) display available options.
.IP "\fB\-v\fR" 4
.IX Item "-v"
set verbose mode: every reaction is echoed on standard output.
The output format follows the \fIrif\fR conventions; as a consequence
the outputed text can be used as a correct Reactive Input Flow description
by tools that support this format (cf. \fBsim2chro\fR).
.IP "\fB\-auto\fR" 4
.IX Item "-auto"
start in \fIauto step\fR mode.
.IP "\fB\-comp\fR" 4
.IX Item "-comp"
start in \fIcompose\fR mode.
.IP "\fB\-p\fR \fIfile\fR\fB.iop\fR" 4
.IX Item "-p file.iop"
(panel) specify a particular layout description.
.SH "IOP FORMAT"
.IX Header "IOP FORMAT"
.SS "Lexical aspects"
.IX Subsection "Lexical aspects"
.IP "\(bu" 4
Comments: all characters between "\f(CW\*(C`//\*(C'\fR\*(L" and the end
of the line are ignored; all characters between \*(R"\f(CW\*(C`/*\*(C'\fR\*(L" and the following
\&\*(R"\f(CW\*(C`*/\*(C'\fR" are ignored.
.IP "\(bu" 4
\&\fInumber\fR is an integer or real notation.
.IP "\(bu" 4
\&\fIident\fR means any string of alphanumeric characters, including \fInumber\fR.
.IP "\(bu" 4
\&\fIstring\fR means any string of printable characters enclosed whithin
quotes.
.SS "Syntax"
.IX Subsection "Syntax"
Parts whithin brackets are optional; \fIitem-list\fR simply means one or
more \*(L"space-separated\*(R" items.
.PP
\fIiopfile\fR ::= \fBmodule\fR \fIstring\fR
            \fBinputs\fR \fIvar-decl-list\fR
            \fBoutputs\fR \fIvar-decl-list\fR
            \fBpanels\fR \fIpanel-list\fR
.PP
\fIvar-decl\fR ::= \fIident\fR \fB:\fR \fItype\fR [\fBlabel = \fR \fIstring\fR] \fB;\fR
.PP
.PP
Additional information can be added to integer and real types.
.PP
\fItype\fR ::= \fBbool\fR
       \f(CW|\fR \fBint\fR [\fBmin = \fR \fInumber\fR] [\fBmax = \fR \fInumber\fR]
       \f(CW|\fR \fBreal\fR [\fBmin = \fR \fInumber\fR] [\fBmax = \fR \fInumber\fR] [\fBstep = \fR \fInumber\fR]
.PP
A panel expression is built with the n\-ary operators
\&\fBline\fR and \fBcol\fR. Leaf expressions are references to
input, output or panel identifiers.
The leaf \fBbox\fR has no meaning: it simply \*(L"takes place\*(R" 
in the layout.
An identifier must be declared before it can be used. 
The panel \fBtop\fR must be the last declared.
.PP
\fIpanel\fR ::= \fIident\fR \fB=\fR \fIexp\fR \fB;\fR
.PP
\fIexp\fR ::= \fBcol\fR \fB{\fR \fIexp-list\fR \fB}\fR
      \f(CW|\fR \fBline\fR \fB{\fR \fIexp-list\fR \fB}\fR
      \f(CW|\fR \fB$\fR\fIident\fR
      \f(CW|\fR \fBbox\fR
.PP
.SS "\s-1THE RESSOURCE FILE\s0"
.IX Subsection "THE RESSOURCE FILE"
The user may customize \fBluciole\fR by defining a ressource file,
whose name must be \fBluciolerc.tcl\fR.
The extension outlines the fact that this file \fIis a tcl/tk script file\fR.
A standard ressource file is provided in the Lustre distribution which
can be copied and modified:
.PP
.Vb 1
\&        $LUSTRE_INSTALL/lib/luciolerc.tcl
.Ve
.PP
The ressource file is automatically searched
when luciole has initialized its window.
The file is searched first in the current directory,
then in the user home directory, and at last in the lustre
distribution library:
.PP
.Vb 5
\&        ./luciolerc.tcl 
\&        ./.luciolerc.tcl
\&        ~/luciolerc.tcl
\&        ~/.luciolerc.tcl
\&        $LUSTRE_INSTALL/lib/luciolerc.tcl
.Ve
.PP
The first encountered file in the previous list is evaluated
\&\fIas it is\fR by the luciole tcl interpret, and, as a consequence,
it has (potentially) access to all internal variable defined by luciole.
However it is strongly recommended to only use a few set of variables,
as it is explained in the standard ressource file.
The most useful variables are:
.IP "\fBGlobal(verbose)\fR" 4
.IX Item "Global(verbose)"
(read/write) holds a Boolean value (\fB1\fR or \fB0\fR) indicating wheter
the verbose mode is set or not.
.IP "\fBGlobal(verbose_channel)\fR" 4
.IX Item "Global(verbose_channel)"
(read/write) holds a tcl channel identifier (initially \fBstdout\fR)
indicating where to put messages in verbose mode.
.IP "\fBGlobal(show_step_ctr)\fR" 4
.IX Item "Global(show_step_ctr)"
(read/write) is a Boolean indicating if the step counter is shown 
(\fB1\fR) or not (\fB0\fR).
.IP "\fBGlobal(show_step)\fR" 4
.IX Item "Global(show_step)"
(read/write) is a Boolean indicating if the step button is shown
(\fB1\fR) or not (\fB0\fR).
.IP "\fBGlobal(auto_step)\fR" 4
.IX Item "Global(auto_step)"
(read/write) is a Boolean indicating if luciole runs in
\&\fIauto-step mode\fR (\fB1\fR) or in \fIcompose mode\fR (\fB0\fR).
.PP
Note that some command line options (\fB\-v\fR, \fB\-auto\fR, \fB\-comp\fR)
may override commands in the ressource file.
.PP
Informations on the current program are also available;
\&\fIthose variables may not be modified\fR:
.IP "\fBGlobal(module_name)\fR" 4
.IX Item "Global(module_name)"
(read only) is the name of the running lustre node (string).
.IP "\fBGlobal(input_names)\fR" 4
.IX Item "Global(input_names)"
(read only) is the list of input names (string list).
.IP "\fBGlobal(input_types)\fR" 4
.IX Item "Global(input_types)"
(read only) is the list of input types (string list).
.IP "\fBGlobal(output_names)\fR" 4
.IX Item "Global(output_names)"
(read only) is the list of output names (string list).
.IP "\fBGlobal(output_types)\fR" 4
.IX Item "Global(output_types)"
(read only) is the list of output types (string list).
.PP
At last, a tk container widget (i.e. a \fIframe\fR) is reserved
in the lurette window for user's customization. Most preciselly,
this widget (initially empty) is located in the luciole menubar,
and its typical use is to add one or more user-defined menu buttons
.IP "\fBGlobal(user_menu)\fR" 4
.IX Item "Global(user_menu)"
(read only) contains the tk-path of a frame where the user can
pack his/her own menus.
.PP
The standard ressource file is an example of how to create such a menu:
it adds a menu button \fBTools\fR, with a command \fBsim2chro\fR that 
dynamically launches the chronogram manager \fIsim2chro\fR.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
The environement variable \fB\s-1LUSTRE_INSTALL\s0\fR must exist and hold
the path of the lustre v4 distribution.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
lustre, lus2ec, ecexe, luciole, simec, lus2oc, ec2oc, ocmin, lus2atg, oc2atg,
ec2c, poc, lux, lesar, ecverif, xlesar