| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.10"> |
| <meta name="author" content="Copyright (c) 2010, 2020 Contributors to the Eclipse Foundation"> |
| <link rel="icon" type="image/png" href="favicon.png"> |
| <title>Chi documentation (Incubation)</title> |
| <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"> |
| <style> |
| /* Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */ |
| /* Uncomment @import statement to use as custom stylesheet */ |
| /*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/ |
| article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section{display:block} |
| audio,video{display:inline-block} |
| audio:not([controls]){display:none;height:0} |
| html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%} |
| a{background:none} |
| a:focus{outline:thin dotted} |
| a:active,a:hover{outline:0} |
| h1{font-size:2em;margin:.67em 0} |
| abbr[title]{border-bottom:1px dotted} |
| b,strong{font-weight:bold} |
| dfn{font-style:italic} |
| hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0} |
| mark{background:#ff0;color:#000} |
| code,kbd,pre,samp{font-family:monospace;font-size:1em} |
| pre{white-space:pre-wrap} |
| q{quotes:"\201C" "\201D" "\2018" "\2019"} |
| small{font-size:80%} |
| sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline} |
| sup{top:-.5em} |
| sub{bottom:-.25em} |
| img{border:0} |
| svg:not(:root){overflow:hidden} |
| figure{margin:0} |
| fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em} |
| legend{border:0;padding:0} |
| button,input,select,textarea{font-family:inherit;font-size:100%;margin:0} |
| button,input{line-height:normal} |
| button,select{text-transform:none} |
| button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer} |
| button[disabled],html input[disabled]{cursor:default} |
| input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0} |
| button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0} |
| textarea{overflow:auto;vertical-align:top} |
| table{border-collapse:collapse;border-spacing:0} |
| *,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box} |
| html,body{font-size:100%} |
| body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased} |
| a:hover{cursor:pointer} |
| img,object,embed{max-width:100%;height:auto} |
| object,embed{height:100%} |
| img{-ms-interpolation-mode:bicubic} |
| .left{float:left!important} |
| .right{float:right!important} |
| .text-left{text-align:left!important} |
| .text-right{text-align:right!important} |
| .text-center{text-align:center!important} |
| .text-justify{text-align:justify!important} |
| .hide{display:none} |
| img,object,svg{display:inline-block;vertical-align:middle} |
| textarea{height:auto;min-height:50px} |
| select{width:100%} |
| .center{margin-left:auto;margin-right:auto} |
| .stretch{width:100%} |
| .subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em} |
| div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr} |
| a{color:#2156a5;text-decoration:underline;line-height:inherit} |
| a:hover,a:focus{color:#1d4b8f} |
| a img{border:0} |
| p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility} |
| p aside{font-size:.875em;line-height:1.35;font-style:italic} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em} |
| h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0} |
| h1{font-size:2.125em} |
| h2{font-size:1.6875em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em} |
| h4,h5{font-size:1.125em} |
| h6{font-size:1em} |
| hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0} |
| em,i{font-style:italic;line-height:inherit} |
| strong,b{font-weight:bold;line-height:inherit} |
| small{font-size:60%;line-height:inherit} |
| code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)} |
| ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit} |
| ul,ol{margin-left:1.5em} |
| ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em} |
| ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit} |
| ul.square{list-style-type:square} |
| ul.circle{list-style-type:circle} |
| ul.disc{list-style-type:disc} |
| ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0} |
| dl dt{margin-bottom:.3125em;font-weight:bold} |
| dl dd{margin-bottom:1.25em} |
| abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help} |
| abbr{text-transform:none} |
| blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd} |
| blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)} |
| blockquote cite::before{content:"\2014 \0020"} |
| blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)} |
| blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)} |
| @media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2} |
| h1{font-size:2.75em} |
| h2{font-size:2.3125em} |
| h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em} |
| h4{font-size:1.4375em}} |
| table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede} |
| table thead,table tfoot{background:#f7f8f7} |
| table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left} |
| table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)} |
| table tr.even,table tr.alt{background:#f8f8f7} |
| table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6} |
| h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em} |
| h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400} |
| .clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table} |
| .clearfix::after,.float-group::after{clear:both} |
| :not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word} |
| :not(pre)>code.nobreak{word-wrap:normal} |
| :not(pre)>code.nowrap{white-space:nowrap} |
| pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed} |
| pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit} |
| pre>code{display:block} |
| pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal} |
| em em{font-style:normal} |
| strong strong{font-weight:400} |
| .keyseq{color:rgba(51,51,51,.8)} |
| kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap} |
| .keyseq kbd:first-child{margin-left:0} |
| .keyseq kbd:last-child{margin-right:0} |
| .menuseq,.menuref{color:#000} |
| .menuseq b:not(.caret),.menuref{font-weight:inherit} |
| .menuseq{word-spacing:-.02em} |
| .menuseq b.caret{font-size:1.25em;line-height:.8} |
| .menuseq i.caret{font-weight:bold;text-align:center;width:.45em} |
| b.button::before,b.button::after{position:relative;top:-1px;font-weight:400} |
| b.button::before{content:"[";padding:0 3px 0 2px} |
| b.button::after{content:"]";padding:0 2px 0 3px} |
| p a>code:hover{color:rgba(0,0,0,.9)} |
| #header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em} |
| #header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table} |
| #header::after,#content::after,#footnotes::after,#footer::after{clear:both} |
| #content{margin-top:1.25em} |
| #content::before{content:none} |
| #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} |
| #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf} |
| #header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} |
| #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap} |
| #header .details span:first-child{margin-left:-.125em} |
| #header .details span.email a{color:rgba(0,0,0,.85)} |
| #header .details br{display:none} |
| #header .details br+span::before{content:"\00a0\2013\00a0"} |
| #header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)} |
| #header .details br+span#revremark::before{content:"\00a0|\00a0"} |
| #header #revnumber{text-transform:capitalize} |
| #header #revnumber::after{content:"\00a0"} |
| #content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem} |
| #toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em} |
| #toc>ul{margin-left:.125em} |
| #toc ul.sectlevel0>li>a{font-style:italic} |
| #toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0} |
| #toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none} |
| #toc li{line-height:1.3334;margin-top:.3334em} |
| #toc a{text-decoration:none} |
| #toc a:active{text-decoration:underline} |
| #toctitle{color:#7a2518;font-size:1.2em} |
| @media screen and (min-width:768px){#toctitle{font-size:1.375em} |
| body.toc2{padding-left:15em;padding-right:0} |
| #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} |
| #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} |
| #toc.toc2>ul{font-size:.9em;margin-bottom:0} |
| #toc.toc2 ul ul{margin-left:0;padding-left:1em} |
| #toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em} |
| body.toc2.toc-right{padding-left:0;padding-right:15em} |
| body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}} |
| @media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0} |
| #toc.toc2{width:20em} |
| #toc.toc2 #toctitle{font-size:1.375em} |
| #toc.toc2>ul{font-size:.95em} |
| #toc.toc2 ul ul{padding-left:1.25em} |
| body.toc2.toc-right{padding-left:0;padding-right:20em}} |
| #content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px} |
| #content #toc>:first-child{margin-top:0} |
| #content #toc>:last-child{margin-bottom:0} |
| #footer{max-width:100%;background:rgba(0,0,0,.8);padding:1.25em} |
| #footer-text{color:rgba(255,255,255,.8);line-height:1.44} |
| #content{margin-bottom:.625em} |
| .sect1{padding-bottom:.625em} |
| @media screen and (min-width:768px){#content{margin-bottom:1.25em} |
| .sect1{padding-bottom:1.25em}} |
| .sect1:last-child{padding-bottom:0} |
| .sect1+.sect1{border-top:1px solid #e7e7e9} |
| #content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400} |
| #content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em} |
| #content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible} |
| #content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none} |
| #content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221} |
| details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em} |
| details>summary:first-of-type{cursor:pointer;display:list-item;outline:none;margin-bottom:.75em} |
| .admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic} |
| table.tableblock.fit-content>caption.title{white-space:nowrap;width:0} |
| .paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)} |
| table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit} |
| .admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} |
| .admonitionblock>table td.icon{text-align:center;width:80px} |
| .admonitionblock>table td.icon img{max-width:none} |
| .admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase} |
| .admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)} |
| .admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} |
| .exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px} |
| .exampleblock>.content>:first-child{margin-top:0} |
| .exampleblock>.content>:last-child{margin-bottom:0} |
| .sidebarblock{border-style:solid;border-width:1px;border-color:#dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;-webkit-border-radius:4px;border-radius:4px} |
| .sidebarblock>:first-child{margin-top:0} |
| .sidebarblock>:last-child{margin-bottom:0} |
| .sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center} |
| .exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0} |
| .literalblock pre,.listingblock>.content>pre{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em} |
| @media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}} |
| @media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}} |
| .literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class="highlight"],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8} |
| .literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)} |
| .listingblock>.content{position:relative} |
| .listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5} |
| .listingblock:hover code[data-lang]::before{display:block} |
| .listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5} |
| .listingblock.terminal pre .command:not([data-prompt])::before{content:"$"} |
| .listingblock pre.highlightjs{padding:0} |
| .listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px} |
| .listingblock pre.prettyprint{border-width:0} |
| .prettyprint{background:#f7f7f8} |
| pre.prettyprint .linenums{line-height:1.45;margin-left:2em} |
| pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0} |
| pre.prettyprint li code[data-lang]::before{opacity:1} |
| pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none} |
| table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none} |
| table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal} |
| table.linenotable td.code{padding-left:.75em} |
| table.linenotable td.linenos{border-right:1px solid currentColor;opacity:.35;padding-right:.5em} |
| pre.pygments .lineno{border-right:1px solid currentColor;opacity:.35;display:inline-block;margin-right:.75em} |
| pre.pygments .lineno::before{content:"";margin-right:-.125em} |
| .quoteblock{margin:0 1em 1.25em 1.5em;display:table} |
| .quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em} |
| .quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify} |
| .quoteblock blockquote{margin:0;padding:0;border:0} |
| .quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)} |
| .quoteblock blockquote>.paragraph:last-child p{margin-bottom:0} |
| .quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right} |
| .verseblock{margin:0 1em 1.25em} |
| .verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility} |
| .verseblock pre strong{font-weight:400} |
| .verseblock .attribution{margin-top:1.25rem;margin-left:.5ex} |
| .quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic} |
| .quoteblock .attribution br,.verseblock .attribution br{display:none} |
| .quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)} |
| .quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none} |
| .quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0} |
| .quoteblock.abstract{margin:0 1em 1.25em;display:block} |
| .quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center} |
| .quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf} |
| .quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0} |
| .quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem} |
| .quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0} |
| table.tableblock{max-width:100%;border-collapse:separate} |
| p.tableblock:last-child{margin-bottom:0} |
| td.tableblock>.content>:last-child{margin-bottom:-1.25em} |
| td.tableblock>.content>:last-child.sidebarblock{margin-bottom:0} |
| table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede} |
| table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0} |
| table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0} |
| table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0} |
| table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px} |
| table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0} |
| table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0} |
| table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0} |
| table.frame-all{border-width:1px} |
| table.frame-sides{border-width:0 1px} |
| table.frame-topbot,table.frame-ends{border-width:1px 0} |
| table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd),table.stripes-even tr:nth-of-type(even),table.stripes-hover tr:hover{background:#f8f8f7} |
| th.halign-left,td.halign-left{text-align:left} |
| th.halign-right,td.halign-right{text-align:right} |
| th.halign-center,td.halign-center{text-align:center} |
| th.valign-top,td.valign-top{vertical-align:top} |
| th.valign-bottom,td.valign-bottom{vertical-align:bottom} |
| th.valign-middle,td.valign-middle{vertical-align:middle} |
| table thead th,table tfoot th{font-weight:bold} |
| tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7} |
| tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold} |
| p.tableblock>code:only-child{background:none;padding:0} |
| p.tableblock{font-size:1em} |
| ol{margin-left:1.75em} |
| ul li ol{margin-left:1.5em} |
| dl dd{margin-left:1.125em} |
| dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0} |
| ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em} |
| ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none} |
| ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em} |
| ul.unstyled,ol.unstyled{margin-left:0} |
| ul.checklist{margin-left:.625em} |
| ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em} |
| ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em} |
| ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em} |
| ul.inline>li{margin-left:1.25em} |
| .unstyled dl dt{font-weight:400;font-style:normal} |
| ol.arabic{list-style-type:decimal} |
| ol.decimal{list-style-type:decimal-leading-zero} |
| ol.loweralpha{list-style-type:lower-alpha} |
| ol.upperalpha{list-style-type:upper-alpha} |
| ol.lowerroman{list-style-type:lower-roman} |
| ol.upperroman{list-style-type:upper-roman} |
| ol.lowergreek{list-style-type:lower-greek} |
| .hdlist>table,.colist>table{border:0;background:none} |
| .hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none} |
| td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em} |
| td.hdlist1{font-weight:bold;padding-bottom:1.25em} |
| .literalblock+.colist,.listingblock+.colist{margin-top:-.5em} |
| .colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top} |
| .colist td:not([class]):first-child img{max-width:none} |
| .colist td:not([class]):last-child{padding:.25em 0} |
| .thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd} |
| .imageblock.left{margin:.25em .625em 1.25em 0} |
| .imageblock.right{margin:.25em 0 1.25em .625em} |
| .imageblock>.title{margin-bottom:0} |
| .imageblock.thumb,.imageblock.th{border-width:6px} |
| .imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em} |
| .image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0} |
| .image.left{margin-right:.625em} |
| .image.right{margin-left:.625em} |
| a.image{text-decoration:none;display:inline-block} |
| a.image object{pointer-events:none} |
| sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} |
| sup.footnote a,sup.footnoteref a{text-decoration:none} |
| sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} |
| #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} |
| #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} |
| #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} |
| #footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em} |
| #footnotes .footnote:last-of-type{margin-bottom:0} |
| #content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0} |
| .gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0} |
| .gist .file-data>table td.line-data{width:99%} |
| div.unbreakable{page-break-inside:avoid} |
| .big{font-size:larger} |
| .small{font-size:smaller} |
| .underline{text-decoration:underline} |
| .overline{text-decoration:overline} |
| .line-through{text-decoration:line-through} |
| .aqua{color:#00bfbf} |
| .aqua-background{background:#00fafa} |
| .black{color:#000} |
| .black-background{background:#000} |
| .blue{color:#0000bf} |
| .blue-background{background:#0000fa} |
| .fuchsia{color:#bf00bf} |
| .fuchsia-background{background:#fa00fa} |
| .gray{color:#606060} |
| .gray-background{background:#7d7d7d} |
| .green{color:#006000} |
| .green-background{background:#007d00} |
| .lime{color:#00bf00} |
| .lime-background{background:#00fa00} |
| .maroon{color:#600000} |
| .maroon-background{background:#7d0000} |
| .navy{color:#000060} |
| .navy-background{background:#00007d} |
| .olive{color:#606000} |
| .olive-background{background:#7d7d00} |
| .purple{color:#600060} |
| .purple-background{background:#7d007d} |
| .red{color:#bf0000} |
| .red-background{background:#fa0000} |
| .silver{color:#909090} |
| .silver-background{background:#bcbcbc} |
| .teal{color:#006060} |
| .teal-background{background:#007d7d} |
| .white{color:#bfbfbf} |
| .white-background{background:#fafafa} |
| .yellow{color:#bfbf00} |
| .yellow-background{background:#fafa00} |
| span.icon>.fa{cursor:default} |
| a span.icon>.fa{cursor:inherit} |
| .admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} |
| .admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c} |
| .admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} |
| .admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900} |
| .admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400} |
| .admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000} |
| .conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold} |
| .conum[data-value] *{color:#fff!important} |
| .conum[data-value]+b{display:none} |
| .conum[data-value]::after{content:attr(data-value)} |
| pre .conum[data-value]{position:relative;top:-.125em} |
| b.conum *{color:inherit!important} |
| .conum:not([data-value]):empty{display:none} |
| dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility} |
| h1,h2,p,td.content,span.alt{letter-spacing:-.01em} |
| p strong,td.content strong,div.footnote strong{letter-spacing:-.005em} |
| p,blockquote,dt,td.content,span.alt{font-size:1.0625rem} |
| p{margin-bottom:1.25rem} |
| .sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em} |
| .exampleblock>.content{background:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc} |
| .print-only{display:none!important} |
| @page{margin:1.25cm .75cm} |
| @media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important} |
| html{font-size:80%} |
| a{color:inherit!important;text-decoration:underline!important} |
| a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important} |
| a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em} |
| abbr[title]::after{content:" (" attr(title) ")"} |
| pre,blockquote,tr,img,object,svg{page-break-inside:avoid} |
| thead{display:table-header-group} |
| svg{max-width:100%} |
| p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3} |
| h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid} |
| #toc,.sidebarblock,.exampleblock>.content{background:none!important} |
| #toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important} |
| body.book #header{text-align:center} |
| body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em} |
| body.book #header .details{border:0!important;display:block;padding:0!important} |
| body.book #header .details span:first-child{margin-left:0!important} |
| body.book #header .details br{display:block} |
| body.book #header .details br+span::before{content:none!important} |
| body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important} |
| body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always} |
| .listingblock code[data-lang]::before{display:block} |
| #footer{padding:0 .9375em} |
| .hide-on-print{display:none!important} |
| .print-only{display:block!important} |
| .hide-for-print{display:none!important} |
| .show-for-print{display:inherit!important}} |
| @media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem} |
| .sect1{padding:0!important} |
| .sect1+.sect1{border:0} |
| #footer{background:none} |
| #footer-text{color:rgba(0,0,0,.6);font-size:.9em}} |
| @media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}} |
| </style> |
| <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"> |
| <!-- |
| Copyright (c) 2010, 2020 Contributors to the Eclipse Foundation |
| |
| See the NOTICE file(s) distributed with this work for additional |
| information regarding copyright ownership. |
| |
| This program and the accompanying materials are made available under the terms |
| of the MIT License which is available at https://opensource.org/licenses/MIT |
| |
| SPDX-License-Identifier: MIT |
| --> |
| <style> |
| .menu, .submenu, .menuitem, .menuref { |
| background-color: Menu; |
| } |
| |
| .button { |
| border: 1px solid ButtonFace; |
| /* |
| Styling too similar to a real button is considered bad practice, see https://github.com/asciidoctor/asciidoctor/issues/1881#issuecomment-250702085 |
| border: 2px outset ButtonFace; |
| background-color: ButtonFace; |
| */ |
| padding-left: 0.5ex; |
| padding-right: 0.5ex; |
| font-weight: normal; |
| font-family: "Segoe UI","Open Sans","DejaVu Sans",sans-serif; |
| white-space: nowrap; |
| } |
| .button:before { |
| content: none !important; |
| } |
| .button:after { |
| content: none !important; |
| } |
| |
| #footer-text, #footer-text a { |
| color: rgba(255,255,255,.8) |
| } |
| </style> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>Chi documentation (Incubation)</h1> |
| <div class="details"> |
| <span id="author" class="author">Copyright (c) 2010, 2020 Contributors to the Eclipse Foundation</span><br> |
| <span id="revnumber">version 0.1.0.20210126-175926</span> |
| </div> |
| <div id="toc" class="toc2"> |
| <div id="toctitle">Table of Contents</div> |
| <ul class="sectlevel1"> |
| <li><a href="#tut-chapter-chi-tutorial">Chi Tutorial</a> |
| <ul class="sectlevel2"> |
| <li><a href="#tut-chapter-introduction">Introduction</a></li> |
| <li><a href="#tut-chapter-data-types">Data types</a></li> |
| <li><a href="#tut-chapter-statements">Statements</a></li> |
| <li><a href="#tut-chapter-functions">Functions</a></li> |
| <li><a href="#tut-chapter-input-and-output">Input and output</a></li> |
| <li><a href="#tut-chapter-stochastic-behavior">Modeling stochastic behavior</a></li> |
| <li><a href="#tut-chapter-processes">Processes</a></li> |
| <li><a href="#tut-chapter-channels">Channels</a></li> |
| <li><a href="#tut-chapter-buffers">Buffers</a></li> |
| <li><a href="#tut-chapter-servers-with-time">Servers with time</a></li> |
| <li><a href="#tut-chapter-conveyors">Conveyors</a></li> |
| <li><a href="#tut-chapter-simulation-and-experiments">Simulations and experiments</a></li> |
| <li><a href="#tut-chapter-svg-visualization">SVG visualization</a></li> |
| <li><a href="#tut-chapter-svg-example">SVG visualization example</a></li> |
| </ul> |
| </li> |
| <li><a href="#ref-chapter-reference-manual">Chi Reference Manual</a> |
| <ul class="sectlevel2"> |
| <li><a href="#ref-chapter-global-definitions">Global definitions</a></li> |
| <li><a href="#ref-chapter-statements">Statements</a></li> |
| <li><a href="#ref-chapter-expressions">Expressions</a></li> |
| <li><a href="#ref-chapter-standard-library">Standard library functions</a></li> |
| <li><a href="#ref-chapter-distributions">Distributions</a></li> |
| <li><a href="#ref-chapter-types">Types</a></li> |
| <li><a href="#ref-chapter-lexical-syntax">Lexical syntax</a></li> |
| <li><a href="#ref-chapter-migration">Model migration</a></li> |
| <li><a href="#ref-chapter-svg-visualization">SVG visualization</a></li> |
| </ul> |
| </li> |
| <li><a href="#tool-chapter-tool-manual">Chi Tool Manual</a> |
| <ul class="sectlevel2"> |
| <li><a href="#tool-chapter-software-operation">Software operation</a></li> |
| <li><a href="#tool-chapter-command-line">Command line options</a></li> |
| </ul> |
| </li> |
| <li><a href="#release-notes-chapter-index">Chi release notes</a> |
| <ul class="sectlevel2"> |
| <li><a href="#version-0-1-unreleased">Version 0.1 (unreleased)</a></li> |
| </ul> |
| </li> |
| <li><a href="#legal-chapter-index">Legal</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Chi is a modeling language for describing and analyzing performance of |
| discrete event systems by means of simulation. |
| It uses a process-based view, and uses synchronous point-to-point |
| communication between processes. A process is written as an imperative |
| program, with a syntax much inspired by the well-known Python language.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Chi is one of the tools of the |
| <a href="https://eclipse.org/escet">Eclipse ESCET™ project</a>.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title="Warning"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>The Eclipse ESCET project, including the Chi language and toolset, |
| is currently in the |
| <a href="https://wiki.eclipse.org/Development_Resources/Process_Guidelines/What_is_Incubation">Incubation Phase</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><span class="image"><img src="./eclipse-incubation.png" alt="eclipse incubation" width="300"></span></p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| You can <a href="eclipse-escet-incubation-chi-manual.pdf">download this manual</a> |
| as a PDF as well. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">Tutorial</dt> |
| <dd> |
| <p>The <a href="#tut-chapter-chi-tutorial">Chi Tutorial</a> |
| teaches the Chi language, and its use in modeling and simulating systems |
| to answer your performance questions.</p> |
| <div class="paragraph"> |
| <p>Some interesting topics are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Basics (<a href="#tut-chapter-data-types">Data types</a>, <a href="#tut-chapter-statements">Statements</a>, |
| <a href="#tut-chapter-stochastic-behavior">Modeling stochastic behavior</a>)</p> |
| </li> |
| <li> |
| <p>Programming (<a href="#tut-chapter-processes">Processes</a>, <a href="#tut-chapter-channels">Channels</a>)</p> |
| </li> |
| <li> |
| <p>Modeling (<a href="#tut-chapter-buffers">Buffers</a>, <a href="#tut-chapter-servers-with-time">Servers with time</a>, |
| <a href="#tut-chapter-conveyors">Conveyors</a>)</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| <dt class="hdlist1">Reference manual</dt> |
| <dd> |
| <p>The <a href="#ref-chapter-reference-manual">Chi Reference Manual</a> |
| describes the Chi language in full detail, for example the top level language |
| elements or all statements. It also contains a list with all standard library |
| functions and a list with all distribution functions.</p> |
| <div class="paragraph"> |
| <p>Some interesting topics are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#ref-chapter-global-definitions">Global definitions</a> (Top level language elements)</p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-standard-library">Standard library functions</a> (Standard library functions)</p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-distributions">Distributions</a> (Available distributions)</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| <dt class="hdlist1">Tool manual</dt> |
| <dd> |
| <p>The <a href="#tool-chapter-tool-manual">Tool manual</a> |
| describes the Chi simulator software. |
| Use of the software to create and simulate Chi programs is also explained.</p> |
| </dd> |
| <dt class="hdlist1">Release notes</dt> |
| <dd> |
| <p>The <a href="#release-notes-chapter-index">Release notes</a> provides information on |
| all Chi releases.</p> |
| </dd> |
| <dt class="hdlist1">Legal</dt> |
| <dd> |
| <p>See <a href="#legal-chapter-index">Legal</a> for copyright and licensing information.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="tut-chapter-chi-tutorial">Chi Tutorial</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This manual explains using the Chi modeling language.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Topics</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#tut-chapter-introduction">Introduction</a> (global description of the aims of the language)</p> |
| </li> |
| <li> |
| <p><em>Basics</em>: Elementary knowledge needed for writing and understanding Chi |
| programs. <em>Start here to learn the language!</em></p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#tut-chapter-data-types">Data types</a> (explanation of all kinds of data and their |
| operations)</p> |
| </li> |
| <li> |
| <p><a href="#tut-chapter-statements">Statements</a> (available process statements)</p> |
| </li> |
| <li> |
| <p><a href="#tut-chapter-functions">Functions</a> (how to use functions)</p> |
| </li> |
| <li> |
| <p><a href="#tut-chapter-input-and-output">Input and output</a> (reading/writing files, displaying output)</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><em>Programming</em>: How to specify parallel executing processes using the Chi |
| language.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#tut-chapter-stochastic-behavior">Modeling stochastic behavior</a> (how to model varying behavior)</p> |
| </li> |
| <li> |
| <p><a href="#tut-chapter-processes">Processes</a> (creating and running processes)</p> |
| </li> |
| <li> |
| <p><a href="#tut-chapter-channels">Channels</a> (connecting processes with each other)</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><em>Modeling</em>: Modeling a real system with Chi.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#tut-chapter-buffers">Buffers</a> (modeling temporary storage of items)</p> |
| </li> |
| <li> |
| <p><a href="#tut-chapter-servers-with-time">Servers</a> (modeling machines)</p> |
| </li> |
| <li> |
| <p><a href="#tut-chapter-conveyors">Conveyors</a> (modeling conveyor belts)</p> |
| </li> |
| <li> |
| <p><a href="#tut-chapter-simulation-and-experiments">Experiments</a> (performing simulation experiments)</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><em>Visualization</em>: Making an animated graphical display of a system with the |
| Chi simulator.</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#tut-chapter-svg-visualization">SVG visualization</a> (how to attach an SVG visualization)</p> |
| </li> |
| <li> |
| <p><a href="#tut-chapter-svg-example">SVG example</a> (an SVG example)</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-introduction">Introduction</h3> |
| <div class="paragraph"> |
| <p>The topic is modeling of the operation of (manufacturing) systems, e.g. |
| semiconductor factories, assembly and packaging lines, car manufacturing |
| plants, steel foundries, metal processing shops, beer breweries, health care |
| systems, warehouses, order-picking systems. |
| For a proper functioning of these systems, these systems are controlled by |
| operators and electronic devices, e.g. computers.</p> |
| </div> |
| <div class="paragraph"> |
| <p>During the design process, engineers make use of (analytical) mathematical |
| models, e.g. algebra and probability theory, to get answers about the |
| operation of the system. |
| For complex systems, (numerical) mathematical models are used, and computers |
| perform simulation experiments, to analyze the operation of the system. |
| Simulation studies give answers to questions like:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>What is the throughput of the system?</p> |
| </li> |
| <li> |
| <p>What is the effect of set-up time in a machine?</p> |
| </li> |
| <li> |
| <p>How will the batch size of an order influence the flow time of the |
| product-items?</p> |
| </li> |
| <li> |
| <p>What is the effect of more surgeons in a hospital?</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| The operation of a system can be described, e.g. in terms of or operating |
| processes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An example of a system with parallel operating processes is a manufacturing |
| line, with a number of manufacturing machines, where product-items go from |
| machine to machine. |
| A surgery room in a hospital is a system where patients are treated by teams |
| using medical equipment and sterile materials. |
| A biological system can be described by a number of parallel processes, where, |
| e.g. processes transform sugars into water and carbon-dioxide producing |
| energy. |
| In all these examples, processes operate in parallel to complete a task, and |
| to achieve a goal. |
| Concurrency is the dominant aspect in these type of systems, and as a |
| consequence this holds too for their models.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The operating behavior of parallel processes can be described by different |
| formalisms, e.g. automata, Petri-nets or parallel processes. This text uses |
| the programming language Chi, which is an instance of a parallel processes |
| formalism.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A system is abstracted into a model, with cooperating processes, where |
| processes are connected to each other via channels. |
| The channels are used for exchanging material and information. |
| Models of the above mentioned examples consist of a number of concurrent |
| processes connected by channels, denoting the flow of products, patients or |
| personnel.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In Chi, communication takes place in a synchronous manner. |
| This means that communication between a sending process, and a receiving |
| process takes place only when both processes are able to communicate. |
| Processes and channels can dynamically be altered. |
| To model times, like inter-arrival times and server processing times, the |
| language has a notation of time.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The rationale behind the language is that models for the analysis of a system should be</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>formal (exactly one interpretation, every reader attaches the same meaning to the model),</p> |
| </li> |
| <li> |
| <p>easily writable (write the essence of the system in a compact way),</p> |
| </li> |
| <li> |
| <p>easily readable (non-experts should be able to understand the model),</p> |
| </li> |
| <li> |
| <p>and easily extensible (adding more details in one part should not affect other parts).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Verification of the models to investigate the properties of the model should |
| be relatively effortless. (A model has to preserve some properties of the real system |
| otherwise results from the simulation study have no relation with the system |
| being modeled. The language must allow this verification to take place in a |
| simple manner.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Experiments should be performed in an straightforward manner. (Minimizing the |
| effort in doing simulation studies, in particular for large systems, makes the |
| language useful.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Finally, the used models should be usable for the supervisory (logic) control |
| of the systems (simulation studies often provide answers on how to control a |
| system in a better way, these answers should also work for the modeled |
| system).</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-chi-in-a-nutshell">Chi in a nutshell</h4> |
| <div class="paragraph"> |
| <p>During the past decades, the ancestors of Chi have been used with success, |
| for the analysis of a variety of (industrial) systems. |
| Based on this experience, the language Chi has been completely redesigned, |
| keeping the strong points of the previous versions, while making it more |
| powerful for advanced users, and easier to access for non-experts.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Its features are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A system (and its control) is modeled as a collection of parallel running |
| processes, communicating with each other using channels.</p> |
| </li> |
| <li> |
| <p>Processes do not share data with other processes and channels are |
| synchronous (sending and receiving is always done together at the same |
| time), making reasoning about process behavior easier.</p> |
| </li> |
| <li> |
| <p>Processes and channels are dynamic, new processes can be created as needed, |
| and communication channels can be created or rerouted.</p> |
| </li> |
| <li> |
| <p>Variables can have elementary values such as <em>boolean</em>, <em>integer</em> or <em>real</em> |
| numbers, to high level structured collections of data like <em>lists</em>, <em>sets</em> |
| and <em>dictionaries</em> to model the data of the system. If desired, processes |
| and channels can also be part of that data.</p> |
| </li> |
| <li> |
| <p>A small generic set of statements to describe algorithms, assignment, <em>if</em>, |
| <em>while</em>, and <em>for</em> statements. This set is relatively easy to explain to |
| non-experts, allowing them to understand the model, and participate in the |
| discussions.</p> |
| </li> |
| <li> |
| <p>Tutorials and manuals demonstrate use of the language for effective modeling |
| of system processes. More detailed modeling of the processes, or custom |
| tailoring them to the real situation, has no inherent limits.</p> |
| </li> |
| <li> |
| <p>Time and (quasi-) random number generation distributions are available for |
| modeling behavior of the system in time.</p> |
| </li> |
| <li> |
| <p>Likewise, measurements to derive performance indicators of the modeled |
| system are integrated in the model. Tutorials and manuals show basic use. |
| The integration allows for custom solutions to obtain the needed data in the |
| wanted form.</p> |
| </li> |
| <li> |
| <p>Input and output facilities from and to the file system exists to support |
| large simulation experiments.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-exercises">Exercises</h4> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Install the Chi programming environment at your computer.</p> |
| </li> |
| <li> |
| <p>Test your first program.</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>Construct the following program in a project in your workspace:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model M(): |
| writeln("It works!") |
| end</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Compile, and simulate the model as explained in the tool manual (in |
| <a href="#tool-compile-and-simulate">Compile and simulate</a>).</p> |
| </li> |
| <li> |
| <p>Try to explain the result.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>Test a program with model parameters.</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>Construct the following program in the same manner:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model M(string s): |
| write("%s\n") |
| end</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Simulate the model, where you have to set the <em>Model instance</em> text to |
| <code>M("OOPS")</code> in the dialog box of the simulator.</p> |
| </li> |
| <li> |
| <p>Try to explain the result.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-data-types">Data types</h3> |
| <div class="paragraph"> |
| <p>The language is a statically typed language, which means that all variables |
| and values in a model have a single fixed type. |
| All variables must be declared in the program. |
| The declaration of a variable consists of the type, and the name, of the |
| variable. The following fragment shows the declaration of two elementary data |
| types, integer variable <code>i</code> and real variable <code>r</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">... |
| int i; |
| real r; |
| ...</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The ellipsis (<code>...</code>) denotes that non-relevant information is left out from |
| the fragment. The syntax for the declaration of variables is similar to the |
| language <em>C</em>. All declared variables are initialized, variables <code>i</code> and |
| <code>r</code> are both initialized to zero.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An expression, consisting of operators, e.g. plus (<code>+</code>), times (<code>*</code>), and |
| operands, e.g. <code>i</code> and <code>r</code>, is used to calculate a new value. The new |
| value can be assigned to a variable by using an <em>assignment</em> statement. An |
| example with four variables, two expressions and assignment statements is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">... |
| int i = 2, j; |
| real r = 1.50, s; |
| |
| j = 2 * i + 1; |
| s = r / 2; |
| ...</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The value of variable <code>j</code> becomes <code>5</code>, and the value of <code>s</code> becomes |
| <code>0.75</code>. |
| Statements are described in <a href="#tut-chapter-statements">Statements</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Data types are categorized in five different groups: <em>elementary</em> types, |
| <em>tuple</em> types, <em>container</em> types, <em>custom</em> types, and <em>distribution</em> types. |
| Elementary types are types such as Boolean, integer, real or string. |
| Tuple types contain at least one element, where each element can be of |
| different type. In other languages tuple types are called records (Pascal) or |
| structures (C). |
| Variables with a container type (a list, set, or dictionary) contain many |
| elements, where each element is of the same type. |
| Custom types are created by the user to enhance the readability of the model. |
| Distributions types are types used for the generation of distributions from |
| (pseudo-) random numbers. |
| They are covered in <a href="#tut-chapter-stochastic-behavior">Modeling stochastic behavior</a>.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-elementary-types">Elementary types</h4> |
| <div class="paragraph"> |
| <p>The elementary data types are Booleans, numbers and strings. |
| The language provides the elementary data types:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>bool</code> for booleans, with values <code>false</code> and <code>true</code>.</p> |
| </li> |
| <li> |
| <p><code>enum</code> for enumeration types, for example |
| <code>enum FlagColors = {red, white, blue}</code>,</p> |
| </li> |
| <li> |
| <p><code>int</code> for integers, e.g. <code>-7</code>, <code>20</code>, <code>0</code>.</p> |
| </li> |
| <li> |
| <p><code>real</code> for reals, e.g. <code>3.14</code>, <code>7.0e9</code>.</p> |
| </li> |
| <li> |
| <p><code>string</code> for text strings, e.g. <code>"Hello"</code>, <code>"world"</code>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-booleans">Booleans</h5> |
| <div class="paragraph"> |
| <p>A boolean value has two possible values, the truth values. |
| These truth values are <code>false</code> and <code>true</code>. |
| The value <code>false</code> means that a property is not fulfilled. |
| A value <code>true</code> means the presence of a property. |
| Boolean variables are initialized with the value <code>false</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In mathematics, various symbols are used for unary and binary boolean |
| operators. |
| These operators are also present in Chi. |
| The most commonly used boolean operators are <code>not</code>, <code>and</code>, and <code>or</code>. |
| The names of the operators, the symbols in mathematics and the symbols in the |
| language are presented in <a href="#tut-table-boolsymbols">Table with boolean symbols</a>.</p> |
| </div> |
| <table id="tut-table-boolsymbols" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 1. Table with boolean symbols</caption> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3334%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Operator</th> |
| <th class="tableblock halign-left valign-top">Math</th> |
| <th class="tableblock halign-left valign-top">Chi</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">boolean not</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">¬</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>not</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">boolean and</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">∧</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>and</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">boolean or</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">∨</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>or</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Examples of boolean expressions are the following. |
| If <code>z</code> equals <code>true</code>, then the value of <code>(not z)</code> equals <code>false</code>. |
| If <code>s</code> equals <code>false</code>, and <code>t</code> equals <code>true</code>, then the value of the |
| expression <code>(s or t)</code> becomes <code>true</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| The result of the unary <code>not</code>, the binary |
| <code>and</code> and <code>or</code> operators, for two variables <code>p</code> and <code>q</code> is given in |
| <a href="#tut-table-truthtable">Truth table for <code>not</code>, <code>and</code> and <code>or</code> operators</a>.</p> |
| </div> |
| <table id="tut-table-truthtable" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 2. Truth table for <code>not</code>, <code>and</code> and <code>or</code> operators</caption> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top"><code>p</code></th> |
| <th class="tableblock halign-left valign-top"><code>q</code></th> |
| <th class="tableblock halign-left valign-top"><code>not p</code></th> |
| <th class="tableblock halign-left valign-top"><code>p and q</code></th> |
| <th class="tableblock halign-left valign-top"><code>p or q</code></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td> |
| <td class="tableblock halign-left valign-top"></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td> |
| <td class="tableblock halign-left valign-top"></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>If <code>p = true</code> and <code>q = false</code>, we find for <code>p or q</code> the value <code>true</code> |
| (third line in <a href="#tut-table-truthtable">Truth table for <code>not</code>, <code>and</code> and <code>or</code> operators</a>).</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-enumerations">Enumerations</h5> |
| <div class="paragraph"> |
| <p>Often there are several variants of entities, like types of products, |
| available resources, available machine types, and so on.</p> |
| </div> |
| <div class="paragraph"> |
| <p>One way of coding them is give each a unique number, which results in code |
| with a lot of small numbers that are not actually numbers, but refer to one |
| variant.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Another way is to give each variant a name (which often already exists), and |
| use those names instead.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, to model a traffic light:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">enum TrafficColor = {RED, ORANGE, GREEN}; |
| |
| TrafficColor light = RED;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>enum TrafficColor</code> line lists the available traffic colors. With this |
| definition, a new type <code>TrafficColor</code> is created, which you can use like any |
| other type. The line <code>TrafficColor light = RED;</code> creates a new variable |
| called <code>light</code> and initializes it to the value <code>RED</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-numbers">Numbers</h5> |
| <div class="paragraph"> |
| <p>In the language, two types of numbers are available: integer numbers and real |
| numbers. Integer numbers are whole numbers, denoted by type <code>int</code> e.g. |
| <code>3</code>, <code>-10</code>, <code>0</code>. Real numbers are used to present numbers with a |
| fraction, denoted by type <code>real</code>. E.g. <code>3.14</code>, <code>2.7e6</code> (the scientific |
| notation for 2.7 million). Note that real numbers <em>must</em> either have a |
| fraction or use the scientific notation, to let the computer know you mean a |
| real number (instead of an integer number). Integer variables are initialized |
| with <code>0</code>. Real variables are initialized with <code>0.0</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| For numbers, the normal arithmetic operators are defined. |
| Expressions can be constructed with these operators. |
| The arithmetic operators for numbers are listed in <a href="#tut-table-aritoper">The arithmetic operators</a>.</p> |
| </div> |
| <table id="tut-table-aritoper" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 3. The arithmetic operators</caption> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3334%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Operator name</th> |
| <th class="tableblock halign-left valign-top">Notation</th> |
| <th class="tableblock halign-left valign-top">Comment</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">unary plus</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+ x</code></p></td> |
| <td class="tableblock halign-left valign-top"></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">unary minus</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>- x</code></p></td> |
| <td class="tableblock halign-left valign-top"></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">raising to the power</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x ^ y</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Always a <code>real</code> result.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">multiplication</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x * y</code></p></td> |
| <td class="tableblock halign-left valign-top"></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real division</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x / y</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Always a <code>real</code> result.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">division</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x div y</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">For <code>int</code> only.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">modulo</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x mod y</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">For <code>int</code> only.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">addition</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x + y</code></p></td> |
| <td class="tableblock halign-left valign-top"></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">subtraction</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x - y</code></p></td> |
| <td class="tableblock halign-left valign-top"></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The priority of the operators is given from high to low. |
| The unary operators have the strongest binding, and the <code>+</code> and <code>-</code> the |
| weakest binding. So, <code>-3^2</code> is read as <code>(-3)^2</code> and not <code>-(3^2)</code>, |
| because the priority rules say that the unary operator binds stronger than the |
| raising to the power operator. Binding in expressions can be changed by the |
| use of parentheses.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The integer division, denoted by <code>div</code>, gives the biggest integral number |
| smaller or equal to <code>x / y</code>. The integer remainder, denoted by <code>mod</code>, |
| gives the remainder after division <code>x - y * (x div y)</code>. So, <code>7 div 3</code> |
| gives <code>2</code> and <code>-7 div 3</code> gives <code>-3</code>, <code>7 mod 3</code> gives <code>1</code> and <code>-7 |
| mod 3</code> gives <code>2</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The rule for the result of an operation is as follows. The real division and |
| raising to the power operations always produce a value of type <code>real</code>. |
| Otherwise, if both operands (thus <code>x</code> and <code>y</code>) are of type <code>int</code>, the |
| result of the operation is of type <code>int</code>. If one of the operands is of type |
| <code>real</code>, the result of the operation is of type <code>real</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| Conversion functions exist to convert a real into an integer. |
| The function <code>ceil</code> converts a real to the |
| smallest integer value not less than the real, the |
| function <code>floor</code> gives the biggest |
| integer value smaller than or equal to the real, and the |
| function <code>round</code> rounds the real to the nearest integer |
| value (or up, if it ends on <code>.5</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| Between two numbers a relational operation can be defined. |
| If for example variable <code>x</code> is smaller than variable <code>y</code>, the expression |
| <code>x < y</code> equals <code>true</code>. The relational operators, with well-known |
| semantics, are listed in <a href="#tut-table-reloper">The relational operators</a>.</p> |
| </div> |
| <table id="tut-table-reloper" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 4. The relational operators</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Name</th> |
| <th class="tableblock halign-left valign-top">Operator</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">less than</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x < y</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">at most</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x <= y</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">equals</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x == y</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">differs from</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x != y</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">at least</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x >= y</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">greater than</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x > y</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-strings">Strings</h5> |
| <div class="paragraph"> |
| <p>Variables of type string contains a sequence of characters. |
| A string is enclosed by double quotes. |
| An example is <code>"Manufacturing line"</code>. |
| Strings can be composed from different strings. |
| The concatenation operator (<code>+</code>) adds one string to another, for |
| example <code>"One" + " " + "string"</code> gives <code>"One string"</code>. |
| Moreover the relational operators (<code><</code>, <code><=</code>, <code>==</code>, <code>!=</code> <code>>=</code>, |
| and <code>></code>) can be used to compare strings alphabetically, |
| e.g. <code>"a" < "aa" < "ab" < "b"</code>. |
| String variables are initialized with the empty string <code>""</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-tuple-types">Tuple types</h4> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| Tuple types are used for keeping several (related) kinds of data together in |
| one variable, e.g. the name and the age of a person. |
| A tuple variable consists of a number of fields |
| inside the tuple, where the types of these fields may be different. |
| The number of fields is fixed. One operator, the projection operator |
| denoted by a dot (<code>.</code>), is defined for tuples. It selects a field in the |
| tuple for reading or assigning.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-notation">Notation</h5> |
| <div class="paragraph"> |
| <p>A type <code>person</code> is a tuple with two fields, a 'name' field of type |
| <code>string</code>, and an 'age' field of type <code>int</code>, is denoted by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type person = tuple(string name; int age)</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-operator">Operator</h5> |
| <div class="paragraph"> |
| <p>A projection operator fetches a field from a tuple. |
| We define two persons:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">person eva = ("eva" , 29), |
| adam = ("adam", 27);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>And we can speak of <code>eva.name</code> and <code>adam.age</code>, denoting the name of |
| <code>eva</code> (<code>"eva"</code>) and the age of <code>adam</code> (<code>27</code>). |
| We can assign a field in a tuple to another variable:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">ae = eva.age; |
| eva.age = eva.age + 1;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This means that the age of <code>eva</code> is assigned tot variable <code>ae</code>, and the |
| new age of <code>eva</code> becomes <code>eva.age + 1</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>By using a multi assignment statement all values of a tuple can be copied into |
| separate variables:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">string name; |
| int age; |
| |
| name, age = eva</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This assignment copies the name of <code>eva</code> into variable <code>name</code> of type |
| <code>string</code> and her age into <code>age</code> of type <code>int</code>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-container-types">Container types</h4> |
| <div class="paragraph"> |
| <p>Lists, sets and dictionaries are container types. |
| A variable of this type contains zero or more identical elements. |
| Elements can be added or removed in variables of these types. |
| Variables of a container type are initialized with zero elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Sets are unordered collections of elements. Each element value either exists |
| in a set, or it does not exist in a set. |
| Each element value is unique, duplicate elements are silently discarded. |
| A list is an ordered collection of elements, that is, there is a first and a last |
| element (in a non-empty list). A list also allows duplicate element values. |
| Dictionaries are unordered and have no duplicate value, just like sets, but |
| you can associate a value (of a different type) with each element value.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| Lists are denoted by a pair of (square) brackets. |
| For example, <code>[7, 8, 3]</code> is a list with three integer elements. Since a list |
| is ordered, <code>[8, 7, 3]</code> is a different list. |
| With empty lists, the computer has to know the type of the elements, e.g. |
| <code><int>[]</code> is an empty list with integer elements. |
| The prefix <code><int></code> is required in this case.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| Sets are denoted by a |
| pair of (curly) braces, e.g. <code>{7, 8, 3}</code> is a set with three integer |
| elements. |
| As with lists, for an empty set a prefix is required, for example |
| <code><string>{}</code> is an empty set with strings. |
| A set is an unordered collection of elements. |
| The set <code>{7, 8, 3}</code> is a set with three integer numbers. Since order of |
| the elements does not matter, the same set can also be written as |
| <code>{8, 3, 7}</code> (or in one of the four other orders). |
| In addition, each element in a set is unique, the set <code>{8, 7, 8, 3}</code> is |
| equal to the set <code>{7, 8, 3}</code>. |
| For readability, elements in a set are normally written in increasing order, |
| for example <code>{3, 7, 8}</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| Dictionaries are denoted by a pair of (curly) braces, whereby an element value |
| consists of two parts, a 'key' and a 'value' part. |
| The two parts separated by a colon (<code>:</code>). |
| For example <code>{"jim" : 32, "john" : 34}</code> is a dictionary with two elements. |
| The first element has <code>"jim"</code> as key part and <code>32</code> as value part, the |
| second element has <code>"john"</code> as key part and <code>34</code> as value part. |
| The key parts of the elements work like a set, they are unordered and |
| duplicates are silently discarded. A value part is associated with its key |
| part. |
| In this example, the key part is the name of a person, while the value part |
| keeps the age of that person. |
| Empty dictionaries are written with a type prefix just like lists and sets, |
| e.g. <code><string:int>{}</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Container types have some built-in functions in common (Functions are |
| described in <a href="#tut-chapter-functions">Functions</a>):</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The function <code>size</code> gives the number of elements in a variable, for |
| example <code>size([7, 8, 3])</code> yields 3; <code>size({7, 8})</code> results in 2; |
| <code>size({"jim":32})</code> gives 1 (an element consists of two parts).</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The function <code>empty</code> yields <code>true</code> if there are no elements in variable. |
| E.g. <code>empty(<string>{})</code> with an empty set of type <code>string</code> is true. |
| (Here the type <code>string</code> is needed to determine the type of the elements |
| of the empty set.)</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The function <code>pop</code> extracts a value from the provided collection and |
| returns a tuple with that value, and the collection minus the value.</p> |
| <div class="paragraph"> |
| <p> |
| |
| For lists, the first element of the list |
| becomes the first field of the tuple. The second field of the tuple becomes |
| the list minus the first list element. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">pop([7, 8, 3]) -> (7, [8, 3])</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>-></code> above denotes 'yields'. |
| The value of the list is split into a 'head' (the first element) and a |
| 'tail' (the remaining elements).</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| For sets, the first field of the tuple becomes the |
| value of an arbitrary element from the set. The second field of the tuple |
| becomes the original set minus the arbitrary element. |
| For example, a <code>pop</code> on the set <code>{8, 7, 3}</code> has three possible answers:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">pop({8, 7, 3}) -> (7, {3, 8}) or |
| pop({8, 7, 3}) -> (3, {7, 8}) or |
| pop({8, 7, 3}) -> (8, {3, 7})</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| Performing a <code>pop</code> on a dictionary |
| follows the same pattern as above, except 'a value from the collection' are |
| actually a key item and a value item. In this case, the <code>pop</code> function |
| gives a three-tuple as result. The first field of the tuple becomes the key |
| of the extracted element, the second field of the tuple becomes the value of |
| the element, and the third field of the tuple contains the dictionary except |
| for the extracted element. Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">pop({"a" : 32, "b" : 34}) -> ("a", 32, {"b" : 34}) or |
| pop({"a" : 32, "b" : 34}) -> ("b", 34, {"a" : 32})</code></pre> |
| </div> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-lists">Lists</h5> |
| <div class="paragraph"> |
| <p>A list is an ordered collection of elements of the same type. |
| They are useful to model anything where duplicate values may occur or where |
| order of the values is significant. Examples are waiting customers in a shop, |
| process steps in a recipe, or products stored in a warehouse. Various |
| operations are defined for lists.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An element can be fetched by <em>indexing</em>. |
| This indexing operation does not change the content of the variable. |
| The first element of a list has index <code>0</code>. |
| The last element of a list has index <code>size(xs) - 1</code>. |
| A negative index, say <code>m</code>, starts from the back of the list, or |
| equivalently, at offset <code>size(xs) + m</code> from the front. |
| You cannot index non-existing elements. |
| Some examples, with <code>xs = [7, 8, 3, 5, 9]</code> are:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">xs[0] -> 7 |
| xs[3] -> 5 |
| xs[5] -> ERROR (there is no element at position 5) |
| xs[-1] -> xs[5 - 1] -> xs[4] -> 9 |
| xs[-2] -> xs[5 - 2] -> xs[3] -> 5</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| In <a href="#tut-figure-list-with-indices">A list with indices</a> the list with indices is visualized. |
| A common name for the first element of a list |
| (i.e., <code>x[0]</code>) is the <em>head</em> of a list. |
| Similarly, the last element of a list |
| (<code>xs[-1]</code>) is also known as <em>head right</em>.</p> |
| </div> |
| <div id="tut-figure-list-with-indices" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/list_with_indices.png" alt="list with indices"> |
| </div> |
| <div class="title">Figure 1. A list with indices</div> |
| </div> |
| <div class="paragraph"> |
| <p>A part of a list can be fetched by <em>slicing</em>. |
| The slicing operation does not change the content of the list, it copies a |
| contiguous sequence of a list. |
| The result of a slice operation is again a list, even if the slice contains |
| just one element.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Slicing is denoted by <code>xs[i:j]</code>. |
| The slice of <code>xs[i:j]</code> is defined as the sequence of elements with index |
| <code>k</code> such that <code>i <= k < j</code>. Note the upper bound <code>j</code> is noninclusive. |
| If <code>i</code> is omitted use <code>0</code>. |
| If <code>j</code> is omitted use <code>size(xs)</code>. If <code>i</code> is greater than or equal to |
| <code>j</code>, the slice is empty. If <code>i</code> or <code>j</code> is negative, the index is |
| relative to the end of the list: <code>size(xs) + i</code> or <code>size(xs) + j</code> is |
| substituted. Some examples with <code>xs = [7, 8, 3, 5, 9]</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">xs[1:3] -> [8, 3] |
| xs[:2] -> [7, 8] |
| xs[1:] -> [8, 3, 5, 9] |
| xs[:-1] -> [7, 8, 3, 5] |
| xs[:-3] -> [7, 8]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| The list of all but the first elements (<code>xs[1:]</code>) is often called <em>tail</em> |
| and <code>xs[:-1]</code> is also known as <em>tail right</em>. |
| In <a href="#tut-figure-list-with-slices">A list with indices and slices</a> the slicing operator is visualized.</p> |
| </div> |
| <div id="tut-figure-list-with-slices" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/list_with_slices.png" alt="list with slices"> |
| </div> |
| <div class="title">Figure 2. A list with indices and slices</div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| Two lists can be 'glued' together into a new list. |
| The glue-ing or concatenation of a list with elements <code>7</code>, <code>8</code>, <code>3</code> and a |
| list with elements <code>5</code>, and <code>9</code> is denoted by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">[7, 8, 3] + [5, 9] -> [7, 8, 3, 5, 9]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>An element can be added to a list at the rear or at the front. |
| The action is performed by transforming the element into a list and then |
| concatenate these two lists. In the next example the value <code>5</code> is added to |
| the rear, respectively the front, of a list:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">[7, 8, 3] + [5] -> [7, 8, 3, 5] |
| [5] + [7, 8, 3] -> [5, 7, 8, 3]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| Elements also can be removed from a list. |
| The <code>del</code> function removes by position, e.g. <code>del(xs, 2)</code> returns the list |
| <code>xs</code> without its third element (since positions start at index 0). |
| Removing a value by value can be performed by the subtraction operator <code>-</code>. |
| For instance, consider the following subtractions:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">[1, 4, 2, 4, 5] - [2] -> [1, 4, 4, 5] |
| [1, 4, 2, 4, 5] - [4] -> [1, 2, 4, 5] |
| [1, 4, 2, 4, 5] - [8] -> [1, 4, 2, 4, 5]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Every element in the list at the right is searched in the list at the left, |
| and if found, the <em>first</em> occurrence is removed. |
| In the first example, element <code>2</code> is removed. In the second example, only |
| the first value <code>4</code> is removed and the second value (at position 3) is kept. |
| In the third example, nothing is removed, since value <code>8</code> is not in the list |
| at the left.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When the list at the right is longer than one element, the operation is repeated. |
| For example, consider <code>xs - ys</code>, whereby <code>xs = [1, 2, 3, 4, 5]</code> and |
| <code>ys = [6, 4, 2, 3]</code>. The result is computed as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi"> [1, 2, 3, 4, 5] - [6, 4, 2, 3] |
| -> ([1, 2, 3, 4, 5] - [6]) - [4, 2, 3] |
| -> [1, 2, 3, 4, 5] - [4, 2, 3] |
| -> ([1, 2, 3, 4, 5] - [4]) - [2, 3] |
| -> [1, 2, 3, 5] - [2, 3] |
| -> ([1, 2, 3, 5] - [2]) - [3] |
| -> [1, 3, 5] - [3] |
| -> [1,5]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Lists have two relational operators, the equal operator and the not-equal operator. |
| The equal operator (<code>==</code>) compares two lists. If the lists have the same |
| number of elements and all the elements are pair-wise the same, the result of |
| the operation is <code>true</code>, otherwise <code>false</code>. |
| The not-equal operator (<code>!=</code>) does the same check, but with an opposite result. |
| Some examples, with <code>xs = [7, 8, 3]</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">xs == [7, 8, 3] -> true |
| xs == [7, 7, 7] -> false</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The membership operator (<code>in</code>) checks if an element is in a list. |
| Some examples, with <code>xs = [7, 8, 3]</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">6 in xs -> false |
| 7 in xs -> true |
| 8 in xs -> true</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-initialization">Initialization</h5> |
| <div class="paragraph"> |
| <p>A list variable is initialized with a list with zero elements, for example in:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list int xs;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The initial value of <code>xs</code> equals <code><int>[]</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A list can be initialized with a number, denoting the number of elements in the list:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list(2) int ys</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This declaration creates a list with <code>2</code> elements, whereby each element of |
| type <code>int</code> is initialized. |
| The initial value of <code>ys</code> equals <code>[0, 0]</code>. |
| Another example with a list of lists:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list(4) list(2) int zm</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This declaration initializes variable <code>zm</code> with the value |
| <code>[ [0, 0], [0, 0], [0, 0], [0, 0] ]</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-sets">Sets</h5> |
| <div class="paragraph"> |
| <p>Set operators for union, intersection and difference are present. |
| <a href="#tut-table-set-operations">Table with set operations</a> gives the name, the mathematical notation and |
| the notation in the Chi language.</p> |
| </div> |
| <table id="tut-table-set-operations" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 5. Table with set operations</caption> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3334%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Operator</th> |
| <th class="tableblock halign-left valign-top">Math</th> |
| <th class="tableblock halign-left valign-top">Chi</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set union</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">∪</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set intersection</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">∩</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>*</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set difference</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">∖</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The union of two sets merges the values of both sets into one, that is, the |
| result is the collection of values that appear in at least one of the |
| arguments of the union operation. Some examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">{3, 7, 8} + {5, 9} -> {3, 5, 7, 8, 9}</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>All permutations with the elements <code>3</code>, <code>5</code>, <code>7</code>, <code>8</code> and <code>9</code> are |
| correct (sets have no order, all permutations are equivalent). To keep sets |
| readable the elements are sorted in increasing order in this tutorial.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Values that occur in both arguments, appear only one time in the result (sets |
| silently discard duplicate elements). For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">{3, 7, 8} + {7, 9} -> {3, 7, 8, 9}</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The intersection of two sets gives a set with the common elements, that is, |
| all values that occur in <em>both</em> arguments. |
| Some examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">{3, 7, 8} * {5, 9} -> <int>{} # no common element |
| {3, 7, 8} * {7, 9} -> {7} # only 7 in common</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Set difference works much like subtraction on lists, except elements occur at |
| most one time (and have no order). The operation computes 'remaining |
| elements'. The result is a new set containing all values from the first set |
| which are not in the second set. |
| Some examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">{3, 7, 8} - {5, 9} -> {3, 7, 8} |
| {3, 7, 8} - {7, 9} -> {3, 9}</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The membership operator <code>in</code> works on sets too:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">3 in {3, 7, 8} -> true |
| 9 in {3, 7, 8} -> false</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-dictionaries">Dictionaries</h5> |
| <div class="paragraph"> |
| <p>Elements of dictionaries are stored according to a key, while lists elements |
| are ordered by a (relative) position, and set elements are not ordered at all. |
| A dictionary can grow and shrink by adding or removing elements respectively, |
| like a list or a set. |
| An element of a dictionary is accessed by the key of the element.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The dictionary variable <code>d</code> of type <code>dict(string : int)</code> is given by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">dict (string : int) d = |
| {"jim" : 32, |
| "john" : 34, |
| "adam" : 25}</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Retrieving values of the dictionary by using the key:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">d["john"] -> 34 |
| d["adam"] -> 25</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Using a non-existing key to retrieve a value results in a error message.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A new value can be assigned to the variable by selecting the key of the element:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">d["john"] = 35</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This assignment changes the value of the <code>"john"</code> item to <code>35</code>. |
| The assignment can also be used to add new items:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">d["lisa"] = 19</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Membership testing of keys in dictionaries can be done with the <code>in</code> operator:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">"jim" in d -> true |
| "peter" in d -> false</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Merging two dictionaries is done by adding them together. The value of the |
| second dictionary is used when a key exists in both dictionaries:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">{1 : 1, 2 : 2} + {1 : 5, 3 : 3} -> {1 : 5, 2 : 2, 3 : 3}</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The left dictionary is copied, and updated with each item of the right dictionary.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Removing elements can be done with subtraction, based on key values. Lists and |
| sets can also be used to denote which keys should be removed. |
| A few examples for <code>p</code> is <code>{1 : 1, 2 : 2}</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">p - {1 : 3, 5 : 5} -> {2 : 2} |
| p - {1, 7} -> {2 : 2} |
| p - [2, 8] -> {1 : 1}</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Subtracting keys that do not exist in the left dictionary is allowed and has |
| no effect.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-custom-types">Custom types</h4> |
| <div class="paragraph"> |
| <p>To structure data the language allows the creation of new types. The |
| definition can only be done at global level, that is, outside any <code>proc</code>, |
| <code>func</code>, <code>model</code>, or <code>xper</code> definition.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Types can be used as alias for elementary data types to increase readability, |
| for example a variable of type <code>item</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type item = real;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Variables of type <code>item</code> are, e.g.:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">item box, product; |
| |
| box = 4.0; product = 120.5;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This definition creates the possibility to speak about an item.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Types also can be used to make combinations of other data types, e.g. a |
| recipe:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type step = tuple(string name; real process_time), |
| recipe = tuple(int id; list step steps);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A type <code>step</code> is defined by a <code>tuple</code> with two fields, a field with |
| <code>name</code> of type <code>string</code>, denoting the name of the step, and a field with |
| <code>process_time</code> of type <code>real</code>, denoting the duration of the (processing) |
| step. |
| The <code>step</code> definition is used in the type <code>recipe</code>. |
| Type <code>recipe</code> is defined by a <code>tuple</code> with two fields, an <code>id</code> of type |
| <code>int</code>, denoting the identification number, and a field <code>steps</code> of type |
| <code>list step</code>, denoting a list of single steps. |
| Variables of type recipe are, e.g.:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">recipe plate, bread; |
| plate = (34, [("s", 10.8), ("w", 13.7), ("s", 25.6)]); |
| bread = (90, [("flour", 16.3), ("yeast", 6.9)]);</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-exercises-2">Exercises</h4> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Exercises for integer numbers. |
| What is the result of the following expressions:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">-5 ^ 3 |
| -5 * 3 |
| 5 mod 3</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Exercises for tuples. |
| Given are tuple type <code>box</code> and variable <code>x</code> of type <code>box</code>:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type box = tuple(string name; real weight); |
| box x = ("White", 12.5);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>What is the result of the following expressions:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">x.name |
| x.real |
| x</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Exercises for lists. |
| Given is the list <code>xs = [0,1,2,3,4,5,6]</code>. |
| Determine the outcome of:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">xs[0] |
| xs[1:] |
| size(xs) |
| xs + [3] |
| [4,5] + xs |
| xs - [2,2,3] |
| xs - xs[2:] |
| xs[0] + (xs[1:])[0]</code></pre> |
| </div> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-statements">Statements</h3> |
| <div class="paragraph"> |
| <p>There are several kinds of statements, such as assignment statements, choice |
| statements (select and if statements), and loop statements (while and for |
| statements).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Semicolons are required after statements, except at the end of a sequence |
| (that is, just before an <code>end</code> keyword and after the last statement) or |
| after the keyword <code>end</code>. In this text semicolons are omitted before <code>end</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-the-assignment-statement">The assignment statement</h4> |
| <div class="paragraph"> |
| <p>An <em>assignment</em> statement is used to assign values to variables. |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">y = x + 10</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This assignment consists of a name of the variable (<code>y</code>), an assignment |
| symbol (<code>=</code>), and an expression (<code>x + 10</code>) yielding a value. For example, |
| when <code>x</code> is <code>2</code>, the value of the expression is <code>12</code>. |
| Execution of this statement copies the value to the <code>y</code> variable, |
| immediately after executing the assignment, the value of the <code>y</code> variable is |
| <code>10</code> larger than the value of the <code>x</code> variable at this point of the |
| program. |
| The value of the <code>y</code> variable will not change until the next assignment to |
| <code>y</code>, for example, performing the assignment <code>x = 7</code> has no effect on the |
| value of the <code>y</code> variable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An example with two assignment statements:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">i = 2; |
| j = j + 1</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The values of <code>i</code> becomes 2, and the value of <code>j</code> is incremented. |
| Independent assignments can also be combined in a multi-assignment, for |
| example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">i, j = 2, j + 1</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The result is the same as the above described example, the first value goes |
| into the first variable, the second value into the second variable, etc.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In an assignment statement, first all expression values are computed before |
| any assignment is actually done. In the following example the values of <code>x</code> |
| and <code>y</code> are swapped:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">x, y = y, x;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-the-if-statement">The <code>if</code> statement</h4> |
| <div class="paragraph"> |
| <p>The <em>if</em> statement is used to express decisions. |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">if x < 0: |
| y = -x |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If the value of <code>x</code> is negative, assign its negated value to <code>y</code>. |
| Otherwise, do nothing (skip the <code>y = -x</code> assignment statement).</p> |
| </div> |
| <div class="paragraph"> |
| <p>To perform a different statement when the decision fails, an <code>if</code>-statement |
| with an <code>else</code> alternative can be used. It has the following form. |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">if a > 0: |
| c = a |
| else: |
| c = b |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If <code>a</code> is positive, variable <code>c</code> gets the value of <code>a</code>, otherwise it |
| gets the value of <code>b</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In some cases more alternatives must be tested. One way of writing it is by |
| nesting an <code>if</code>-statement in the <code>else</code> alternative of the previous |
| <code>if</code>-statement, like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">if i < 0: |
| writeln("i < 0") |
| else: |
| if i == 0: |
| writeln("i = 0") |
| else: |
| if i > 0 and i < 10: |
| writeln("0 < i < 10") |
| else: |
| # i must be greater or equal 10 |
| writeln("i >= 10") |
| end |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This tests <code>i < 0</code>. If it fails, the <code>else</code> is chosen, which contains a |
| second <code>if</code>-statement with the <code>i == 0</code> test. If that test also fails, the |
| third condition <code>i > 0 and i < 10</code> is tested, and one of the <code>writeln</code> |
| statements is chosen.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The above can be written more compactly by combining an <code>else</code>-part and the |
| <code>if</code>-statement that follows, into an <code>elif</code> part. Each <code>elif</code> part |
| consists of a boolean expression, and a statement list. Using <code>elif</code> parts |
| results in:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">if i < 0: |
| writeln("i < 0") |
| elif i == 0: |
| writeln("i = 0") |
| elif i > 0 and i < 10: |
| writeln("0 < i < 10") |
| else: |
| # i must be greater or equal 10 |
| writeln("i >= 10") |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Each alternative starts at the same column, instead of having increasing |
| indentation. |
| The execution of this combined statement is still the same, an alternative is |
| only tested when the conditions of all previous alternatives fail.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| Note that the line <code># i must be greater or equal 10</code> is a comment to clarify |
| when the alternative is chosen. It is not executed by the simulator. You can |
| write comments either at a line by itself like above, or behind program code. |
| It is often useful to clarify the meaning of variables, give a more detailed |
| explanation of parameters, or add a line of text describing what the purpose |
| of a block of code is from a birds-eye view.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-the-while-statement">The <code>while</code> statement</h4> |
| <div class="paragraph"> |
| <p>The <em>while</em> statement is used for repetitive execution of the same statements, |
| a so-called <em>loop</em>. A fragment that calculates the sum of <code>10</code> integers, |
| <code>10, 9, 8, ..., 3, 2, 1</code>, is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">int i = 10, sum; |
| |
| while i > 0: |
| sum = sum + i; i = i - 1 |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Each iteration of a <code>while</code> statement starts with evaluating its condition |
| (<code>i > 0</code> above). When it holds, the statements inside the while (the |
| <code>sum = sum + i; i = i - 1</code> assignments) are executed (which adds <code>i</code> to the sum |
| and decrements <code>i</code>). At the end of the statements, the <code>while</code> is executed |
| again by evaluating the condition again. If it still holds, the next iteration |
| of the loop starts by executing the assignment statements again, etc. |
| When the condition fails (<code>i</code> is equal to <code>0</code>), the <code>while</code> statement |
| ends, and execution continues with the statement following <code>end</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A fragment with an infinite loop is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">while true: |
| i = i + 1; |
| ... |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The condition in this fragments always holds, resulting in <code>i</code> getting |
| incremented 'forever'. Such loops are very useful to model things you switch |
| on but never off, e.g. processes in a factory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A fragment to calculate <code>z = x ^ y</code>, where <code>z</code> and <code>x</code> are of type |
| <code>real</code>, and <code>y</code> is of type <code>integer</code> with a non-negative value, showing |
| the use of two <code>while</code> loops, is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">real x; int y; real z = 1; |
| |
| while y > 0: |
| while y mod 2 == 0: |
| y = y div 2; x = x * x |
| end; |
| y = y - 1; z = x * z |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A fragment to calculate the greatest common divisor (GCD) of two integer |
| numbers <code>j</code> and <code>k</code>, showing the use of <code>if</code> and <code>while</code> statements, |
| is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">while j != k: |
| if j > k: |
| j = j - k |
| else: |
| k = k - j |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The symbol <code>!=</code> stands for 'differs from' ('not equal').</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-for-statement">The <code>for</code> statement</h4> |
| <div class="paragraph"> |
| <p>The while statement is useful for looping until a condition fails. The <em>for</em> |
| statement is used for iterating over a collection of values. A fragment with |
| the calculation of the sum of <code>10</code> integers:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">int sum; |
| |
| for i in range(1, 11): |
| sum = sum + i |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| The result of the expression <code>range(1, 11)</code> |
| is a list whose items are consecutive integers from <code>1</code> (included) |
| up to <code>11</code> (excluded): <code>[1, 2, 3, ..., 9, 10]</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following example illustrates the use of the for statement in relation |
| with container-type variables. Another way of calculating the sum of a list of |
| integer numbers:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list int xs = [1, 2, 3, 5, 7, 11, 13]; |
| int sum; |
| |
| for x in xs: |
| sum = sum + x |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This statement iterates over the elements of list <code>xs</code>. |
| This is particularly useful when the value of <code>xs</code> may change before the |
| <code>for</code> statement.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-notes">Notes</h4> |
| <div class="paragraph"> |
| <p>In this chapter the most used statements are described. Below are a few other |
| statements that may be useful some times:</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| . Inside loop statements, the <em>break</em> and <em>continue</em> statements are allowed. |
| The <code>break</code> statements allows 'breaking |
| out of a loop', that is, abort a while or a for statement. |
| The <code>continue</code> statement aborts |
| execution of the statements in a loop. |
| It 'jumps' to the start of the next iteration.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| . A rarely used statement is the <code>pass</code> statement. |
| It’s like an <code>x = x</code> assignment statement, but more clearly |
| expresses 'nothing is done here'.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-exercises-3">Exercises</h4> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Study the Chi specification below and explain why, though it works, it is |
| not an elegant way of modeling the selection. |
| Make a suggestion for a shorter, more elegant version of:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model M(): |
| int i = 3; |
| |
| if (i < 0) == true: |
| write("%d is a negative number\n", i); |
| elif (i <= 0) == false: |
| write("%d is a positive number\n", i); |
| end |
| end</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Construct a list with the squares of the integers 1 to 10.</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>using a <code>for</code> statement, and</p> |
| </li> |
| <li> |
| <p>using a <code>while</code> statement.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>Write a program that</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>Makes a list with the first 50 prime numbers.</p> |
| </li> |
| <li> |
| <p>Extend the program with computing the sum of the first 7 prime numbers.</p> |
| </li> |
| <li> |
| <p>Extend the program with computing the sum of the last 11 prime numbers.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-functions">Functions</h3> |
| <div class="paragraph"> |
| <p>In a model, computations must be performed to process the information that is |
| sent around. |
| Short and simple calculations are written as assignments between the other |
| statements, but for longer computations or computations that are needed at |
| several places in the model, a more encapsulated environment is useful, a |
| <em>function</em>. |
| In addition, the language comes with a number of built-in functions, such as |
| <code>size</code> or <code>empty</code> on container types. |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">func real mean(list int xs): |
| int sum; |
| |
| for x in xs: |
| sum = sum + x |
| end; |
| return sum / size(xs) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>func</code> keyword indicates it is a function. The name of the function is |
| just before the opening parenthesis, in this example <code>mean</code>. Between the |
| parentheses, the input values (the <em>formal parameters</em>) are listed. In this |
| example, there is one input value, namely <code>list int</code> which is a list of |
| integers. Parameter name <code>xs</code> is used to refer to the input value in the |
| body of the function. |
| Between <code>func</code> and the name of the function is the type of the computation |
| result, in this case, a <code>real</code> value. |
| In other words, this <code>mean</code> function takes a list of integers as input, and |
| produces a <code>real</code> value as result.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| The colon at the end of the first line indicates the start of the computation. |
| Below it are new variable declarations (<code>int sum</code>), and statements to |
| compute the value, the <em>function algorithm</em>. |
| The <code>return</code> statement denotes the end of |
| the function algorithm. |
| The value of the expression behind it is the result of the calculation. |
| This example computes and returns the mean value of the integers of the list.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Use of a function (<em>application</em> of a function) is done by using its name, |
| followed by the values to be used as input (the <em>actual parameters</em>). |
| The above function can be used like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">m = mean([1, 3, 5, 7, 9])</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The actual parameter of this function application is <code>[1, 3, 5, 7, 9]</code>. |
| The function result is <code>(1 + 3 + 5 + 7 + 9)/5</code> (which is <code>5.0</code>), and |
| variable <code>m</code> becomes <code>5.0</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| A function is a mathematical function: the result of a function is the same |
| for the same values of input parameters. |
| A function has no <em>side-effect</em>, and it cannot access variables outside the body. |
| For example, it cannot access <code>time</code> (explained in |
| <a href="#tut-servers-with-time">Servers with time</a>) directly, it has to be passed in through |
| the parameter list.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A function that calculates the sign of a real number, is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">func int sign(real r): |
| if r < 0: |
| return -1 |
| elif r = 0: |
| return 0 |
| end; |
| return 1 |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The sign function returns:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>if <code>r</code> is smaller than zero, the value minus one;</p> |
| </li> |
| <li> |
| <p>if <code>r</code> equals zero, the value zero; and</p> |
| </li> |
| <li> |
| <p>if <code>r</code> is greater than zero, the value one.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The computation in a function ends when it encounters a <code>return</code> statement. |
| The <code>return 1</code> at the end is therefore only executed when both |
| <code>if</code> conditions are false.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-sorted-lists">Sorted lists</h4> |
| <div class="paragraph"> |
| <p>The language allows <em>recursive</em> functions as well as <em>higher-order</em> functions. |
| Explaining them in detail is beyond the scope of this tutorial, but these |
| functions are useful for making and maintaining sorted lists. |
| Such a sorted list is useful for easily getting the smallest (or largest) item |
| from a collection, for example the order with the nearest deadline.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To sort a list, the first notion that has to be defined is the desired order, |
| by making a function of the following form:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">func bool decreasing(int x, y): |
| return x >= y |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The function is called <em>predicate function</em>. |
| It takes two values from the list (two integers in this case), and produces a |
| boolean value, indicating whether the parameters are in the right order. |
| In this case, the function returns <code>true</code> when the first parameter is larger |
| or equal than the second parameter, that is, larger values must be before |
| smaller values (for equal values, the order does not matter). This results in |
| a list with decreasing values.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The requirements on <em>any</em> predicate function <code>f</code> are:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>If <code>x != y</code>, either <code>f(x, y)</code> must hold or <code>f(y, x)</code> must hold, but |
| not both. (Unequal values must have a unique order.)</p> |
| </li> |
| <li> |
| <p>If <code>x == y</code>, both <code>f(x, y)</code> and <code>f(y, x)</code> must hold. (Equal values |
| can be placed in arbitrary order.)</p> |
| </li> |
| <li> |
| <p>For values <code>x</code>, <code>y</code>, and <code>z</code>, if <code>f(x, y)</code> holds and <code>f(y, z)</code> |
| holds (that is <code>x >= y</code> and <code>y >= z</code>), then <code>f(x, z)</code> must also hold |
| (that is, <code>x >= z</code> should also be true).</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>(The order between <code>x</code> and <code>z</code> must be stable, even when you compare |
| with an intermediate value <code>y</code> between <code>x</code> and <code>z</code>.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>These requirements hold for functions that test on <code><=</code> or <code>>=</code> between |
| two values, like above.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you do not provide a proper predicate function, the result may not be |
| sorted as you expect, or the simulator may abort when it fails to find a |
| proper sorting order.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-sort">Sort</h5> |
| <div class="paragraph"> |
| <p>The first use of such a predicate function is for sorting a list. For example |
| list <code>[3, 8, 7]</code> is sorted decreasingly (larger numbers |
| before smaller numbers) with the following statement:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">ys = sort([3, 8, 7], decreasing)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Sorting is done with the <em>sort</em> function, it takes two parameters, the list to |
| sort, and the predicate <em>function</em>. (There are no parentheses <code>()</code> behind |
| <code>decreasing</code>!) The value of list <code>ys</code> becomes <code>[8, 7, 3]</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Another sorting example is a list of type <code>tuple(int number, real slack)</code>, |
| where field <code>number</code> denotes the number of an item, and field <code>slack</code> |
| denotes the slack time of the item. The list should be sorted in ascending |
| order of the slack time. The type of the item is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type item = tuple(int number, real slack);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The predicate function <code>spred</code> is defined by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">func bool spred(item x, y): |
| return x.slack <= y.slack |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Function <code>spred</code> returns <code>true</code> if the two elements are in increasing |
| order in the list, otherwise <code>false</code>. |
| Note, the parameters of the function are of type <code>item</code>. |
| Given a variable <code>ps</code> equal to <code>[(7, 21.6), (5, 10.3), (3, 35.8)]</code>. |
| The statement denoting the sorting is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">qs = sort(ps, spred)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>variable <code>qs</code> becomes <code>[(5, 10.3), (7, 21.6), (3, 35.8)]</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-insert">Insert</h5> |
| <div class="paragraph"> |
| <p>Adding a new value to a sorted list is the second use of higher-order |
| functions. The simplest approach would be to add the new value to the head or |
| rear of the list, and sort the list again, but sorting an almost sorted list |
| is very expensive. |
| It is much faster to find the right position in the already sorted list, and |
| insert the new value at that point. |
| This function also exists, and is named <code>insert</code>. |
| An example is (assume <code>xs</code> initially contains <code>[3,8]</code>):</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">xs = insert(xs, 7, increasing)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where <code>increasing</code> is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">func bool increasing(int x, y): |
| return x <= y |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>insert</code> call assigns the result <code>[3,7,8]</code> as new value to <code>xs</code>, |
| <code>7</code> is inserted in the list.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-input-and-output">Input and output</h3> |
| <div class="paragraph"> |
| <p>A model communicates with the outside world, e.g. screen and files, by the use |
| of read statements for input of data, and write statements for output of data.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-the-read-function">The <code>read</code> function</h4> |
| <div class="paragraph"> |
| <p>Data can be read from the command line or from a file by <em>read</em> functions. |
| A read function requires a type value for each parameter to be read. |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">int i; string s; |
| |
| i = read(int); |
| s = read(string);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Two values, an integer value and a string value are read from the command line. |
| On the command line the two values are typed:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">1 "This is a string"</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Variable <code>i</code> becomes <code>1</code>, and string <code>s</code> becomes <code>"This is a string"</code>. |
| The double quotes are required! Parameter values are separated by a space or a |
| tabular stop. Putting each value on a separate line also works.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-reading-from-file">Reading from a file</h4> |
| <div class="paragraph"> |
| <p>Data also can be read from files. An example fragment:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type row = tuple(string name; list int numbers); |
| |
| file f; |
| int i; |
| list row rows; |
| |
| f = open("data_file.txt", "r"); |
| i = read(f, int); |
| rows = read(f, list row); |
| close(f)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Before a file can be used, the file has to be declared, <em>and</em> the file has to |
| be opened by statement <code>open</code>. |
| Statement <code>open</code> has two parameters, the first parameter denotes the file |
| name (as a string), and the second parameter describes the way the file is |
| used. In this case, the file is opened in a read-only mode, denoted by string |
| "r".</p> |
| </div> |
| <div class="paragraph"> |
| <p>Reading values works in the same way as before, except you cannot add new text |
| in the file while reading it. Instead, the file is processed sequentially from |
| begin to end, with values separated from each other by white space (spaces, |
| tabs, and new-lines). You can read values of different types from the same |
| file, as long as the value in the file matches with the type that you ask. |
| For example, the above Chi program could read the following data from |
| <code>data_file.txt</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">21 |
| [("abc", [7,21]), |
| ("def", [8,31,47])]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>After enough values have been read, the file should be closed with the |
| statement <code>close</code>, with one parameter, the variable of the file. |
| If a file is still open after an experiment, the file is closed automatically |
| before the program quits.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-advanced-file-reading">Advanced reading from a file</h4> |
| <div class="paragraph"> |
| <p>When reading from a file, the <code>eof</code> and <code>eol</code> functions can be used to |
| obtain information about the white space around the values.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <code>eof</code> (end of file) function returns <code>true</code> if you have read the |
| last value (that is, there are no more values to read).</p> |
| </li> |
| <li> |
| <p>The <code>eol</code> (end of line) function returns <code>true</code> if there are no more |
| values at the current line. In particular, the <code>eol</code> function returns |
| <code>true</code> when the end of the file has been reached.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>These functions can be used to customize reading of more complicated values. |
| As an example, you may want to read the same <code>list row</code> value as above, but |
| without having all the comma’s, quotes, parentheses, and brackets of the |
| literal value <code>[("abc", [7,21]), ("def", [8,31,47])]</code>. |
| Instead, imagine having a file <code>clean_data.txt</code> with the following layout:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">abc 7 21 |
| def 8 31 47</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Each line is one row. It starts with a one-word string, followed by a list of |
| integer numbers. |
| By using the <code>eof</code> and <code>eol</code> functions, you can read this file in the |
| following way:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">file f; |
| list row rows; |
| string name; |
| list int xs; |
| |
| f = open("clean_data.txt", "r"); |
| while not eof(f): |
| name = read(f, string); |
| xs = <int>[]; |
| while not eol(f): # Next value is at the same line. |
| xs = xs + [read(f, int)]; |
| end |
| rows = rows + [(name, xs)]; |
| end |
| close(f);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Each line is processed individually, where <code>eol</code> is used to find out whether |
| the last value of a line has been read. The reading loop terminates when |
| <code>eof</code> returns <code>true</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that <code>eol</code> returns whether the current line has no more values. It does |
| not tell you how many lines down the next value is. For example, an empty line |
| inserted between the <code>abc 7 21</code> line and the <code>def 8 31 47</code> line is |
| skipped silently. If you want that information, you can use the <code>newlines</code> |
| function instead.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-the-write-statement">The <code>write</code> statement</h4> |
| <div class="paragraph"> |
| <p>The <em>write</em> statement is used for for output of data to the screen of the |
| computer. Data can also be written to a file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The first argument of <code>write</code> (or the second argument if you write to a file, |
| see below) Is called the <em>format string</em>. It is a template of the text to |
| write, with 'holes' at the point where a data value is to be written.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Behind the format string, the data values to write are listed. The first value is |
| written in the first 'hole', the second value in the second 'hole' and so |
| on. The holes are also called <em>place holders</em>. A place holder starts with |
| <code>%</code> optionally followed by numbers or some punctuation (its meaning is |
| explained below). A place holder ends with a <em>format specifier</em>, a single |
| letter like <code>s</code> or <code>f</code>. An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">int i = 5; |
| |
| write("i equals %s", i)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In this example the text <code>i equals 5</code> is written to the screen by the |
| <code>write</code> statement. The <code>"i equals %s"</code> format string defines what output |
| is written. All 'normal' characters are copied as-is. The <code>%s</code> place holder |
| is not copied. Instead the first data value (in this case <code>i</code>) is inserted.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>s</code> in the place holder is the format specifier. It means 'print as |
| string'. The <code>%s</code> is a general purpose format specifier, it works with |
| almost every type of data. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list dict(int:real) xs = [{1 : 5.3}]; |
| |
| write("%s", xs)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>will output the contents of <code>xs</code> (<code>{1 : 5.3}</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>In general, this works nicely, but for numeric values a little more control |
| over the output is often useful. |
| To this end, there are also format specifiers <code>d</code> for integer numbers, and |
| <code>f</code> for real numbers. |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">int i = 5; |
| real r = 3.14; |
| |
| write("%4d/%8.2f", i, r)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This fragment has the effect that the values of <code>i</code> and <code>r</code> are written to |
| the screen as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console"> 5/ 3.14</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The value of <code>i</code> is written in <code>d</code> format (as <code>int</code> value), and the |
| value of <code>r</code> is written in <code>f</code> format (as <code>real</code> value). |
| The symbols <code>d</code> and <code>f</code> originate respectively from 'decimal', and |
| 'floating point' numbers. |
| The numbers <code>4</code> respectively <code>8.2</code> denote that the integer value is |
| written four positions wide (that is, 3 spaces and a <code>5</code> character), and |
| that the real value is written eight positions wide, with two characters after |
| the decimal point (that is, 4 spaces and the text <code>3.14</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>A list of format specifiers is given in <a href="#tut-table-format-specifiers">Format specifiers</a>.</p> |
| </div> |
| <table id="tut-table-format-specifiers" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 6. Format specifiers</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Format specifier</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>%b</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">boolean value (outputs <code>false</code> or <code>true</code>)</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>%d</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">integer</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>%10d</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">integer, at least ten characters wide</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>%f</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>%10f</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real, at least ten characters wide</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>%.4f</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real, four characters after the decimal point</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>%10.4f</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real, at least ten characters wide with four characters after the decimal point</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>%s</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">character string <code>s</code>, can also write other types of data</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>%%</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">the character <code>%</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Finally, there are also a few special character sequences called <em>escape |
| sequence</em> which allow to write characters like horizontal tab (which means |
| 'jump to next tab position in the output'), or newline (which means 'go to the |
| next line in the output') in a string. |
| An escape sequence consists of two characters. First a backslash character |
| <code>\</code>, followed by a second character. |
| The escape sequence are presented in <a href="#tut-table-escape-sequences">Escape sequences in strings</a>.</p> |
| </div> |
| <table id="tut-table-escape-sequences" class="tableblock frame-all grid-all stretch"> |
| <caption class="title">Table 7. Escape sequences in strings</caption> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Sequence</th> |
| <th class="tableblock halign-left valign-top">Meaning</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>\n</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">new line</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>\t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">horizontal tab</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>\"</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">the character <code>"</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>\\</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">the character <code>\</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>An example is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">int i = 5, j = 10; |
| real r = 3.14; |
| write("%6d\t%d\n\t%.2f\n", i, j, r)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The result looks like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console"> 5 10 |
| 3.14</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The value of <code>j</code> is written at the tab position, the output goes to the next |
| line again at the first tab position, and outputs the value of <code>r</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-writing-to-file">Writing to a file</h4> |
| <div class="paragraph"> |
| <p>Data can be written to a file, analog to the read function. |
| A file has to be defined first, and opened for writing before the file can be used. |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">file f; |
| int i; |
| |
| f = open("output_file", "w"); |
| write(f, "%s", i); write(f, "%8.2f", r); |
| close(f)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A file, in this case <code>"output_file"</code> is used in write-only mode, denoted by |
| the character <code>"w"</code>. |
| Opening a file for writing destroys its old contents (if the file already exists). |
| In the write statement, the first parameter must be the file, and the second |
| parameter must be the format string.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After all data has been written, the file is closed by statement <code>close</code>. |
| If the file is still open after execution of the program, the file is closed |
| automatically.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-stochastic-behavior">Modeling stochastic behavior</h3> |
| <div class="paragraph"> |
| <p> |
| |
| |
| Many processes in the world vary a little bit each time they are performed. |
| Setup of machines goes a bit faster or slower, patients taking their medicine |
| takes longer this morning, more products are delivered today, or the quality |
| of the manufactured product degrades due to a tired operator. |
| Modeling such variations is often done with stochastic distributions. A |
| distribution has a mean value and a known shape of variation. By matching the |
| means and the variation shape with data from the system being modeled, an |
| accurate model of the system can be obtained. |
| The language has many stochastic distributions available, this chapter |
| explains how to use them to model a system, and lists a few commonly used |
| distributions. The full list is available in the reference manual at |
| <a href="#ref-chapter-distributions">Distributions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following fragment illustrates the use of the random distribution to model |
| a dice. |
| Each value of the six-sided dice is equally likely to appear. Every value |
| having the same probability of appearing is a property of the integer uniform |
| distribution, in this case using interval <code>[1, 7)</code> (inclusive on the left |
| side, exclusive on the right side). |
| The model is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">dist int dice = uniform(1,7); |
| int x, y; |
| |
| x = sample dice; |
| y = sample dice; |
| writeln("x=%d, y=%d", x, y);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The variable <code>dice</code> is an integer distribution, meaning that values drawn |
| from the distribution are integer numbers. It is assigned an |
| uniform distribution. |
| A throw of a dice is simulated with the <em>operator</em> <code>sample</code>. |
| Each time <code>sample</code> is used, a new sample value is obtained from the |
| distribution. |
| In the fragment the dice is thrown twice, and the values are assigned to the |
| variables <code>x</code>, and <code>y</code>.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-distributions">Distributions</h4> |
| <div class="paragraph"> |
| <p>The language provides <em>constant</em>, <em>discrete</em> and <em>continuous</em> distributions. |
| A discrete distribution is a distribution where only specific values can be |
| drawn, for example throwing a dice gives an integer number. |
| A continuous distribution is a distribution where a value from a continuous |
| range can be drawn, for example assembling a product takes a positive amount |
| of time. |
| The constant distributions are discrete distributions that always return the |
| same value. They are useful during the development of the model (see below).</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-constant-distributions">Constant distributions</h5> |
| <div class="paragraph"> |
| <p>When developing a model with stochastic behavior, it is hard to verify whether |
| the model behaves correctly, since the stochastic results make it difficult to |
| predict the outcome of experiments. As a result, errors in the model may not |
| be noticed, they hide in the noise of the stochastic results. |
| One solution is to first write a model without stochastic behavior, verify |
| that model, and then extend the model with stochastic sampling. |
| Extending the model with stochastic behavior is however an invasive change |
| that may introduce new errors. These errors are again hard to find due to the |
| difficulties to predict the outcome of an experiment. |
| The constant distributions aim to narrow the gap by reducing the amount of |
| changes that need to be done after verification.</p> |
| </div> |
| <div class="paragraph"> |
| <p>With constant distributions, a stochastic model with sampling of distributions |
| is developed, but the stochastic behavior is eliminated by temporarily using |
| constant distributions. The model performs stochastic sampling of values, but |
| with predictable outcome, and thus with predictable experimental results, |
| making verification easier. After verifying the model, the constant |
| distributions are replaced with the distributions that fit the mean value and |
| variation pattern of the modeled system, giving a model with stochastic |
| behavior. |
| Changing the used distributions is however much less invasive, making it less |
| likely to introduce new errors at this stage in the development of the model.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Constant distributions produce the same value <code>v</code> with every call of |
| <code>sample</code>. There is one constant distribution for each type of sample value:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>constant(bool v)</code>, a <code>bool</code> distribution.</p> |
| </li> |
| <li> |
| <p><code>constant(int v)</code>, an <code>int</code> distribution.</p> |
| </li> |
| <li> |
| <p><code>constant(real v)</code>, a <code>real</code> distribution.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>An example with a constant distribution is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">dist int u = constant(7);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This distribution returns the integer value <code>7</code> with each <code>sample u</code> |
| operation.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-discrete-distributions">Discrete distributions</h5> |
| <div class="paragraph"> |
| <p>Discrete distributions return values from a finite fixed set of possible |
| values as answer. In Chi, there is one distribution that returns a boolean |
| when sampled, and there are several discrete distributions that return an |
| integer number.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>dist</code> <code>bool</code> <strong>bernoulli</strong><code>(real p)</code></p> |
| <div class="paragraph"> |
| <p>Outcome of an experiment with chance <code>p</code> <code>(0 <= p <= 1)</code>.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/bernoulli.svg" alt="bernoulli"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>{false, true}</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>p</code> (where <code>false</code> is interpreted as <code>0</code>, and <code>true</code> is interpreted as <code>1</code>)</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>1 - p</code> (where <code>false</code> is interpreted as <code>0</code>, and <code>true</code> is interpreted as <code>1</code>)</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>Bernoulli(p), <a href="#law-tut">[law-tut]</a>, page 302</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>int</code> <strong>uniform</strong><code>(int a, b)</code></p> |
| <div class="paragraph"> |
| <p>Integer uniform distribution from <code>a</code> to <code>b</code> excluding the upper bound.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/disc_uni.svg" alt="disc uni"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>{a, a+1, ..., b-1}</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>(a + b - 1) / 2</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>((b - a)\^2 - 1) / 12</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>DU(a, b - 1), <a href="#law-tut">[law-tut]</a>, page 303</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-continuous-distributions">Continuous distributions</h5> |
| <div class="paragraph"> |
| <p>Continuous distributions return a value from a continuous range.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>uniform</strong><code>(real a, b)</code></p> |
| <div class="paragraph"> |
| <p>Real uniform distribution from <code>a</code> to <code>b</code>, excluding the upper bound.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/cont_uni.svg" alt="cont uni"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>[a, b)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>(a + b) / 2</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>(b - a)^2 / 12</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>U(a,b), <a href="#law-tut">[law-tut]</a>, page 282, except that distribution has an |
| inclusive upper bound.</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>gamma</strong><code>(real a, b)</code></p> |
| <div class="paragraph"> |
| <p>Gamma distribution, with shape parameter <code>a > 0</code> and scale parameter <code>b > 0</code>.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/gamma.svg" alt="gamma"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>a * b</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>a * b^2</code></p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-references">References</h5> |
| <div class="ulist bibliography"> |
| <ul class="bibliography"> |
| <li> |
| <p><a id="law-tut"></a>[law-tut] Simulation Modeling & Analysis, fourth edition, |
| by Averill M. Law, |
| publisher McGraw-Hill, International Edition, 2007, |
| ISBN 978-007-125519-6</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-simulating-stochastic-behavior">Simulating stochastic behavior</h4> |
| <div class="paragraph"> |
| <p>In this chapter, the mathematical notion of stochastic distribution is used to |
| describe how to model stochastic behavior. |
| Simulating a model with stochastic behavior at a computer is however not |
| stochastic at all. Computer systems are deterministic machines, and |
| have no notion of varying results.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A (pseudo-)random number generator is used to create stochastic results |
| instead. It starts with an initial <em>seed</em>, an integer number (you can give one |
| at the start of the simulation). |
| From this seed, a function creates a stream of 'random' values. When looking |
| at the values there does not seem to be any pattern. |
| It is not truly random however. Using the same seed again gives exactly the |
| same stream of numbers. This is the reason to call the function a |
| <em>pseudo</em>-random number generator (a true random number generator would never |
| produce the exact same stream of numbers). |
| A sample of a distribution uses one or more numbers from the stream to compute |
| its value. |
| The value of the initial seed thus decides the value of all samples drawn in |
| the simulation. By default, a different seed is used each time you run a |
| simulation (leading to slightly different results each time). |
| You can also explicitly state what seed you want to use when running a model, |
| see <a href="#tool-compile-and-simulate">Compile and simulate</a>. |
| At the end of the simulation, the used |
| initial seed of that simulation is printed for reference purposes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>While doing a stochastic simulation study, performing several experiments with |
| the same initial seed invalidates the results, as it is equivalent to copying |
| the outcome of a single experiment a number of times. |
| On the other hand, when looking for the cause of a bug in the model, |
| performing the exact same experiment is useful as outcomes of previous |
| experiments should match exactly.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-exercises-4">Exercises</h4> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>According to the Chi reference manual, for a <code>gamma</code> distribution with |
| parameters <code>(a, b)</code>, the mean equals <code>a * b</code>.</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>Use a Chi specification to verify whether this is true for at least 3 |
| different pairs of <code>a</code> and <code>b</code>.</p> |
| </li> |
| <li> |
| <p>How many samples from the distribution are approximately required to |
| determine the mean up to three decimals accurate?</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>Estimate the mean μ and variance σ<sup>2</sup> of a triangular distribution |
| <code>triangle(1.0, 2.0, 5.0)</code> by simulating 1000 samples. Recall that the |
| variance σ<sup>2</sup> of <em>n</em> samples can be calculated by a function like:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">func real variance(list real samples, real avg): |
| real v; |
| |
| for x in samples: |
| v = v + (x - avg)^2; |
| end |
| |
| return v / (size(samples) - 1) |
| end</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>We would like to build a small game, called <em>Higher or Lower</em>. |
| The computer picks a random integer number between 1 and 14. The player |
| then has to predict whether the next number will be higher or lower. The |
| computer picks the next random number and compares the new number with the |
| previous one. If the player guesses right his score is doubled. If the |
| player guesses wrong, he looses all and the game is over. Try the following |
| specification:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model HoL(): |
| dist int u = uniform(1, 15); |
| int sc = 1; |
| bool c = true; |
| int new, oldval; |
| string s; |
| |
| new = sample u; |
| write("Your score is %d\n", sc); |
| write("The computer drew %d\n", new); |
| |
| while c: |
| writeln("(h)igher or (l)ower:\n"); |
| s = read(string); |
| oldval = new; |
| new = sample u; |
| write("The computer drew %d\n", new); |
| if new == oldval: |
| c = false; |
| else: |
| c = (new > oldval) == (s == "h"); |
| end; |
| |
| if c: |
| sc = 2 * sc; |
| else: |
| sc = 0; |
| end; |
| |
| write("Your score is %d\n", sc) |
| end; |
| write("GAME OVER...\n") |
| end</code></pre> |
| </div> |
| </div> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>What is the begin score?</p> |
| </li> |
| <li> |
| <p>What is the maximum end score?</p> |
| </li> |
| <li> |
| <p>What happens, when the drawn sample is equal to the previous drawn |
| sample?</p> |
| </li> |
| <li> |
| <p>Extend this game specification with the possibility to stop.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-processes">Processes</h3> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| The language has been designed for modeling and analyzing systems with many |
| components, all working together to obtain the total system behavior. |
| Each component exhibits behavior over time. Sometimes they are busy making |
| internal decisions, sometimes they interact with other components. |
| The language uses a <em>process</em> to model the behavior of a component (the |
| primary interest are the actions of the component rather than its physical |
| representation). This leads to models with many processes working in |
| <em>parallel</em> (also known as <em>concurrent</em> processes), interacting with each |
| other.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Another characteristic of these systems is that the parallelism happens at |
| different scales at the same time, and each scale can be considered to be a |
| collection of co-operating parallel working processes. |
| For example, a factory can be seen as a single component, it accepts supplies |
| and delivers products. |
| However, within a factory, you can have several parallel operating production |
| lines, and a line consists of several parallel operating machines. |
| A machine again consists of parallel operating parts. |
| In the other direction, a factory is a small element in a supply chain. Each |
| supply chain is an element in a (distribution) network. |
| Depending on the area that needs to be analyzed, and the level of detail, some |
| scales are precisely modeled, while others either fall outside the scope of |
| the system or are modeled in an abstract way.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In all these systems, the interaction between processes is not random, they |
| understand each other and exchange information. |
| In other words, they <em>communicate</em> with each other. The Chi language uses |
| <em>channels</em> to model the communication. |
| A channel connects a sending process to a receiving process, allowing the |
| sender to pass messages to the receiver. |
| This chapter discusses parallel operating processes only, communication |
| between processes using channels is discussed in <a href="#tut-chapter-channels">Channels</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As discussed above, a process can be seen as a single component with behavior |
| over time, or as a wrapper around many processes that work at a smaller scale. |
| The Chi language supports both kinds of processes. |
| The former is modeled with the statements explained in previous chapters and |
| communication that will be explained in <a href="#tut-chapter-channels">Channels</a>. |
| The latter (a process as a wrapper around many smaller-scale processes) is |
| supported with the <code>run</code> statement.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-a-single-process">A single process</h4> |
| <div class="paragraph"> |
| <p>The simplest form of processes is a model with one process:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(): |
| write("Hello. I am a process.") |
| end |
| |
| model M(): |
| run P() |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Similar to a model, a process definition is denoted by the keyword <code>proc</code> |
| (<code>proc</code> means process and does not mean procedure!), followed by the name of |
| the process, here <code>P</code>, followed by an empty pair of parentheses <code>()</code>, |
| meaning that the process has no parameters. |
| Process <code>P</code> contains one statement, a <code>write</code> statement to output text to |
| the screen. |
| Model <code>M</code> contains one statement, a <code>run</code> statement to run a process. |
| When simulating this model, the output is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">Hello. I am a process.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| A <code>run</code> statement constructs a process from the process definition (it |
| <em>instantiates</em> a process definition) for each of its arguments, and they start |
| running. |
| This means that the statements inside each process are executed. The <code>run</code> |
| statement waits until the statements in its created processes are finished, |
| before it ends itself.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To demonstrate, below is an example of a model with two processes:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(int i): |
| write("I am process. %d.\n", i) |
| end |
| |
| model M(): |
| run P(1), P(2) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This model instantiates and runs two processes, <code>P(1)</code> and <code>P(2)</code>. |
| The processes are running at the same time. |
| Both processes can perform a <code>write</code> statement. |
| One of them goes first, but there is no way to decide beforehand which one. |
| (It may always be the same choice, it may be different on Wednesday, etc, you |
| just don’t know.) |
| The output of the model is therefore either:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">I am process 1. |
| I am process 2.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>or:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">I am process 2. |
| I am process 1.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>After the two processes have finished their activities, the <code>run</code> statement |
| in the model finishes, and the simulation ends.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| An important property of statements is that they are executed <em>atomically</em>. |
| It means that execution of the statement of one process cannot be interrupted |
| by the execution of a statement of another process.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-a-process-in-a-process">A process in a process</h4> |
| <div class="paragraph"> |
| <p>The view of a process being a wrapper around many other processes is supported |
| by allowing to use the <code>run</code> statement inside a process as |
| well. An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(): |
| while true: |
| write("Hello. I am a process.\n") |
| end |
| end |
| |
| proc DoubleP(): |
| run P(), P() |
| end |
| |
| model M(): |
| run DoubleP() |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The model instantiates and runs one process <code>DoubleP</code>. |
| Process <code>DoubleP</code> instantiates and runs two processes <code>P</code>. |
| The relevance becomes clear in models with a lot of processes. |
| The concept of 'a process in a process' is very useful in keeping the model |
| structured.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-many-processes">Many processes</h4> |
| <div class="paragraph"> |
| <p>Some models consist of many identical processes at a single level. The |
| language has an <code>unwind</code> statement to reduce the amount of program text. |
| A model with e.g. ten identical processes, and a different parameter value, is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model MRun(): |
| run P(0), P(1), P(2), P(3), P(4), |
| P(5), P(6), P(7), P(8), P(9) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>An easier way to write this model is by applying the <code>unwind</code> statement |
| inside <code>run</code> with the same effect:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model MP(): |
| run unwind j in range(10): |
| P(j) |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>unwind</code> works like a <code>for</code> statement |
| (see <a href="#tut-for-statement">The <code>for</code> statement</a>), |
| except the <code>unwind</code> expands all values at the same time instead of iterating |
| over them one at a time.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-channels">Channels</h3> |
| <div class="paragraph"> |
| <p> |
| |
| |
| In <a href="#tut-chapter-processes">Processes</a> processes have been introduced. |
| This chapter describes channels, denoted by the type <code>chan</code>. |
| A channel connects two processes and is used for the transfer of data or just |
| signals. |
| One process is the sending process, the other process is the receiving process. |
| Communication between the processes takes place instantly when both processes |
| are willing to communicate, this is called <em>synchronous</em> communication.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-a-channel">A channel</h4> |
| <div class="paragraph"> |
| <p>The following example shows the sending of an integer value between two |
| processes via a channel. |
| <a href="#tut-figure-producer-consumer">A producer and a consumer</a> shows the two processes <code>P</code> and <code>C</code>, |
| connected by channel variable <code>a</code>.</p> |
| </div> |
| <div id="tut-figure-producer-consumer" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/producer_consumer.png" alt="producer consumer"> |
| </div> |
| <div class="title">Figure 3. A producer and a consumer</div> |
| </div> |
| <div class="paragraph"> |
| <p>Processes are denoted by circles, and channels are denoted by directed arrows |
| in the figure. The arrow denotes the direction of communication. |
| Process <code>P</code> is the sender or producer, process <code>C</code> is the receiver or consumer.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this case, the producer sends a finite stream of integer values (5 numbers) |
| to the consumer. |
| The consumer receives these values and writes them to the screen. |
| The model is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(chan! int a): |
| for i in range(5): |
| a!i |
| end |
| end |
| |
| proc C(chan? int b): |
| int x; |
| |
| while true: |
| b?x; |
| write("%d\n",x) |
| end |
| end |
| |
| model M(): |
| chan int a; |
| |
| run P(a), C(a) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The model instantiates processes <code>P</code> and <code>C</code>. |
| The two processes are connected to each other via channel variable <code>a</code> which |
| is given as actual parameter in the <code>run</code> statement. |
| This value is copied into the local formal parameter <code>a</code> in process <code>P</code> |
| and in formal parameter <code>b</code> inside process <code>C</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Process <code>P</code> can send a value of type <code>int</code> via the actual channel |
| parameter <code>a</code> to process <code>C</code>. |
| In this case <code>P</code> first tries to send the value <code>0</code>. |
| Process <code>C</code> tries to receive a value of type <code>int</code> via the actual channel |
| parameter <code>a</code>. |
| Both processes can communicate, so the communication occurs and the value |
| <code>0</code> is sent to process <code>C</code>. |
| The received value is assigned in process <code>C</code> to variable <code>x</code>. |
| The value of <code>x</code> is printed and the cycle starts again. |
| This model writes the sequence <code>0, 1, 2, 3, 4</code> to the screen.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-synchronization-channels">Synchronization channels</h4> |
| <div class="paragraph"> |
| <p>Above, process <code>P</code> constructs the numbers and sends them to process <code>C</code>. |
| However, since it is known that the number sequence starts at <code>0</code> and |
| increments by one each time, there is no actual need to transfer a number. |
| Process <code>C</code> could also construct the number by itself after getting a signal |
| (a 'go ahead') from process <code>P</code>. |
| Such signals are called synchronization signals, transfered by means of a |
| synchronization channel. The signal does not carry any data, |
| it just synchronizes a send and a receive between different processes. |
| (Since there is no actual data transfered, the notion of sender and receiver |
| is ambiguous. However, in modeling there is often a notion of 'initiator' |
| process that can be conveniently expressed with sending.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following example shows the use of synchronization signals between |
| processes <code>P</code> and <code>C</code>. |
| The connecting channel 'transfers' values of type <code>void</code>. |
| The type <code>void</code> means that 'non-values' are sent and received; |
| the type <code>void</code> is only allowed in combination with channels. |
| The iconic model is given in the previous figure, |
| <a href="#tut-figure-producer-consumer">A producer and a consumer</a>. |
| The model is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(chan! void a): |
| for i in range(5): |
| a! # No data is being sent |
| end |
| end |
| |
| proc C(chan? void b): |
| int i; |
| |
| while true: |
| b?; # Nothing is being received |
| write("%d\n", i); |
| i = i + 1 |
| end |
| end |
| |
| model M(): |
| chan void a; |
| |
| run P(a), C(a) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Process <code>P</code> sends a signal (and no value is sent), and process <code>C</code> |
| receives a signal (without a value). |
| The signal is used by process <code>C</code> to write the value of <code>i</code> and to |
| increment variable <code>i</code>. |
| The effect of the model is identical to the previous example: the numbers |
| <code>0, 1, 2, 3, 4</code> appear on the screen.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-two-channels">Two channels</h4> |
| <div class="paragraph"> |
| <p>A process can have more than one channel, allowing interaction with several |
| other processes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The next example shows two channel variables, <code>a</code> and <code>b</code>, and three |
| processes, generator <code>G</code>, server <code>S</code> and exit <code>E</code>. |
| The iconic model is given in <a href="#tut-figure-generator-server-exit">A generator, a server and an exit</a>.</p> |
| </div> |
| <div id="tut-figure-generator-server-exit" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/generator_server_exit.png" alt="generator server exit"> |
| </div> |
| <div class="title">Figure 4. A generator, a server and an exit</div> |
| </div> |
| <div class="paragraph"> |
| <p>Process <code>G</code> is connected via channel variable <code>a</code> to process <code>S</code> and |
| process <code>S</code> is connected via channel variable <code>b</code> to process <code>E</code>. |
| The model is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc G(chan! int a): |
| for x in range(5): |
| a!x |
| end |
| end |
| |
| proc S(chan? int a; chan! int b): |
| int x; |
| |
| while true: |
| a?x; x = 2 * x; b!x |
| end |
| end |
| |
| proc E(chan int a): |
| int x; |
| |
| while true: |
| a?x; |
| write("E %d\n", x) |
| end |
| end |
| |
| model M(): |
| chan int a,b; |
| |
| run G(a), S(a,b), E(b) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The model contains two channel variables <code>a</code> and <code>b</code>. |
| The processes are connected to each other in model <code>M</code>. |
| The processes are instantiated and run where the formal parameters are |
| replaced by the actual parameters. |
| Process <code>G</code> sends a stream of integer values <code>0, 1, 2, 3, 4</code> to another |
| process via channel <code>a</code>. |
| Process <code>S</code> receives a value via channel <code>a</code>, assigns this value to |
| variable <code>x</code>, doubles the value of the variable, and sends the value of the |
| variable via <code>b</code> to another process. |
| Process <code>E</code> receives a value via channel <code>b</code>, assigns this value to the |
| variable <code>x</code>, and prints this value. |
| The result of the model is given by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">E 0 |
| E 2 |
| E 4 |
| E 6 |
| E 8</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>After printing this five lines, process <code>G</code> stops, process <code>S</code> is blocked, |
| as well as process <code>E</code>, the model gets blocked, and the model ends.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-more-senders-or-receivers">More senders or receivers</h4> |
| <div class="paragraph"> |
| <p>Channels send a message (or a signal in case of synchronization channels) from |
| one sender to one receiver. It is however allowed to give the same channel to |
| several sender or receiver processes. The channel selects a sender and a |
| receiver before each communication.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The following example gives an illustration, see |
| <a href="#tut-figure-generator-2servers-exit">A generator, two servers and an exit</a>.</p> |
| </div> |
| <div id="tut-figure-generator-2servers-exit" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/generator_2servers_exit.png" alt="generator 2servers exit"> |
| </div> |
| <div class="title">Figure 5. A generator, two servers and an exit</div> |
| </div> |
| <div class="paragraph"> |
| <p>Suppose that only <code>G</code> and <code>S0</code> want to communicate. |
| The channel can select a sender (namely <code>G</code>) and a receiver (process |
| <code>S0</code>), and let both processes communicate with each other. |
| When sender <code>G</code>, and both receivers (<code>S0</code> and <code>S1</code>), want to |
| communicate, the channel selects a sender (<code>G</code> as it is the only sender |
| available to the channel), and a receiver (either process <code>S0</code> or process |
| <code>S1</code>), and it lets the selected processes communicate with each other. |
| This selection process is non-deterministic; a choice is made, but it is |
| unknown how the selection takes place and it cannot be influenced. |
| Note that a non-deterministic choice is different from a random choice. In the |
| latter case, there are known probabilities of selecting a process.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Sharing a channel in this way allows to send data to receiving processes where |
| the receiving party is not relevant (either server process will do). |
| This way of communication is different from <em>broadcasting</em>, where both servers |
| receive the same data value. |
| Broadcasting is not supported by the Chi language.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In case of two senders, <code>S0</code> and <code>S1</code>, and one receiver <code>E</code> the |
| selection process is the same. |
| If one of the two servers <code>S</code> can communicate with exit <code>E</code>, communication |
| between that server and the exit takes place. |
| If both servers can communicate, a non-deterministic choice is made.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Having several senders and several receivers for a single channel is also |
| handled in the same manner. |
| A non-deterministic choice is made for the sending process and a |
| non-deterministic choice is made for the receiving process before each |
| communication.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To communicate with several other processes but without non-determinism, |
| unique channels must be used.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-notes-2">Notes</h4> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The direction in channels, denoted by <code>?</code> or <code>!</code>, may be omitted. |
| By leaving it out, the semantics of the parameters becomes less clear (the |
| direction of communication has to be derived from the process code). |
| |
| </p> |
| </li> |
| <li> |
| <p>There are a several ways to name channels: |
| |
| </p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>Start naming formal channel parameters |
| in each new process with <code>a</code>, <code>b</code>, etc. |
| The actual names follow from the figure. |
| This convention is followed in this chapter. |
| For small models this convention is easy and works well, for complicated |
| models this convention can be error-prone. |
| |
| </p> |
| </li> |
| <li> |
| <p>Use the actual names of the channel parameters in the figures as formal |
| names in the processes. Start naming in figures with <code>a</code>, <code>b</code>, etc. |
| This convention works well, if both figure and code are at hand during |
| the design process. If many processes have sub-processes, this convention |
| does not really work.</p> |
| </li> |
| <li> |
| <p>Use unique names for the channel parameters for the whole model, and for |
| all sub-systems, for example a channel between processes <code>A</code> and <code>B</code> |
| is named <code>a2b</code> (the lower-case name of the sending process, followed by |
| <code>2</code>, denoting 'to', and the lower-case name of the receiving process).</p> |
| <div class="paragraph"> |
| <p>In this case the formal and actual parameters can be in most cases the same. |
| If many identical processes are used, this convention does not really work.</p> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In the text all three conventions are used, depending on the structure of |
| the model.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-exercises-5">Exercises</h4> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Given is the specification of process <code>P</code> and model <code>PP</code>:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(chan int a, b): |
| int x; |
| |
| while true: |
| a?x; |
| x = x + 1; |
| write("%d\n", x); |
| b!x |
| end |
| end |
| |
| model PP(): |
| chan int a, b; |
| |
| run P(a,b), P(b,a) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>Study this specification.</p> |
| </li> |
| <li> |
| <p>Why does the model terminate immediately?</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>Six children have been given the assignment to perform a series of |
| calculations on the numbers <code>0, 1, 2, 3, ..., 9</code>, namely add 2, multiply |
| by 3, multiply by 2, and add 6 subsequently. They decide to split up the |
| calculations and to operate in parallel. They sit down at a table next to |
| each other. The first child, the reader <code>R</code>, reads the numbers |
| <code>0, 1, 2, 3, ..., 9</code> one by one to the first calculating child <code>C1</code>. Child |
| <code>C1</code> adds 2 and tells the result to its right neighbour, child <code>C2</code>. After |
| telling the result to child <code>C2</code>, child <code>C1</code> is able to start |
| calculating on the next number the reader <code>R</code> tells him. Children <code>C2</code>, |
| <code>C3</code>, and <code>C4</code> are analogous to child <code>C1</code>; they each perform a |
| different calculation on a number they hear and tell the result to their |
| right neighbor. At the end of the table the writer <code>W</code> writes every |
| result he hears down on paper. Figure <a href="#tut-figure-sixchilds">Six children working in parallel</a> shows a |
| schematic drawing of the children at the table.</p> |
| <div id="tut-figure-sixchilds" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/sixchilds.png" alt="sixchilds"> |
| </div> |
| <div class="title">Figure 6. Six children working in parallel</div> |
| </div> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>Finish the specification for the reading child <code>R</code>, that reads the |
| numbers 0 till 9 one by one:</p> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc R(...): |
| int i; |
| |
| while i < 10: |
| ...; |
| ... |
| end |
| end</code></pre> |
| </div> |
| </div> |
| </li> |
| <li> |
| <p>Specify the parameterized process <code>Cadd</code> that represents the children |
| <code>C1</code> and <code>C4</code>, who perform an addition.</p> |
| </li> |
| <li> |
| <p>Specify the parameterized process <code>Cmul</code> that represents the children |
| <code>C2</code> and <code>C3</code>, who perform a multiplication.</p> |
| </li> |
| <li> |
| <p>Specify the process <code>W</code> representing the writing child. Write each |
| result to the screen separated by a new line.</p> |
| </li> |
| <li> |
| <p>Make a graphical representation of the model <code>SixChildren</code> that is |
| composed of the six children.</p> |
| </li> |
| <li> |
| <p>Specify the model <code>SixChildren</code>. Simulate the model.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-buffers">Buffers</h3> |
| <div class="paragraph"> |
| <p>In the previous chapter, a production system was discussed that passes values |
| from one process to the next using channels, in a synchronous manner. |
| (Sender and receiver perform the communication at exactly the same moment in |
| time, and the communication is instantaneous.) |
| In many systems however, processes do not use synchronous communication, they |
| use <em>asynchronous</em> communication instead. |
| Values (products, packets, messages, simple tokens, and so on) are sent, |
| temporarily stored in a buffer, and then received.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In fact, the decoupling of sending and receiving is very important, it allows |
| compensating temporarily differences between the number of items that are sent |
| and received. |
| (Under the assumption that the receiver is fast enough to keep up with the |
| sender in general, otherwise the buffer will grow forever or overflow.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, consider the exchange of items from a producer process <code>P</code> to a |
| consumer process <code>C</code> as shown in <a href="#tut-figure-pc2">A producer and a consumer</a>.</p> |
| </div> |
| <div id="tut-figure-pc2" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/producer_consumer.png" alt="producer consumer"> |
| </div> |
| <div class="title">Figure 7. A producer and a consumer</div> |
| </div> |
| <div class="paragraph"> |
| <p>In the unbuffered situation, both processes communicate at the same time. |
| This means that when one process is (temporarily) faster than the other, it |
| has to wait for the other process before communication can take place. |
| With a buffer in-between, the producer can give its item to the buffer, and |
| continue with its work. |
| Likewise, the consumer can pick up a new item from the buffer at any later |
| time (if the buffer has items).</p> |
| </div> |
| <div class="paragraph"> |
| <p>In Chi, buffers are not modeled as channels, they are modeled as additional |
| processes instead. The result is shown in <a href="#tut-figure-pbc">A producer and a consumer, with an additional buffer process</a>.</p> |
| </div> |
| <div id="tut-figure-pbc" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/buffered_producer_consumer.png" alt="buffered producer consumer"> |
| </div> |
| <div class="title">Figure 8. A producer and a consumer, with an additional buffer process</div> |
| </div> |
| <div class="paragraph"> |
| <p>The producer sends its items synchronously (using channel <code>a</code>) to the buffer |
| process. The buffer process keeps the item until it is needed. |
| The consumer gets an item synchronously (using channel <code>b</code>) from the buffer |
| when it needs a new item (and one is available).</p> |
| </div> |
| <div class="paragraph"> |
| <p>In manufacturing networks, buffers, in combination with servers, play a |
| prominent role, for buffering items in the network. |
| Various buffer types exist in these networks: buffers can have a finite or |
| infinite capacity, they have a input/output discipline, for example a |
| first-out queuing discipline or a priority-based discipline. |
| Buffers can store different kinds of items, for example, product-items, |
| information-items, or a combination of both. |
| Buffers may also have sorting facilities, etc.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this chapter some buffer types are described, and with the presented |
| concepts numerous types of buffer can be designed by the engineer. |
| First a simple buffer process with one buffer position is presented, followed |
| by more advanced buffer models. |
| The producer and consumer processes are not discussed in this chapter.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-a-one-place-buffer">A one-place buffer</h4> |
| <div class="paragraph"> |
| <p>A buffer usually has a receiving channel and a sending channel, for receiving |
| and sending items. |
| A buffer, buffer <code>B1</code>, is presented in <a href="#tut-figure-oneplacebuffer">A <code>1</code>-place buffer</a>.</p> |
| </div> |
| <div id="tut-figure-oneplacebuffer" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/one_place_buffer.png" alt="one place buffer"> |
| </div> |
| <div class="title">Figure 9. A <code>1</code>-place buffer</div> |
| </div> |
| <div class="paragraph"> |
| <p>The simplest buffer is a one-place buffer, for buffering precisely one item. |
| A one-place buffer can be defined by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc B1(chan? item a; chan! item b): |
| item x; |
| |
| while true: |
| a?x; b!x |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where <code>a</code> and <code>b</code> are the receiving and sending channels. |
| Item <code>x</code> is buffered in the process. |
| A buffer receives an item, stores the item, and sends the item to the next |
| process, if the next process is willing to receive the item. |
| The buffer is not willing to receive a second item, as long as the first item |
| is still in the buffer.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A two-place buffer can be created, by using the one-place buffer process |
| twice. |
| A two-place buffer is depicted in <a href="#tut-figure-twoplacebuffer">A <code>2</code>-place buffer</a>.</p> |
| </div> |
| <div id="tut-figure-twoplacebuffer" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/two_place_buffer.png" alt="two place buffer"> |
| </div> |
| <div class="title">Figure 10. A <code>2</code>-place buffer</div> |
| </div> |
| <div class="paragraph"> |
| <p>A two-place buffer is defined by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc B2(chan? item a; chan! item b): |
| chan item c; |
| |
| run B1(a, c), B1(c, b) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where two processes <code>B1</code> buffer maximal two items. |
| If each process <code>B1</code> contains an item, a third item has to wait in front of |
| process <code>B2</code>. This procedure can be extended to create even larger buffers. |
| Another, more preferable manner however, is to describe a buffer in a single |
| process by using a <em>select</em> statement and a list for storage of the items. |
| Such a buffer is discussed in the next section.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-a-single-process-buffer">A single process buffer</h4> |
| <div class="paragraph"> |
| <p>An informal description of the process of a buffer, with an arbitrary number |
| of stored items, is the following:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>If the buffer has space for an item, <em>and</em> can receive an item from another |
| process via channel <code>a</code>, the buffer process receives that item, and |
| stores the item in the buffer.</p> |
| </li> |
| <li> |
| <p>If the buffer contains at least one item, <em>and</em> the buffer can send that |
| item to another process via channel <code>b</code>, the buffer process sends that |
| item, and removes that item from the buffer.</p> |
| </li> |
| <li> |
| <p>If the buffer can both send and receive a value, the buffer process selects |
| one of the two possibilities (in a non-deterministic manner).</p> |
| </li> |
| <li> |
| <p>If the buffer cannot receive an item, and cannot send an item, the buffer |
| process waits.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p>Next to the sending and receiving of items (to and from the buffer process) is |
| the question of how to order the stored items. |
| A common form is the <em>first-in first-out</em> (fifo) queuing discipline. |
| Items that enter the buffer first (first-in) also leave first (first-out), the |
| order of items is preserved by the buffer process.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the model of the buffer, an (ordered) list of type <code>item</code> is used for |
| storing the received items. |
| New item <code>x</code> is added at the rear of list <code>xs</code> by the statement:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">xs = xs + [x]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The first item of the list is sent, and then deleted with:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">xs = xs[1:]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>An alternative solution is to swap the function of the rear and the front, |
| which can be useful some times.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The statement to monitor several channels at the same time is the <code>select</code> |
| statement. |
| The syntax of the <code>select</code> statement, with two alternatives, is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">select |
| boolean_expression_1, communication statement_1: |
| statement_list_1 |
| alt |
| boolean_expression_2, communication statement_2: |
| statement_list_2 |
| ... |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>There has to be at least one alternative in a select statement. The statement |
| waits, until for one of the alternatives the <code>boolean_expression</code> holds |
| <em>and</em> communication using the <code>communication statement</code> is possible. |
| (When there are several such alternatives, one of them is |
| non-deterministically chosen.) |
| For the selected alternative, the communication statement is executed, |
| followed by the statements in the <code>statement_list</code> of the alternative.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The above syntax is the most generic form, the <code>boolean_expression</code> may |
| be omitted when it always holds, or the <code>communication statement</code> may be |
| omitted when there is no need to communicate. The <code>,</code> also disappears then. |
| (Omitting both the boolean expression and the communication statement is not |
| allowed.) Similarly, when the <code>statement_list</code> is empty or just <code>pass</code>, it |
| may be omitted (together with the <code>:</code> in front of it).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The description (in words) of the core of the buffer, from the start of this |
| section, is translated in code, by using a <code>select</code> statement:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">select |
| size(xs) < N, a?x: |
| xs = xs + [x] |
| alt |
| size(xs) > 0, b!xs[0]: |
| xs = xs[1:] |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In the first alternative, it is stated that, if the buffer is not full, and |
| the buffer can receive an item, an item is received, and that item is added to |
| the rear of the list. |
| In the second alternative, it is stated that, if the buffer contains at least |
| one item, and the buffer can send an item, the first item in the list is sent, |
| and the list is updated. |
| Please keep in mind that both the condition must hold and the communication |
| must be possible <em>at the same moment</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The complete description of the buffer is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc B(chan? item a; chan! item b): |
| list item xs; item x; |
| |
| while true: |
| select |
| size(xs) < N, a?x: |
| xs = xs + [x] |
| alt |
| size(xs) > 0, b!xs[0]: |
| xs = xs[1:] |
| end |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Instead of boolean expression <code>size(xs) > 0</code>, expression <code>not empty(xs)</code> |
| can be used, where <code>empty</code> is a function yielding <code>true</code> if the list is |
| empty, otherwise <code>false</code>. |
| In case the capacity of the buffer is infinite, expression <code>size(xs) < N</code> |
| can be replaced by <code>true</code>, or even omitted (including the comma).</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-infinite-buffer">An infinite buffer</h4> |
| <div class="paragraph"> |
| <p>A buffer with infinite capacity can be written as:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc B(chan? item a; chan! item b): |
| list item xs; item x; |
| |
| while true: |
| select |
| a?x: |
| xs = xs + [x] |
| alt |
| not empty(xs), b!xs[0]: |
| xs = xs[1:] |
| end |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A first-in first-out buffer is also called a <em>queue</em>, while a first-in |
| last-out buffer (<em>lifo</em> buffer), is called a <em>stack</em>. |
| A description of a lifo buffer is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc B(chan? item a; chan! item b): |
| list item xs; item x; |
| |
| while true: |
| select |
| a?x: |
| xs = [x] + xs |
| alt |
| not empty(xs), b!xs[0]: |
| xs = xs[1:] |
| end |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The buffer puts the last received item at the head of the list, and gets the |
| first item from the list. An alternative is to put the last item at the rear |
| of the list, and to get the last item from the list.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-a-token-buffer">A token buffer</h4> |
| <div class="paragraph"> |
| <p>In the next example, signals are buffered instead of items. |
| The buffer receives and sends 'empty' items or <em>tokens</em>. |
| Counter variable <code>w</code> of type <code>int</code> denotes the difference between the |
| number of tokens received and the number of tokens sent. |
| If the buffer receives a token, counter <code>w</code> is incremented; if the buffer |
| sends a token, counter <code>w</code> is decremented. |
| If the number of tokens sent is less than the number of tokens received, there |
| are tokens in the buffer, and <code>w > 0</code>. |
| A receiving channel variable <code>a</code> of type <code>void</code> is defined for receiving |
| tokens. A sending channel variable <code>b</code> of type <code>void</code> is defined for |
| sending tokens. |
| The buffer becomes:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc B(chan? void a; chan! void b): |
| int w; |
| |
| while true: |
| select |
| a?: |
| w = w + 1 |
| alt |
| w > 0, b!: |
| w = w - 1 |
| end |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note that variables of type <code>void</code> do not exist. |
| Type <code>void</code> only can be used in combination with channels.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-a-priority-buffer">A priority buffer</h4> |
| <div class="paragraph"> |
| <p>A buffer for items with different priority is described in this section. An |
| item has a high priority or a normal priority. |
| Items with a high priority should leave the buffer first.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An item is a tuple with a field <code>prio</code>, denoting the priority, <code>0</code> for |
| high priority, and <code>1</code> for normal priority:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type item = tuple(...; int prio);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For the storage of items, two lists are used: a list for high priority items |
| and a list for normal priority items. |
| The two lists are described by a list with size two:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list(2) list item xs;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Variable <code>xs[0]</code> contains the high priority items, <code>xs[1]</code> the normal |
| priority items. |
| The first item in the high priority list is denoted by <code>xs[0][0]</code>, etc.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the model the received items are, on the basis of the value of the |
| <code>prio</code>-field in the item, stored in one of the two lists: one list for |
| 'high' items and one list for 'normal' items. |
| The discipline of the buffer is that items with a high priority leave the |
| buffer first. |
| The model is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc BPrio(chan? item a; chan! item b): |
| list(2) list item xs; item x; |
| |
| while true: |
| select |
| a?x: |
| xs[x.prio] = xs[x.prio] + [x] |
| alt |
| not empty(xs[0]), b!xs[0][0]: |
| xs[0] = xs[0][1:] |
| alt |
| empty(xs[0]) and not empty(xs[1]), b!xs[1][0]: |
| xs[1] = xs[1][1:] |
| end |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The buffer has two lists <code>xs[0]</code> and <code>xs[1]</code>. Received items <code>x</code> are |
| stored in <code>xs[x.prio]</code> by the statement <code>xs[x.prio] = xs[x.prio] + [x]</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the list high priority items (<code>xs[0]</code>) is not empty, items with high |
| priority are sent. The first element in list <code>xs[0]</code> is element |
| <code>xs[0][0]</code>. If there are no high priority items (list <code>xs[0]</code> is empty), |
| and there are normal priority items (list <code>xs[1]</code> is not empty), the first |
| element of list <code>xs[1]</code>, element <code>xs[1][0]</code>, is sent.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the order of the alternatives in the select statement does not |
| matter, every alternative is treated in the same way.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-buffer-exercises">Exercises</h4> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>To study product flow to and from a factory, a setup as shown in |
| <a href="#tut-figure-controlled-factory">A controlled factory</a> is created.</p> |
| <div id="tut-figure-controlled-factory" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/controlled_factory.png" alt="controlled factory"> |
| </div> |
| <div class="title">Figure 11. A controlled factory</div> |
| </div> |
| <div class="paragraph"> |
| <p><code>F</code> is the factory being studied, generator <code>G</code> sends products into the |
| factory, and exit process <code>E</code> retrieves finished products. The factory is |
| tightly controlled by controller <code>C</code> that sends a signal to <code>G</code> or <code>E</code> |
| before a product may be moved. The model is as follows:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc G(chan! int a; chan? void sg): |
| for i in range(10): |
| sg?; |
| a!i; |
| end |
| end |
| |
| proc F(chan? int a; chan! int b): |
| ... |
| end |
| |
| proc E(chan? int a; chan? void se): |
| int x; |
| |
| while true: |
| se?; |
| a?x; |
| write("E received %d\n", x); |
| end |
| end |
| |
| proc C(chan! void sg, se; int low, high): |
| int count; |
| |
| while true: |
| while count < high: |
| sg!; |
| count = count + 1; |
| end |
| while count > low: |
| se!; |
| count = count - 1; |
| end |
| end |
| end |
| |
| model M(): |
| chan void sg, se; |
| chan int gf, fe; |
| |
| run C(sg, se, 0, 1), |
| G(gf, sg), F(gf, fe), E(fe, se); |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The number of products inserted by the generator has been limited to allow |
| for manual inspection of results.</p> |
| </div> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>As a model of the factory, use a FIFO buffer process. |
| Run the simulation, and check whether all products are received by the |
| exit process.</p> |
| </li> |
| <li> |
| <p>Change the control policy to <code>low = 1</code> and <code>high = 4</code>. |
| Predict the outcome, and verify with simulation.</p> |
| </li> |
| <li> |
| <p>The employees of the factory propose to stack the products in the |
| factory to reduce the amount of space needed for buffering. |
| Replace the factory process with a LIFO buffer process, run the |
| experiments again, first with <code>low = 0</code> and <code>high = 1</code> and then with |
| <code>low = 1</code> and <code>high = 4</code>.</p> |
| </li> |
| <li> |
| <p>You will notice that some products stay in the factory forever. Why does |
| that happen? How should the policy be changed to ensure all products |
| eventually leave the factory?</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-servers-with-time">Servers with time</h3> |
| <div class="paragraph"> |
| <p> |
| A manufacturing line contains machines and/or persons that perform a sequence |
| of tasks, where each machine or person is responsible for a single task. |
| The term <em>server</em> is used for a machine or a person that performs a task. |
| Usually the execution of a task takes time, e.g. a drilling process, a welding |
| process, the set-up of a machine. |
| In this chapter we introduce the concept of <em>time</em>, together with the <em>delay</em> |
| statement.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that here 'time' means the simulated time inside the model. |
| For example, assume there are two tasks that have to be performed in sequence |
| in the modeled system. |
| The first task takes three hours to complete, the second task takes five hours |
| to complete. These amounts of time are specified in the model (using the delay |
| statement, as will be explained below). |
| A simulation of the system should report 'It takes eight hours from start of |
| the first task to finish of the second task'. |
| However, it generally does not take eight hours to compute that result, a |
| computer can calculate the answer much faster. |
| When an engineer says ''I had to run the system for a year to reach |
| steady-state'', he means that time inside the model has progressed a year.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-the-clock">The clock</h4> |
| <div class="paragraph"> |
| <p>The variable <code>time</code> denotes the current time in a model. It is a <em>global</em> |
| variable, it can be used in every <code>model</code> and <code>proc</code>. |
| The time is a variable of type <code>real</code>. Its initial value is <code>0.0</code>. The |
| variable is updated automatically by the model, it cannot be changed by the |
| user. |
| The unit of the time is however determined by the user, that is, you define |
| how long 1 time unit of simulated time is in the model.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The value of variable <code>time</code> can be retrieved by reading from the <code>time</code> |
| variable:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">t = time</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The meaning of this statement is that the current time is copied to variable |
| <code>t</code> of type real.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A process delays itself to simulate the processing time of an operation with a |
| <em>delay</em> statement. |
| The process postpones or suspends its own actions until the delay ends.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, suppose a system has to perform three actions, each action takes |
| 45 seconds. The unit of time in the model is one minute (that is, progress of |
| the modeled time by one time unit means a minute of simulated time has |
| passed). |
| The model looks like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(): |
| for i in range(3): |
| write("i = %d, time = %f\n", i, time); |
| delay 0.75 |
| end |
| end |
| |
| model M(): |
| run P() |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>An action takes 45 seconds, which is <code>0.75</code> time units. The <code>delay 0.75</code> |
| statement represents performing the action, the process is suspended until |
| 0.75 units of time has passed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The simulation reports:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">i = 0, time = 0.000000 |
| i = 1, time = 0.750000 |
| i = 2, time = 1.500000 |
| All processes finished at time 2.25</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The three actions are done in 2.25 time units (2.25 minutes).</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-servers-with-time">Servers with time</h4> |
| <div class="paragraph"> |
| <p>Adding time to the model allows answering questions about time, often |
| performance questions ('how many products can I make in this situation?'). Two |
| things are needed:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Servers must model use of time to perform their task.</p> |
| </li> |
| <li> |
| <p>The model must perform measurements of how much time passes.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>By extending models of the servers with time, time passes while tasks are |
| being performed. Time measurements then give non-zero numbers (servers that |
| can perform actions instantly result in all tasks being done in one moment of |
| time, that is 0 time units have passed between start and finish). |
| Careful analysis of the measurements should yields answers to questions about |
| performance.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this chapter, adding of passing time in a server and how to embed time |
| measurements in the model is explained. |
| The first case is a small production line with a deterministic server (its |
| task takes a fixed amount of time), while the second case uses stochastic |
| arrivals (the moment of arrival of new items varies), and a stochastic server |
| instead (the duration of the task varies each time). |
| In both cases, the question is what the flow time of an item is (the amount of |
| time that a single item is in the system), and what the throughput of the |
| entire system is (the number of items the production line can manufacture per |
| time unit).</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-servers-deterministic-system">A deterministic system</h5> |
| <div class="paragraph"> |
| <p>The model of a deterministic system consists of a deterministic generator, a |
| deterministic server, and an exit process. |
| The line is depicted in <a href="#tut-figure2-generator-server-exit">Generator <code>G</code>, server <code>S</code>, and exit <code>E</code></a>.</p> |
| </div> |
| <div id="tut-figure2-generator-server-exit" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/generator_server_exit.png" alt="generator server exit"> |
| </div> |
| <div class="title">Figure 12. Generator <code>G</code>, server <code>S</code>, and exit <code>E</code></div> |
| </div> |
| <div class="paragraph"> |
| <p>Generator process <code>G</code> sends items, with constant inter-arrival time <code>ta</code>, |
| via channel <code>a</code>, to server process <code>S</code>. |
| The server processes items with constant processing time <code>ts</code>, and sends |
| items, via channel <code>b</code>, to exit process <code>E</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An item contains a real value, denoting the creation time of the item, for |
| calculating the throughput of the system and flow time (or sojourn time) of an |
| item in the system. |
| The generator process creates an item (and sets its creation time), the exit |
| process <code>E</code> writes the measurements (the moment in time when the item |
| arrives in the exit process, and its creation time) to the output. |
| From these measurements, throughput and flow time can be calculated.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Model <code>M</code> describes the system:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type item = real; |
| |
| model M(real ta, ts; int N): |
| chan item a, b; |
| |
| run G(a, ta), |
| S(a, b, ts), |
| E(b, N) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>item</code> is a real number for storing the creation time. |
| Parameter <code>ta</code> denotes the inter-arrival time, and is used in generator <code>G</code>. |
| Parameter <code>ts</code> denotes the server processing time, and is used in server <code>S</code>. |
| Parameter <code>N</code> denotes the number of items that must flow through the system |
| to get a good measurement.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Generator <code>G</code> has two parameters, channel <code>a</code>, and inter-arrival time <code>ta</code>. |
| The description of process <code>G</code> is given by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc G(chan! item a; real ta): |
| while true: |
| a!time; delay ta |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Process <code>G</code> sends an item, with the current time, and delays for <code>ta</code>, |
| before sending the next item to server process <code>S</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Server <code>S</code> has three parameters, receiving channel <code>a</code>, sending channel |
| <code>b</code>, and server processing time <code>ts</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc S(chan? item a; chan! item b; real ts): |
| item x; |
| |
| while true: |
| a?x; delay ts; b!x |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The process receives an item from process <code>G</code>, processes the item during |
| <code>ts</code> time units, and sends the item to exit process <code>E</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Exit <code>E</code> has two parameters, receiving channel <code>a</code> and the length of the |
| experiment <code>N</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc E(chan item a; int N): |
| item x; |
| |
| for i in range(N): |
| a?x; write("%f, %f\n", time, time - x) |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The process writes current time <code>time</code> and item flow time <code>time - x</code> to |
| the screen for each received item. |
| Analysis of the measurements will show that the system throughput equals |
| <code>1 / ta</code>, and that the item flow time equals <code>ts</code> (if <code>ta >= ts</code>).</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-stochastic-system">A stochastic system</h5> |
| <div class="paragraph"> |
| <p>In the next model, the generator produces items with an exponential |
| inter-arrival time, and the server processes items with an exponential server |
| processing time. To compensate for the variations in time of the generator and |
| the server, a buffer process has been added. |
| The model is depicted in <a href="#tut-figure-MM1">Generator <code>G</code>, buffer <code>B</code>, server <code>S</code>, and exit <code>E</code></a>.</p> |
| </div> |
| <div id="tut-figure-MM1" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/generator_buffer_server_exit.png" alt="generator buffer server exit"> |
| </div> |
| <div class="title">Figure 13. Generator <code>G</code>, buffer <code>B</code>, server <code>S</code>, and exit <code>E</code></div> |
| </div> |
| <div class="paragraph"> |
| <p>Type <code>item</code> is the same as in the previous situation. |
| The model runs the additional buffer process:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model M(real ta, ts; int N): |
| chan item a, b, c; |
| |
| run G(a, ta), |
| B(a, b), |
| S(b, c, ts), |
| E(c, N) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Generator <code>G</code> has two parameters, channel variable <code>a</code>, and variable |
| <code>ta</code>, denoting the mean inter-arrival time. |
| An <code>exponential</code> distribution is used for deciding the inter-arrival time of |
| new items:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc G(chan item a; real ta): |
| dist real u = exponential(ta); |
| |
| while true: |
| a!time; delay sample u |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The process sends a new item to the buffer, and delays <code>sample u</code> time units. |
| Buffer process <code>B</code> is a fifo buffer with infinite capacity, as described at |
| <a href="#tut-infinite-buffer">An infinite buffer</a>. |
| Server <code>S</code> has three parameters, channel |
| variables <code>a</code> and <code>b</code>, for receiving and sending items, and a variable for |
| the average processing time <code>ts</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc S(chan item a, b; real ts): |
| dist real u = exponential(ts); |
| item x; |
| |
| while true: |
| a?x; delay sample u; b!x |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>An <code>exponential</code> distribution is used for deciding the processing time. |
| The process receives an item from process <code>G</code>, processes the item during |
| <code>sample u</code> time units, and sends the item to exit process <code>E</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Exit process <code>E</code> is the same as previously, see <a href="#tut-servers-deterministic-system">A deterministic system</a>. |
| In this case the throughput of the system also equals <code>1 / ta</code>, and the |
| <em>mean flow</em> can be obtained by doing an experiment and analysis of the |
| resulting measurements (for <code>ta > ts</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-two-servers">Two servers</h4> |
| <div class="paragraph"> |
| <p>In this section two different types of systems are shown: a serial and a |
| parallel system. |
| In a serial system the servers are positioned after each other, in a parallel |
| system the servers are operating in parallel. |
| Both systems use a stochastic generator, and stochastic servers.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-serial-system">Serial system</h5> |
| <div class="paragraph"> |
| <p>The next model describes a <em>serial</em> system, where an item is processed by one |
| server, followed by another server. |
| The generator and the servers are decoupled by buffers. |
| The model is depicted in <a href="#tut-figure-tandem">A generator, two buffers, two servers, and an exit</a>.</p> |
| </div> |
| <div id="tut-figure-tandem" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/generator_2buffers_2servers_exit.png" alt="generator 2buffers 2servers exit"> |
| </div> |
| <div class="title">Figure 14. A generator, two buffers, two servers, and an exit</div> |
| </div> |
| <div class="paragraph"> |
| <p>The model can be described by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model M(real ta, ts; int N): |
| chan item a, b, c, d, e; |
| |
| run G(a, ta), |
| B(a, b), S(b, c, ts), |
| B(c, d), S(d, e, ts), |
| E(e, N) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The various processes are equal to those described previously in |
| <a href="#tut-stochastic-system">A stochastic system</a>.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="tut-parallel-systems">Parallel systems</h5> |
| <div class="paragraph"> |
| <p>In a parallel system the servers are operating in parallel. Having several |
| servers in parallel is useful for enlarging the processing capacity of the |
| task being done, or for reducing the effect of break downs of servers (when a |
| server breaks down, the other server continues with the task for other items). |
| <a href="#tut-figure-two-parallel-servers">A model with two parallel servers</a> depicts the system.</p> |
| </div> |
| <div id="tut-figure-two-parallel-servers" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/two_parallel_servers.png" alt="two parallel servers"> |
| </div> |
| <div class="title">Figure 15. A model with two parallel servers</div> |
| </div> |
| <div class="paragraph"> |
| <p>Generator process <code>G</code> sends items via <code>a</code> to buffer process <code>B</code>, and |
| process <code>B</code> sends the items in a first-in first-out manner to the servers |
| <code>S</code>. Both servers send the processed items to the exit process <code>E</code> via |
| channel <code>c</code>. |
| The inter-arrival time and the two process times are assumed to be stochastic, |
| and exponentially distributed. |
| Items can pass each other, due to differences in processing time between the |
| two servers.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a server is free, and the buffer is not empty, an item is sent to a server. |
| If both servers are free, one server will get the item, but which one cannot |
| be determined beforehand. (How long a server has been idle is not taken into |
| account.) |
| The model is described by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model M(real ta, ts; int N): |
| chan item a, b, c; |
| |
| run G(a, ta), |
| B(a, b), |
| S(b, c, ts), S(b, c, ts), |
| E(c, N) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To control which server gets the next item, each server must have its own |
| channel from the buffer. In addition, the buffer has to know when the server |
| can receive a new item. |
| The latter is done with a 'request' channel, denoting that a server is free |
| and needs a new item. |
| The server sends its own identity as request, the requests are administrated |
| in the buffer. |
| The model is depicted in <a href="#tut-figure-two-parallel-requesting-servers">A model with two parallel requesting servers</a>.</p> |
| </div> |
| <div id="tut-figure-two-parallel-requesting-servers" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/two_parallel_requesting_servers.png" alt="two parallel requesting servers"> |
| </div> |
| <div class="title">Figure 16. A model with two parallel requesting servers</div> |
| </div> |
| <div class="paragraph"> |
| <p>In this model, the servers 'pull' an item through the line. |
| The model is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model M(real ta, ts; int N): |
| chan item a; list(2) chan item b; chan item c; |
| chan int r; |
| |
| run G(a, ta), |
| B(a, b, r), |
| unwind j in range(2): |
| S(b[j], c, r, ts, j) |
| end, |
| E(c, N) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In this model, an <code>unwind</code> statement is used for the initialization and |
| running of the two servers. |
| Via channel <code>r</code> an integer value, <code>0</code> or <code>1</code>, is sent to the buffer.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The items received from generator <code>G</code> are stored in list <code>xs</code>, the |
| requests received from the servers are stored in list <code>ys</code>. |
| The items and requests are removed form their respective lists in a first-in |
| first-out manner. |
| Process <code>B</code> is defined by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc B(chan? item a; list chan! item b; chan? int r): |
| list item xs; item x; |
| list int ys; int y; |
| |
| while true: |
| select |
| a?x: |
| xs = xs + [x] |
| alt |
| r?y: |
| ys = ys + [y] |
| alt |
| not empty(xs) and not empty(ys), b[ys[0]]!xs[0]: |
| xs = xs[1:]; ys = ys[1:] |
| end |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If, there is an item present, <em>and</em> there is a server demanding for an item, |
| the process sends the first item to the longest waiting server. |
| The longest waiting server is denoted by variable <code>ys[0]</code>. |
| The head of the item list is denoted by <code>xs[0]</code>. |
| Assume the value of <code>ys[0]</code> equals <code>1</code>, then the expression |
| <code>b[ys[0]]!xs[0]</code>, equals <code>b[1]!xs[0]</code>, indicates that the first item of |
| list <code>xs</code>, equals <code>xs[0]</code>, is sent to server <code>1</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The server first sends a request via channel <code>r</code> to the buffer, and waits |
| for an item. The item is processed, and sent to exit process <code>E</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc S(chan? item b; chan! item c; chan! int r; real ts; int k): |
| dist real u = exponential(ts); |
| item x; |
| |
| while true: |
| r!k; |
| b?x; |
| delay sample u; |
| c!x |
| end |
| end</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-assembly">Assembly</h4> |
| <div class="paragraph"> |
| <p>In assembly systems, components are assembled into bigger components. |
| These bigger components are assembled into even bigger components. |
| In this way, products are built, e.g. tables, chairs, computers, or cars. |
| In this section some simple assembly processes are described. |
| These systems illustrate how assembling can be performed: in industry these |
| assembly processes are often more complicated.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An assembly work station for two components is shown in |
| <a href="#tut-figure-assembly-two-components">Assembly for two components</a>.</p> |
| </div> |
| <div id="tut-figure-assembly-two-components" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/assembly_two_components.png" alt="assembly two components"> |
| </div> |
| <div class="title">Figure 17. Assembly for two components</div> |
| </div> |
| <div class="paragraph"> |
| <p>The assembly process server <code>S</code> is preceded by buffers. The server receives |
| an item from each buffer <code>B</code>, before starting assembly. The received items |
| are assembled into one new item, a list of its (sub-)items. |
| The description of the assembly server is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc S(list chan? item c, chan! list item b): |
| list(2) item v; |
| |
| while true: |
| select |
| c[0]?v[0]: c[1]?v[1] |
| alt |
| c[1]?v[1]: c[0]?v[0] |
| end |
| b!v |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The process takes a list of channels <code>c</code> to receive items from the preceding |
| buffers. |
| The output channel <code>b</code> is used to send the assembled component away to the |
| next process.</p> |
| </div> |
| <div class="paragraph"> |
| <p>First, the assembly process receives an item from both buffers. All buffers |
| are queried at the same time, since it is unknown which buffer has components |
| available. If the first buffer reacts first, and sends an item, it is received |
| with channel <code>c[0]</code> and stored in <code>v[0]</code> in the first alternative. The |
| next step is then to receive the second component from the second buffer, and |
| store it (<code>c[1]?v[1]</code>). |
| The second alternative does the same, but with the channels and stored items |
| swapped.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When both components have been received, the assembled product is sent away.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A generalized assembly work station for <code>n</code> components is depicted in |
| <a href="#tut-figure-assembly-n-components">Assembly for <code>n</code> components, with <code>m = n - 1</code></a>.</p> |
| </div> |
| <div id="tut-figure-assembly-n-components" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/assembly_n_components.png" alt="assembly n components"> |
| </div> |
| <div class="title">Figure 18. Assembly for <code>n</code> components, with <code>m = n - 1</code></div> |
| </div> |
| <div class="paragraph"> |
| <p>The entire work station (the combined buffer processes and the assembly server |
| process) is described by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc W(list chan? item a; chan! list item b): |
| list(size(a)) chan item c; |
| |
| run unwind i in range(size(a)): |
| B(a[i], c[i]) |
| end, |
| S(c,b) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The size of the list of channels <code>a</code> is determined during initialization of |
| the workstation. |
| This size is used for the generation of the process buffers, and the |
| accompanying channels.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The assembly server process works in the same way as before, except for a |
| generic <code>n</code> components, it is impossible to write a select statement |
| explicitly. Instead, an <em>unwind</em> is used to unfold the alternatives:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc S(list chan? item c, chan! list item b): |
| list(size(c)) item v; |
| list int rec; |
| |
| while true: |
| rec = range(size(c)); |
| while not empty(rec): |
| select |
| unwind i in rec |
| c[i]?v[i]: rec = rec - [i] |
| end |
| end |
| end; |
| delay ...; |
| b!v |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The received components are again in <code>v</code>. Item <code>v[i]</code> is received from |
| channel <code>c[i]</code>. The indices of the channels that have not provided an item |
| are in the list <code>rec</code>. Initially, it contains all channels |
| <code>0</code> …​ <code>size(c)</code>, that is, <code>range(size(c))</code>. While <code>rec</code> still has a |
| channel index to monitor, the <code>unwind i in rec</code> unfolds all alternatives |
| that are in the list. For example, if <code>rec</code> contains <code>[0, 1, 5]</code>, |
| the <code>select unwind i in rec ... end</code> is equivalent to:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">select |
| c[0]?v[0]: rec = rec - [0] |
| alt |
| c[1]?v[1]: rec = rec - [1] |
| alt |
| c[5]?v[5]: rec = rec - [5] |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>After receiving an item, the index of the channel is removed from <code>rec</code> to |
| prevent receiving a second item from the same channel. |
| When all items have been received, the assembly process starts (modeled with a |
| <code>delay</code>, followed by sending the assembled component away with <code>b!v</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In practical situations these assembly processes are performed in a more |
| cascading manner. Two or three components are 'glued' together in one assemble |
| process, followed in the next process by another assembly process.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-exercises-6">Exercises</h4> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>To understand how time and time units relate to each other, change the time |
| unit of the model in <a href="#tut-the-clock">The clock</a>.</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>Change the model to using time units of one second (that is, one time |
| unit means one second of simulated time).</p> |
| </li> |
| <li> |
| <p>Predict the resulting throughput and flow time for a deterministic case |
| like in |
| <a href="#tut-servers-with-time">Servers with time</a>, with <code>ta = 4</code> and <code>ts = 5</code>. |
| Verify the prediction with an experiment, and explain the result.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| <li> |
| <p>Extend the model <a href="#tut-figure-controlled-factory">A controlled factory</a> |
| in <a href="#tut-buffer-exercises">Buffer exercises</a> |
| with a single deterministic server taking |
| <code>4.0</code> time units to model the production capacity of the factory. |
| Increase the number of products inserted by the generator, and measure the |
| average flow time for</p> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>A FIFO buffer with control policy <code>low = 0</code> and <code>high = 1</code>.</p> |
| </li> |
| <li> |
| <p>A FIFO buffer with control policy <code>low = 1</code> and <code>high = 4</code>.</p> |
| </li> |
| <li> |
| <p>A <em>LIFO</em> buffer with control policy <code>low = 1</code> and <code>high = 4</code>.</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-conveyors">Conveyors</h3> |
| <div class="paragraph"> |
| <p>A conveyor is a long belt on which items are placed at the starting point of |
| the conveyor. |
| The items leave the conveyor at the end point, after traveling a certain |
| period of time on the conveyor. |
| The number of items traveling on the conveyor varies, while each item stays |
| the same amount of time on the conveyor. It works like a buffer that provides |
| output based on item arrival time instead of based on demand from the next |
| process.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-using-timers">Timers</h4> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| To model a conveyor, you have to wait until a particular point in time. The |
| Chi language has timers to signal such a time-out. |
| The timer is started by assigning it a value. From that moment, it |
| automatically decrements when time progresses in the model, until it reaches |
| zero. The function <code>ready</code> gives the boolean value <code>true</code> if the timer is ready. |
| The amount of time left can be obtained by reading from the variable. |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(): |
| timer t; |
| |
| delay 10.0; |
| t = timer(5.0); # Get a time-out at time = 15.0 |
| for i in range(7): |
| write("%f %f %b\n, time, real(t), ready(t)); |
| delay 1.0 |
| end |
| end |
| |
| model M(): |
| run P() |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Initially, <code>time</code> equals <code>0.0</code>. |
| The first action of process <code>P</code> is to delay the time for <code>10.0</code> time units. |
| Now the value of <code>time</code> equals <code>10.0</code>. Nothing happens to timer <code>t</code> as |
| it was already zero. |
| At time <code>10</code> timer <code>t</code> is started with the value <code>5.0</code>. |
| The output of the program is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">10.0 5.0 false |
| 11.0 4.0 false |
| 12.0 3.0 false |
| 13.0 2.0 false |
| 14.0 1.0 false |
| 15.0 0.0 true |
| 16.0 0.0 true</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Timer <code>t</code> decrements as time progresses, and it is <code>ready</code> at |
| <code>10.0 + 5.0</code> units. |
| A process can have more timers active at the same moment.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-a-conveyor">A conveyor</h4> |
| <div class="paragraph"> |
| <p>A conveyor is schematically depicted in <a href="#tut-figure-conveyor">A conveyor with three items</a>.</p> |
| </div> |
| <div id="tut-figure-conveyor" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/conveyor_3items.png" alt="conveyor 3items"> |
| </div> |
| <div class="title">Figure 19. A conveyor with three items</div> |
| </div> |
| <div class="paragraph"> |
| <p>Three items are placed on the conveyor. For simplicity, assume the conveyor is |
| <code>60.0</code> meter long and has a speed of <code>1</code> meter per second. |
| An item thus stays on the conveyor for <code>60.0</code> seconds.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Item <code>0</code> has been placed on the conveyor <code>50.0</code> seconds ago, and will leave |
| the conveyor <code>10.0</code> second from now. In the same way, item <code>1</code> will leave |
| <code>30.0</code> seconds from now, and <code>2</code> leaves after <code>45.0</code> seconds. Each item |
| has a <em>yellow sticker</em> with the time that the item leaves the conveyor. Based |
| on this idea, tuple type <code>conv_item</code> has been defined, consisting of a |
| field <code>item</code>, denoting the received item, and a timer field <code>t</code>, with the |
| remaining time until the item leaves the conveyor:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type conv_item = tuple(item x; timer t); |
| |
| proc T(chan? item a; chan! item b; real convey_time): |
| list conv_item xst; item x; |
| |
| while true: |
| select |
| a?x: |
| xst = xst + [(x, timer(convey_time))] |
| alt |
| not empty(xst) and ready(xst[0].t), b!xst[0].x: |
| xst = xst[1:] |
| end |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The conveyor always accepts new items from channel <code>a</code>, and adds the item |
| with the yellow sticker to the list. If the conveyor is not empty, and the |
| timer has expired for the first item in the list, it is sent (without sticker) |
| to the next process. The conveyor sends items to a process that is always |
| willing to a receive an item, this implies that the conveyor is never blocked. |
| Blocking implies that the items nevertheless are transported to the end of the |
| conveyor.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-a-priority-conveyor">A priority conveyor</h4> |
| <div class="paragraph"> |
| <p>In this example, items are placed on a conveyor, where the time of an item on |
| the conveyor varies between items. |
| Items arriving at the conveyor process, get inserted in the list with waiting |
| items, in ascending order of their remaining time on the conveyor. |
| The field <code>tt</code> in the item denotes the traveling time of the item on the |
| conveyor:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type item = tuple(...; real tt; ...), |
| conv_item = tuple(item x; timer t);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The predicate function <code>pred</code> is defined by:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">func bool pred(conv_item x, y): |
| return real(x.t) <= real(y.t) |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The conveyor process becomes:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc T(chan? item a; chan! item b): |
| list conv_item xst; item x; |
| |
| while true: |
| select |
| a?x: |
| xst = insert(xst, (x, timer(x.tt)), pred) |
| alt |
| not empty(xst) and ready(xst[0].t), b!xst[0].item: |
| xst = xst[1:] |
| end |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The conveyor process works like before, except the new item is inserted in the |
| list according to its remaining time, instead of at the rear of the list.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-exercises-7">Exercises</h4> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Model the system as shown in <a href="#tut-figure-conveyor-system">A conveyor system</a> where <code>T</code> |
| is a conveyor process with a capacity of <em>at most</em> three products and |
| exponentially distributed conveying times with an average of <code>4.0</code>.</p> |
| <div class="paragraph"> |
| <p>Compute the average flow time of products in the system.</p> |
| </div> |
| <div id="tut-figure-conveyor-system" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/conveyor_system.png" alt="conveyor system"> |
| </div> |
| <div class="title">Figure 20. A conveyor system</div> |
| </div> |
| </li> |
| <li> |
| <p>Model the system as shown in <a href="#tut-figure-three-parallel-servers">A system with three parallel servers</a> with |
| exponentially distributed server processing times with an average of |
| <code>4.0</code>.</p> |
| <div id="tut-figure-three-parallel-servers" class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/pictures/three_parallel_servers.png" alt="three parallel servers"> |
| </div> |
| <div class="title">Figure 21. A system with three parallel servers</div> |
| </div> |
| <div class="olist loweralpha"> |
| <ol class="loweralpha" type="a"> |
| <li> |
| <p>Compute the average flow time of products in the system.</p> |
| </li> |
| <li> |
| <p>Are there differences in behavior between both systems? Why (not)?</p> |
| </li> |
| </ol> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-simulation-and-experiments">Simulations and experiments</h3> |
| <div class="paragraph"> |
| <p>So far, attention has focused on the Chi language, and how to use it for |
| modeling a discrete-event system.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this chapter, the focus shifts to performing simulations, in particular for |
| systems with infinite behavior. Also, how to perform multiple model |
| simulations is explained.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-simulating-finite-systems">Simulating finite systems</h4> |
| <div class="paragraph"> |
| <p>For systems that have simple cyclic behavior, the simulation can be |
| 'exhaustive', for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc G(chan! real a): |
| a!time |
| end |
| |
| proc M(chan? real a, chan! real b): |
| real x; |
| |
| a?x; delay 5.0; b!x |
| end |
| |
| proc E(chan? real a): |
| real x; |
| |
| a?x; |
| writeln("Flow time: %.2f", time - x); |
| end |
| |
| model M(): |
| chan real gm, me; |
| |
| run G(gm), M(gm, me), E(me); |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This simulation sends a single product through the line, prints the flow time, |
| and exits. (All processes end, which makes that the <code>run</code> statement and the |
| model end as well.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this case, the answer is even obvious without running the simulation.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-exit">Simulating infinite systems</h4> |
| <div class="paragraph"> |
| <p>For other systems, it is much harder to decide when enough has been simulated. |
| Typically, a process (<code>E</code> in the example below), collects values of the |
| property of interest (for example flow time of products), until it has |
| collected enough samples to draw a conclusion, and compute the resulting value.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After doing so, the problem arises to let all processes know the simulation |
| should be stopped. This can be programmed in the model (such as adding |
| channels to |
| signal termination of the simulation to all processes). A simpler alternative |
| is to use the <code>exit</code> statement, in the following way:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc real E(chan? real a, int N): |
| real total, x; |
| |
| for n in range(N): |
| a?x; |
| total = total + time - x; |
| end; |
| exit total / N |
| end |
| |
| model real M(... int N): |
| ... |
| |
| run ..., E(..., N); |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In process <code>E</code>, the average flow time is calculated and given as |
| argument of the <code>exit</code> statement. At the moment this statement is executed, |
| the model and all processes are killed, and the computed value becomes the |
| exit value (the result) of the simulation. The <code>real</code> type before |
| the name <code>E</code> denotes that the process may perform an <code>exit</code> statement |
| returning a real value. The model runs the <code>E</code> process, so it may also give |
| an exit value as result. These types are called <em>exit type</em>. |
| Exit values are printed to the screen by the simulator when it ends the |
| model simulation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Another option is to use <code>write</code> to output the computed value, and use |
| <code>exit</code> without argument. In that case, the exit value is of type <code>void</code>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-experiment">Simulating several scenarios</h4> |
| <div class="paragraph"> |
| <p>The above works nicely for single model simulations. The model is started one |
| time, and it derives a result for a single scenario.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Often however, you want to perform several model simulations. This can be the |
| exact same scenario when the model has stochastic behavior, or it can be |
| with different parameter values each time (to investigate system behavior |
| under different circumstances). |
| In such cases, you can use an experiment, like below:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">xper X(): |
| real v; |
| int n; |
| |
| for n in range(5, 10): |
| v = M(n); |
| write("%2d: %.2f\n", n, v) |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The experiment <code>X</code> looks just like a function, except that it has no |
| <code>return</code> |
| statement. It can however 'call' a model like a function. In the example above |
| <code>M(n)</code> starts a simulation with model <code>M</code> and the given value for <code>n</code>. |
| When the model exits by means of the <code>exit</code> statement (this is required!), |
| the computed exit |
| value of the (model) simulation is assigned to variable <code>v</code>. In the |
| experiment, this value can be used for post-processing, or in this case, get |
| printed as result value in a table.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-svg-visualization">SVG visualization</h3> |
| <div class="paragraph"> |
| <p>A Chi simulation often produces large amounts of textual output that you have |
| to process in order to understand the simulation result. Also for people |
| unfamiliar with the details of the simulated system, results are hard to |
| understand. A possible solution is to add a visualization of the system to the |
| simulator, that displays how the system behaves over time. Generally, it |
| looses some of the details, but it makes globally checking, and explaining of |
| the simulation much easier.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-the-svg-file-format">The SVG file format</h4> |
| <div class="paragraph"> |
| <p> |
| The <a href="http://www.w3.org/TR/SVG11/">Scalable Vector Graphics</a> (SVG) file |
| format is a widely used, royalty-free standard for two-dimensional vector |
| graphics, developed by the <a href="http://www.w3.org/">World Wide Web Consortium</a> |
| (W3C). SVG images consist of three types of objects: vector graphic shapes |
| (rectangles, circles, etc.), raster images, and text. The benefit of vector |
| images formats over raster image formats, is that raster images are created |
| with a fixed size, while vector images contain a description of the image and |
| can be rendered at any size without loss of quality.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| SVG image files are stored in an |
| <a href="http://en.wikipedia.org/wiki/XML">XML</a>-based file format. This means that |
| they can be edited with any text editor. However, it is often more convenient |
| to edit them with a drawing program that supports vector graphics, such as |
| <a href="http://www.adobe.com/products/illustrator.html">Adobe Illustrator</a> |
| or <a href="https://inkscape.org/">Inkscape</a>. |
| Most modern web browsers also support display of SVG images.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-visualization">Visualization</h4> |
| <div class="paragraph"> |
| <p>An SVG file has a tree structure; (graphical) elements are drawn in the same |
| order as they appear in the file. Elements further down in the file are thus |
| drawn on top of earlier elements. Also, each element has a position and size. |
| They may have other properties like a color or a gradient as well. There are |
| also 'administrative' elements, that can group, scale, or rotate parts of the |
| tree. The website of Jakob Jenkov has a very nice |
| <a href="http://tutorials.jenkov.com/svg">SVG Tutorial</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The SVG visualization by the Chi simulator exploits this structure. You access |
| the elements, and literally change the value of their properties or copy part |
| of the tree. The |
| <a href="http://xmlgraphics.apache.org/batik/">Apache Batik SVG Toolkit</a> |
| used for drawing the SVG image at the |
| screen notices the changes, and updates the displayed image.</p> |
| </div> |
| <div class="paragraph"> |
| <p>By updating the SVG tree every time when the state of the simulation changes, |
| you can display how a system evolves over time as an animated image.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tut-chapter-svg-example">SVG visualization example</h3> |
| <div class="paragraph"> |
| <p>To illustrate how to make an SVG visualization, a simple generator, buffer, |
| server, buffer, server, exit (GBSBSE) process line is used. |
| Below the generator and exit process definitions, and the model:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc G(chan! real to; real ptime): |
| int n = 0; |
| |
| while n < 100: |
| to!time; delay ptime; n = n + 1 |
| end |
| end |
| |
| proc E(chan? real from): |
| real x; |
| |
| while true: |
| from?x |
| end |
| end |
| |
| model M(): |
| list(3) chan real c; |
| list(2) chan real bs; |
| |
| run G(c[0], 1.1), |
| |
| B(0, c[0], bs[0], 3), |
| S(0, bs[0], c[1], 1.0, exponential(10.0), exponential(4.0)), |
| |
| B(1, c[1], bs[1], 3), |
| S(1, bs[1], c[2], 0.9, exponential(10.0), exponential(4.0)), |
| |
| E(c[2]); |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This system should be visualized, where the number of items in each buffer |
| should be displayed, and the state of each server (waiting for input, |
| processing, or waiting for output) should also be shown. |
| The <a href="./tutorial/gbse.svg">gbse.svg</a> |
| SVG file was made for this purpose, which |
| looks like</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./tutorial/sbb.png" alt="sbb"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>in an editor. The black rectangle represents the displayed area when the |
| visualization is running. It has two light-green rectangles in it, representing |
| the first and second buffer. The darker green rectangles inside will vary in height |
| to show the number of items in each buffer.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The circle at the left of the displayed area is never displayed in the |
| visualization. However, each server makes a copy of it, and places it at an |
| appropriate position in the display. While for two servers, one could just as |
| well perform the copying beforehand, as was done with the buffer graphics, but |
| the copying technique demonstrates how to scale visualizations for displaying |
| a larger number of items without a lot of effort.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-buffer-visualization">Buffer visualization</h4> |
| <div class="paragraph"> |
| <p>The left darker green rectangle has an <code>id</code> with value <code>buf0</code>, while the |
| right rectangle has an <code>id</code> containing <code>buf1</code>. Through the <code>id</code>, you can |
| access the properties, in this case, the height, for example |
| <code>attr buf0.height = 50</code>. This will set the <code>height</code> property of the SVG element |
| named <code>buf0</code> to <code>50</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The SVG visualization is not in the Chi model itself, it is an external |
| entity. You access it by opening a 'file', and writing the commands such as |
| above, as lines of text. |
| The code of the buffer is shown below.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc B(int num; chan? real from; chan! real to; int cap): |
| list real xs; |
| real x; |
| file f = open("SVG:gbse.svg", "w"); |
| |
| while true: |
| select size(xs) > 0, to!xs[0]: |
| xs = xs[1:]; |
| alt size(xs) < cap, from?x: |
| xs = xs + [x] |
| end |
| writeln(f, "attr buf%d.height = %d", num, size(xs) * 50); |
| end |
| close(f); |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It is a normal finite buffer process, except for three additional lines. The |
| first change is the <code>file f = open("SVG:gbse.svg", "w");</code> line. It creates a |
| connection to the SVG visualization due to the <code>SVG:</code> prefix of the file |
| name. <code>gbse.svg</code> is the name of the <code>.svg</code> file described above. The |
| 'file' should be opened for writing (since you will be sending commands to |
| it).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The second line is the |
| <code>writeln(f, "attr buf%d.height = %d", num, size(xs) * 50);</code> line, |
| which constructs a line of text to set the height of the darker |
| green rectangle to a value proportional to the number of elements in the |
| buffer. There is however a <a href="#svg-vertical-trickery">vertical coordinate trick</a> |
| needed to make it all work.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The third line is the <code>close(f);</code> line at the end of the process. It closes |
| the connection to the SVG visualization.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="svg-vertical-trickery">Vertical coordinates trickery</h4> |
| <div class="paragraph"> |
| <p>In SVG, the vertical coordinates run from the top of the screen to the bottom. |
| If you just draw a rectangle, its base position <code>(x,y)</code> is at the top-left |
| corner, with <code>width</code> going to the right of the screen, and <code>height</code> |
| towards the bottom. In other words, if you change the height of a simple |
| SVG rectangle by a program like the buffer process, the rectangle will grow |
| downwards instead of upwards!</p> |
| </div> |
| <div class="paragraph"> |
| <p>To make it grow upwards instead, you can</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>change both the <code>height</code> and the <code>y</code> coordinate of the rectangle at the |
| same time (you move the top of the rectangle in opposite direction with its |
| growth in height, so it looks like the rectangle grows upwards), or</p> |
| </li> |
| <li> |
| <p>flip the coordinate system of the rectangle by inserting a '180 degrees |
| rotation' transformation around the rectangle (you tell SVG to draw the |
| rectangle 'upside down', thus if you make it higher, it grows downwards, but |
| the flipped coordinate displays it as growth upwards.</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-server-process">Server process</h4> |
| <div class="paragraph"> |
| <p>The server process code looks as follows (ignore all the <code>writeln</code> lines for |
| now).</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc S(int num; chan? real from; chan! real to; real ptime; dist real up, down): |
| real event, x; |
| file f = open("SVG:gbse.svg", "w"); |
| |
| writeln(f, "copy server, , _x%d", num); |
| writeln(f, "absmove s_x%d (%d, 325)", num, num*420+150); |
| |
| while true: |
| event = time + sample up; |
| |
| # Up; process items. |
| while event > time: |
| writeln(f, "attr s_x%d.fill=yellow", num); |
| from?x; |
| writeln(f, "attr s_x%d.fill=green", num); |
| delay ptime; |
| writeln(f, "attr s_x%d.fill=magenta", num); |
| to!x; |
| end |
| |
| # Down; repair machine. |
| writeln(f, "attr s_x%d.fill=red", num); |
| delay sample down; |
| end |
| close(f); |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The server runs forever, starting with sampling how long it will be up |
| (<code>event = time + sample up</code>). Until it has reached that time |
| (<code>while event > time:</code>), it cycles through getting a product, processing |
| it for <code>uptime</code> time units, and sending the product out again. After a |
| few cycles, it has reached the <code>event</code> time, goes down, and waits for repair |
| (<code>delay sample down;</code>). Once the machine is repaired it starts again. |
| Visualization of the servers is discussed below.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-visualizing-the-server">Visualizing the server</h4> |
| <div class="paragraph"> |
| <p>A server is to be visualized with a circle that changes color depending on |
| what the server is doing. Yellow means it is waiting for a product, green |
| means processing, magenta means it is waiting to pass the finished product |
| to the next station, and red means the machine is down. After repairing, it |
| will continue processing.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As with the buffer process, the SVG visualization first opens a file |
| connection to the visualizer and the SVG file with the |
| <code>file f = open("SVG:gbse.svg", "w");</code> line. The filename of the <code>.svg</code> file |
| must be the same as with the buffer process (the visualizer can only show |
| one SVG file at a time).</p> |
| </div> |
| <div class="paragraph"> |
| <p>To display server state in the SVG visualization, we need a circle (called <em>arc</em> in |
| SVG) named <code>s_0</code> and <code>s_1</code> (for server 0 and server 1), positioned behind |
| its buffer. If there are not too many servers, and their number is fixed, one |
| could simply add those arcs to the SVG file and be done with it. |
| However, if you have a lot of servers, or you don’t know in advance how many |
| you will have, you cannot add them beforehand, you need to construct the SVG |
| elements 'on the fly'.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-copying-svg-elements">Copying SVG elements</h4> |
| <div class="paragraph"> |
| <p>For showing the server states, arcs named <code>s_0</code> and <code>s_1</code> are required in |
| SVG, which are created by copying and moving an SVG element. In this case, a |
| server is represented by just one SVG element, so you can copy and move that |
| one element. In general however, you want to copy several elements at the same |
| time (for example you might want to copy graphical elements to display a work |
| station, a server with its buffer).</p> |
| </div> |
| <div class="paragraph"> |
| <p>SVG has group elements, where you can put any number of (graphical) elements inside. |
| When you copy a group, you copy its entire contents. The <code>gbse.svg</code> file as |
| a group called <code>server</code>, containing an arc element called <code>s</code>. The server |
| group is copied and moved, which causes the arc element to be copied and moved |
| as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Inside an SVG file, each element must have a unique <code>id</code>, that is, each |
| element must have a unique name. When making a copy, the copied elements must |
| thus also be given a new name. The entire operation is performed with sending |
| a <code>copy [node], [prefix], [suffix]</code> command to the SVG visualizer. It |
| takes the element named <code>[node]</code>, and makes a full copy of it |
| (all elements inside it are also copied). For each copied element the |
| <code>[prefix]</code> is added in front of its <code>id</code> name, and the <code>[suffix]</code> is |
| added behind it.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>writeln(f, "copy server, , _x%d", num);</code> line in the Chi simulation |
| performs the copy operation for the servers. It takes the <code>server</code> group |
| element (which contains an <code>s</code> arc element), and adds nothing in front of |
| the names (there is no text between the first and the second comma). It |
| appends the names with <code>_x0</code> for the first server, and <code>_x1</code> for the |
| second server. The result is thus a copy of the <code>server</code> group, called |
| <code>server_x0</code> or <code>server_x1</code>, containing an arc <code>s_x0</code> respectively |
| <code>s_x1</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the copy command performs copying, and nothing else. Since the |
| copied element is exactly at the same position as the original, you don’t see |
| copies. This is however fixed by a move command explained next.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tut-moving-svg-elements">Moving SVG elements</h4> |
| <div class="paragraph"> |
| <p>You often want to position an SVG element at some point in the display. The |
| simplest way to do that is to change its <code>x</code> and <code>y</code> attributes, much |
| like the <code>height</code> attribute of the buffer rectangle was modified. Another |
| solution is to perform a relative move, using transform/translate.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This works, until you add a transformation element that changes the coordinate |
| system. Sometimes you do this consciously, for example adding a 'flip' |
| transformation to fix the vertical coordinates. At other times the SVG editor |
| may insert one, for example when you rotate or scale some part of the drawing.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Chi SVG visualizer has a <code>absmove [node] ([xpos], [ypos])</code> |
| command to handle this case. It computes a transformation to get the top-left |
| corner of the element named <code>[node]</code> at position (<code>[xpos]</code>, <code>[ypos]</code>). |
| Keep in mind that the vertical coordinate starts at the top, and goes down.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There are limitations to this command, in some case it may fail (see the |
| <a href="#ref-chapter-svg-visualization">reference manual</a> for details about the |
| command). It is recommended to use this command one time on an element to move |
| it to a known base position. Once it is at a known position, change the <code>x</code> |
| and <code>y</code> coordinates of a child element (to avoid disturbing the base |
| position), to move relative to that base position. Another solution is to |
| perform a relative move, using transform/translate.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the Chi simulation, the |
| <code>writeln(f, "absmove s_x%d (%d, 325)", num, num*420+150);</code> line moves the |
| copied <code>s_x0</code> and <code>s_x1</code> arcs to the right |
| position in the display.</p> |
| </div> |
| <div class="paragraph"> |
| <p>With the arcs in the right position in the display, the servers can display |
| their activities by changing the color of the <code>fill</code> attribute.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="ref-chapter-reference-manual">Chi Reference Manual</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This manual explains the allowed Chi language constructs and their semantics. |
| Topics discussed here are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#ref-chapter-global-definitions">Global definitions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-statements">Statements</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-expressions">Expressions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-standard-library">Standard library functions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-distributions">Distributions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-types">Types</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-lexical-syntax">Lexical syntax</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-migration">Model migration</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-svg-visualization">SVG visualization</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="ref-chapter-global-definitions">Global definitions</h3> |
| <div class="paragraph"> |
| <p>At global level, a Chi program is a sequence of definitions, as shown in the |
| following diagram</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/program.png" alt="program"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Each of the definitions is explained below. |
| The syntax diagram suggests that a <code>;</code> separator is obligatory between |
| definitions. The implementation is more liberal, you may omit the separator |
| when a definition ends with the <code>end</code> keyword. Also, it is allowed to use a |
| separator after the last definition.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The name of each global definition has to be unique.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-enum-definitions">Enumeration definitions</h4> |
| <div class="paragraph"> |
| <p>With enumerations, you create a new enumeration type containing a number of |
| names (called enumeration values). |
| The syntax is given below.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/enumdef.png" alt="enumdef"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The enumeration definitions start with the keyword <code>enum</code>, followed by a |
| sequence of definitions separated with a <code>,</code>. Each definition |
| associates an enumeration type name with a set of enumeration value names. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">enum FlagColours = {red, white, blue}, |
| MachineState = {idle, heating, processing};</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The enumeration type names act as normal types, and the enumeration values are |
| its values. The values have to be unique words.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, you can create a variable, and compare values like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">MachineState state = idle; |
| ... |
| while state != processing: |
| ... |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note that enumeration values have no order, you cannot increment or decrement |
| variables with an enumeration type, and you can only compare values with |
| equality and inequality.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-type-definitions">Type definitions</h4> |
| <div class="paragraph"> |
| <p>Type definitions allow you to assign a name to a type. By using a name instead |
| of the type itself, readability of the program increases.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/typedef.png" alt="typedef"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A type definition starts with the keyword <code>type</code>, followed by a number of |
| 'assignments' that associate a type name with a type, separated with a <code>,</code>. |
| For further details about type names and types, see <a href="#ref-chapter-types">Types</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type lot = real, |
| batch = list lot;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Here a <code>lot</code> type name is introduced that is implemented with a real number, |
| and a <code>batch</code> type name is created, which is a list of <code>lot</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These type names can be used at every place where you can use a type, for |
| example in variable declarations:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">batch xs; |
| lot x;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note that you cannot define use a type name in its own definition.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-constant-definitions">Constant definitions</h4> |
| <div class="paragraph"> |
| <p>Constant definitions allow you to give a name to a fixed value to enhance |
| readability. It also makes it easier to change a value between different |
| experiments. For example, if you have a constant named <code>speed</code>, and you want |
| to investigate how its value affects performance, you only have to change |
| value in the constant definition, instead of finding and changing numbers in |
| the entire program.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax of constant definitions is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/constantdef.png" alt="constantdef"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">const real speed = 4.8, |
| dict(string : list int) recipes = { "short" : [1,4,8], |
| "long" : [1,1,2,3,4,5] };</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Here, a <code>speed</code> real value is defined, and <code>recipes</code> value, a |
| dictionary of string to numbers. The constant names can be used at every point |
| where you can use an expression. See the <a href="#ref-chapter-expressions">Expressions</a> |
| section for details about expressions.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that you cannot use a constant name in its own definition.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-process-definitions">Process definitions</h4> |
| <div class="paragraph"> |
| <p>A process is an entity that shows behavior over time. A process definition is |
| a template for such a process. It is defined as follows</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/procdef.png" alt="procdef"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The definition starts with the keyword <code>proc</code> optionally followed by an exit |
| type. The name of the process definition, and its formal parameters concludes |
| the header. |
| In the body, the behavior is described using statements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Formal parameters are further explained in <a href="#ref-formal-parameters">Formal parameters</a>, |
| statements are explained in the <a href="#ref-chapter-statements">Statements</a> section.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(): |
| writeln("Hello"); |
| delay 15; |
| writeln("Finished") |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In the example, a process definition with the name <code>P</code> is defined, without |
| parameters, that outputs a line of text when starting, and another line of |
| text 15 time units later (and then finishes execution).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Creating and running a process is done with <a href="#ref-sub-process-statements">Sub-process statements</a> |
| (<code>start</code> or <code>run</code>) from another process or from a model.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If a process definition has no exit type specified, it may not use the |
| <code>exit</code> statement, nor may it start other processes that have an exit type |
| (see also <a href="#ref-sub-process-statements">Sub-process statements</a>). |
| Process definitions that have an exit type may use the <code>exit</code> statement |
| directly (see <a href="#ref-exit-statement">Exit statement</a> for details on the statement), and it |
| may start other processes without exit type, or with the same exit type.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Since values returned by the <code>exit</code> statement may get printed onto the |
| output, you may only use exit types that are printable. These are all the |
| 'normal' data values, from simple booleans to lists, sets, and dictionaries of |
| data values, but not channels, files, etc.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-model-definitions">Model definitions</h4> |
| <div class="paragraph"> |
| <p>A model behaves like a process, the only difference is that a model is run |
| as first process. It is the 'starting point' of a simulation. |
| As such, a model can only take data values which you can write down as literal |
| value. For example, giving it a channel or a process instance is not allowed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Like the process, a model also has a definition. It is defined below</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/modeldef.png" alt="modeldef"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax is exactly the same as process definitions explained in |
| <a href="#ref-process-definitions">Process definitions</a>, except it starts with |
| a <code>model</code> keyword instead. |
| A model can be started directly in the simulator (see |
| <a href="#tool-chapter-software-operation">Software operation</a>), or as part of an experiment, explained in |
| <a href="#tut-experiment">Simulating several scenarios</a>, and <a href="#ref-xper-definitions">Experiment definitions</a>. |
| If the model definition has no exit type, it may not use the <code>exit</code> |
| statement directly, nor may it start other processes that have an exit type. |
| If an exit type is specified, the model may use the <code>exit</code> statement |
| to end the model simulation (see <a href="#ref-sub-process-statements">Sub-process statements</a> for |
| details), and it may start other processes, either without exit type, or with |
| a matching exit type.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-function-definitions">Function definitions</h4> |
| <div class="paragraph"> |
| <p>In programs, computations are executed to make decisions. These computations |
| can be long and complex. A function definition attaches a name to a |
| computation, so it can be moved to a separate place in the file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Another common pattern is that the same computation is needed at several |
| places in the program. Rather than duplicating it (which creates consistency |
| problems when updating the computation), write it in a function definition, |
| and call it by name when needed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax of a function definition is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/funcdef.png" alt="funcdef"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In the syntax, the only thing that changes compared with the syntax in |
| <a href="#ref-process-definitions">Process definitions</a> or <a href="#ref-model-definitions">Model definitions</a> is the |
| additional <code>Type</code> node that defines the type resulting from the computation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>However, since a function represents a computation (that is, calculation of an |
| output value from input values) rather than having behavior over time, the |
| <code>Body</code> part has additional restrictions.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A computation is performed instantly, no time passes. This means that you |
| cannot delay or wait in a function.</p> |
| </li> |
| <li> |
| <p>A computation outputs a result. You cannot have a function that has no |
| result.</p> |
| </li> |
| <li> |
| <p>A computation is repeatable. That means if you run the |
| same computation again with the same input values, you get the same result |
| <em>every time</em>. Also in the environment of the function, there should be no |
| changes. This idea is known as <em>mathematical functions</em>.</p> |
| <div class="paragraph"> |
| <p>A consequence of having mathematical functions is that you cannot interact |
| with 'outside'. No querying of the current time, no communication, no select |
| statement, and no use of distributions.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Technically, this would also imply no input/output, but for practical |
| reasons this restriction has been lifted. However, as a general rule, avoid |
| using it.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-xper-definitions">Experiment definitions</h4> |
| <div class="paragraph"> |
| <p>An experiment can execute one or more model simulations, collect their exit |
| values, and combine them into a experiment result. |
| Its syntax is shown below</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/xperdef.png" alt="xperdef"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>An experiment definition has some function-like restrictions, like not being |
| able to use sub-process statements, no communication, and no use of time. On |
| the other hand, it does not return a value, and it can start model |
| simulations that have a non-void exit type (<a href="#ref-void-type">Void type</a> discusses the |
| void type).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The definition is very similar to other definitions. It starts with an |
| <code>xper</code> keyword, followed by the name of the definition. The name can be used |
| to start an experiment with the simulator (see <a href="#tool-chapter-software-operation">Software operation</a> |
| for details on starting the simulator). |
| If formal parameters are specified with the experiment definition (see |
| <a href="#ref-formal-parameters">Formal parameters</a> below), the experiment can be parameterized with |
| values. |
| Like models, an experiment can only take data values which you can write down |
| as literal value. For example, giving it a channel or a process instance is |
| not allowed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The body of an experiment is just like the body of a |
| <a href="#ref-function-definitions">Function definitions</a> (no interaction with processes or time). |
| Unlike a function, an experiment never returns a value with the |
| <a href="#ref-return-statement">Return statement</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The primary goal of an <code>xper</code> is to allow you to run one or more model |
| simulations that give an exit value. For this purpose, you can 'call' a model |
| like a function, for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">xper X(): |
| real total; |
| int n; |
| |
| while n < 10: |
| total = total + M(); |
| n = n + 1 |
| end |
| |
| writeln("Average is %.2f", total / 10); |
| end |
| |
| model real M(): |
| dist real d = exponential(7.5); |
| exit sample d; |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The model above is very short to keep the example compact. In practice it will |
| be larger, start several concurrent processes, and do a lengthy simulation |
| before it decides what the answer should be. |
| The experiment <code>X</code> makes ten calls to the model. Each call causes the |
| model to be run, until the model or one of its processes executes the <code>exit</code> |
| statement. At that point, the model and all its processes are killed, and the |
| value supplied with the exit statement becomes the return value of the model |
| call, adding it to <code>total</code>. |
| After the ten model simulations, the experiment outputs the average value of |
| all model simulations.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the called model (or one of its started processes) <strong>must</strong> end with |
| the <code>exit</code> statement, it is an error when the model ends by finishing its |
| last model statement.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-formal-parameters">Formal parameters</h4> |
| <div class="paragraph"> |
| <p>Definitions above often take values as parameter to allow customizing their |
| behavior during execution. |
| The definition of those parameters are called <em>formal parameters</em>, |
| The syntax of formal parameters is shown below</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/formalparms.png" alt="formalparms"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>As you can see, they are just variable declarations (explained in the |
| <a href="#ref-variable-declarations">Local variables</a> section), except you may not add an initial |
| value, since their values are obtained during use of the definition.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To a definition, the formal parameters act like variables. You may |
| use them just like other variables.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An example, where <code>int x, y; string rel</code> are the formal parameters of |
| process definition <code>P</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(int x, y; string rel): |
| writeln("%d %s %d", x, rel, x-y) |
| end |
| |
| ... |
| |
| run P(2, -1, "is less than");</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The formal parameters introduce additional variables in the process, that can |
| be just just like any other variable. Here, they are just printed to the |
| screen. |
| Elsewhere in the program, the definition gets used (instantiated), and a value |
| is supplied for the additional variables. Such values are called |
| <em>actual parameters</em>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ref-chapter-statements">Statements</h3> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| Statements express how a process or function in a system works. They define |
| what is done and in which order. Many statements use data for their decisions, |
| which is stored in local variables. The combined local variables and |
| statements are called 'body' with the following syntax.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/body.png" alt="body"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Data values available to the process are the global constants (see |
| <a href="#ref-constant-definitions">Constant definitions</a>) and enumeration values (see |
| <a href="#ref-enum-definitions">Enumeration definitions</a>). The formal parameters of the surrounding |
| process definition (explained in <a href="#ref-process-definitions">Process definitions</a>) or the |
| surrounding function definition (explained in <a href="#ref-function-definitions">Function definitions</a>) |
| are added as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Data storage that can be modified by the process are the local variables, |
| defined by the <code>VarDefinitions</code> block in the <code>Body</code> diagram |
| above (variable definitions are explained below in |
| <a href="#ref-variable-declarations">Local variables</a>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The data values and the modifiable data storage is used by the statements of |
| the <code>Body</code> in the path after <code>1</code>. For ease of reference they are grouped |
| by kind of statement as shown in the <code>Statement</code> diagram below.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/statement.png" alt="statement"> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <code>AssignmentStatement</code> is used to assign new values to the local |
| variables (and explained further in <a href="#ref-assignment-statement">Assignment statement</a>).</p> |
| </li> |
| <li> |
| <p>The <code>IterativeStatement</code> allows repeated execution of the same statements |
| by means of the <code>for</code> and <code>while</code> statements (further explained in |
| <a href="#ref-iterative-statements">Iterative statements</a>).</p> |
| </li> |
| <li> |
| <p>The <code>ChoiceStatement</code> allows selection on which statement to perform next |
| by means of the <code>if</code> statement (explained in <a href="#ref-choice-statement">Choice statement</a>).</p> |
| </li> |
| <li> |
| <p>The <code>run</code> and <code>start</code> statements of the <code>SubProcessStatement</code> group |
| (explained in <a href="#ref-sub-process-statements">Sub-process statements</a>) start new processes.</p> |
| </li> |
| <li> |
| <p>Communication with other processes using channels is done with send, |
| receive, and <code>select</code> statements in <code>CommunicationStatement</code> (explained |
| in <a href="#ref-communication-statements">Communication statements</a>)</p> |
| </li> |
| <li> |
| <p>Finally, the <code>OtherStatements</code> group contains several different |
| statements (explained further in <a href="#ref-other-statements">Other statements</a>). |
| The more commonly used statements in that group are the <code>delay</code> statement, |
| the <code>write</code> statement, and the <code>return</code> statement.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax diagram of <code>Body</code> states that statements are separated from each |
| other with a semi colon (<code>;</code>). The compiler allows more freedom. Semicolons |
| may be omitted before and after a <code>end</code> keyword, and a semi colon may be |
| added after the last statement.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-variable-declarations">Local variables</h4> |
| <div class="paragraph"> |
| <p>Local variables are introduced in a process or function using the following |
| syntax</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/vardef.png" alt="vardef"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Variable definitions start with a <code>Type</code> node (its syntax if explained in |
| <a href="#ref-chapter-types">Types</a>), followed by a sequence of variable names where |
| each variable may be initialized with a value by means of the <code>= Expression</code> |
| path. If no value is assigned, the variable gets the default value of the |
| type. Use a semi colon to terminate the sequence of new variables.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Next, another set of variables may be defined by going back to the start of |
| the diagram, and giving another <code>Type</code> node, or the diagram can be ended, |
| and the statements of the process or function can be given.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-assignment-statement">Assignment statement</h4> |
| <div class="paragraph"> |
| <p>An assignment statement assigns one or more values to the local variables. |
| Its syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/assignment_statement.png" alt="assignment statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The assignment statement computes the value of every <code>Expression</code> at the |
| right. If there is one expression, its value is also the value to assign. If |
| there are more expressions, a tuple value is constructed, combining all values |
| into one tuple (see <a href="#ref-tuple-expression">Tuple expression</a> for a discussion of tuple |
| values).</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| At the left, a number of <code>Addressable</code> blocks define where the computed |
| value is assigned to.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/addressable.png" alt="addressable"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>An <code>Addressable</code> is a variable. If the variable has a tuple type (see |
| <a href="#ref-tuple-type">Tuple type</a>) a field of the tuple may be assigned only using Path 1. |
| Similarly, if the variable is a list (see <a href="#ref-list-type">List type</a>) or a |
| dictionary (see <a href="#ref-dictionary-type">Dictionary type</a>) assignment is done to one |
| element by using Path 2. The <code>Expression</code> here is evaluated before <em>any</em> |
| assignment by this statement is performed. |
| Since selected elements may also have a type that allows selection, element |
| selection can be repeated.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After processing the element selections at the left, it is known where |
| values are assigned to. If there is exactly one addressable at the left, its |
| type must match with the type of the value at the right (which may be a |
| constructed tuple value as explained above). The value gets copied into the |
| variable (or in its element if one is selected). |
| If there are several addressable values at the left, the number of values must |
| be equal to the length of the tuple from the expression(s) at the right, and |
| each field of the right tuple must pair-wise match with the type of the |
| addressed element at the left. In the latter case, all assignments are done at |
| the same moment.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For a few examples, a number of variable declarations are needed:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">int x, y; |
| real r; |
| list(10) int xs; |
| tuple(real v; int w) t; |
| func tuple(real v; int w) (int) f; |
| |
| ... # Initialization of the variables omitted</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The variable declarations introduce integer variables <code>x</code> and <code>y</code>, a real |
| number variable <code>r</code>, a list of 10 integers <code>xs</code>, a tuple <code>t</code> with two |
| fields, and a function variable <code>f</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For reasons of clarity, initialization of the variables has been omitted. |
| Also, expressions at the right are simple values. However, you may use all |
| allowed expression operations explained in the next chapter |
| (<a href="#ref-chapter-expressions">Expressions</a>) to obtain a value to assign. |
| The first assignments show assignment of values to variables where there is |
| one explicit value for every assigned variable:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">x = 3; |
| t = f(y); |
| x, y = 4, 5; |
| xs[0], t.v = x+x, r;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The first assignment statement assigns 3 to <code>x</code>. The second assignment |
| assigns the return value of the function call <code>f(y)</code> to tuple <code>t</code>. The |
| third assignment assigns 4 to <code>x</code> and 5 to <code>y</code> at the same time. The |
| fourth assignment assigns the value of <code>x+x</code> to the first element of the |
| list <code>xs</code>, and the value of <code>r</code> to the <code>v</code> field of tuple <code>t</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The next assignments show combining or splitting of tuples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">t = r, y; |
| r, x = t; |
| r, x = f(y);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The first assignment assigns a new value to every field of tuple <code>t</code> |
| (<code>t.v</code> gets the value of <code>r</code>, while <code>t.w</code> gets the value of <code>y</code>). This |
| is called <em>packing</em>, it 'packs' the sequence of values into one tuple. The |
| opposite operation is demonstrated in the second assignment. The value of each |
| field of <code>t</code> is assigned to a separate variable. The types of the variables |
| at the left have to pair-wise match with the field types of the tuple at the |
| right. This assignment is called <em>unpacking</em>, it 'unpacks' a tuple value into |
| its separate elements. |
| The third assignment does the same as the second assignment, the difference is |
| that the value at the right is obtained from a function call. The origin of |
| the value is however irrelevant to the assignment statement.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To demonstrate the order of evaluation, the following assignment, under the |
| assumption that variable <code>x</code> holds value 3:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">x, xs[x-1] = 7, x+2;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The assignment first computes all values at the right. Since there are more |
| than one expression, they are combined into a tuple:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">x, xs[x-1] = (7, 5);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Next, the addressable values are calculated:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">x, xs[2] = (7, 5);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Finally the values are assigned, <code>x</code> gets a new value 7, while the third |
| element of <code>xs</code> gets the value of expression <code>x+2</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The expressions at the right as well as the expressions to select elements in |
| lists and dictionaries are always evaluated using values from before the |
| assignment.</p> |
| </div> |
| <div class="paragraph"> |
| <p>It is forbidden to assign the same variable or selected element more than |
| once:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">x, x = 3, 3 # Error, assigned 'x' twice. |
| xs[0], xs[1] = 0, 1 # Allowed, different selected elements. |
| xs[0], xs[x] = 0, 1 # Allowed if x != 0 .</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-iterative-statements">Iterative statements</h4> |
| <div class="paragraph"> |
| <p>The iterative statements are</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/iterative_statement.png" alt="iterative statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The Chi language has two statements for repeatedly executing a body (a |
| sequence of statements), a <code>while</code> statement and a <code>for</code> statement. |
| The former is the generic iterative statement, the latter simplifies the |
| common case of iterating over a collection of values.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>break</code> and <code>continue</code> statements change the flow of control in the |
| iterative statements.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-while-loop-statement">While loop statement</h5> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/while_statement.png" alt="while statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A while loop starts with the keyword <code>while</code> with a boolean condition. |
| Between the colon and the <code>end</code> keyword, the body of statements is given, |
| which is executed repeatedly.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Executing an iterative <code>while</code> statement starts with evaluating the boolean |
| condition. If it does not hold, the <code>while</code> statement ends (and execution |
| continues with the statement following the while statement). If the condition |
| holds, the statements in the body are executed from start to end (unless a |
| <code>break</code> or <code>continue</code> statement is executed, as explained below). |
| After the last statement has been executed, the <code>while</code> statement starts |
| again from the beginning, by evaluating the boolean condition again.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As an example, consider the following code:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">int s, i; |
| |
| while i < 10: |
| s = s + i |
| i = i + 1 |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>At first, the <code>i < 10</code> condition holds, and the body of the <code>while</code> |
| statement (two assignment statements) is executed. |
| After the body has finished, <code>i</code> has been incremented, but is still less |
| than <code>10</code>. The condition again holds, and the body is again executed, etc. |
| This process continues, until the final statement of the body increments <code>i</code> |
| to <code>10</code>. The condition does not hold, and execution of the <code>while</code> |
| statement ends.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-for-loop-statement">For loop statement</h5> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/for_statement.png" alt="for statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A common case for iterating is to execute some statements for every value in a |
| collection, for example a list:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list int xs; |
| int x; |
| int i; |
| |
| while i < size(xs): |
| x = xs[i] |
| ... |
| i = i + 1 |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where the <code>...</code> line represents the statements that should be executed for |
| each value <code>x</code> of the list. This is a very common case. Chi has a special |
| statement for it, the <code>for</code> statement. It looks like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list int xs; |
| |
| for x in xs: |
| ... |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This code performs the same operation, the statements represented with <code>...</code> |
| are executed for each value <code>x</code> from list <code>xs</code>, but it is shorter and |
| easier to write. |
| The advantages are mainly a reduction in the amount of code that must be |
| written.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>No need to create and update the temporary index variable <code>i</code>.</p> |
| </li> |
| <li> |
| <p>Variable <code>x</code> is declared implicitly, no need to write a full variable |
| declaration for it.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The behavior is slightly different in some circumstances.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>There is no index variable <code>i</code> that can be accessed afterwards.</p> |
| </li> |
| <li> |
| <p>When the <code>...</code> statements modify the source variable (<code>xs</code> in the |
| example), the <code>while</code> statement above uses the changed value. The <code>for</code> |
| statement continues to use the original value of the source variable.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Continuing use of the original source value can be an advantage or a |
| disadvantage, depending on the case. Using the new value gives more |
| flexibility, keeping the old value makes the <code>for</code> statement more |
| predictable, for example indices in the source variable stay valid.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Besides iterating over a list with <code>for</code>, you can also iterate over element |
| values of a set, or over key-value tuples of a dictionary, for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">dict(int:int) d = {1:10, 2:20}; |
| |
| for k, v in d: |
| writeln("%s: %s", k, v); |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When iterating over a set or a dictionary, the order of the elements is |
| undefined. In the above example, the first pair is either <code>(1, 10)</code> or |
| <code>(2, 20)</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-break-statement">Break statement</h5> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/break_statement.png" alt="break statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>break</code> statement may only be used inside the body of a loop statement. |
| When executed, the inner-most loop statement ends immediately, and execution |
| continues with the first statement after the inner-most loop statement. |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi"># Get a slice of the xs list, up-to the position of value x in the list |
| func get_until(list int xs, int x): |
| int index; |
| |
| while index < size(xs): |
| if xs[index] == x: |
| break |
| end; |
| index = index + 1 |
| end |
| return xs[:index] |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In the example, elements of the list <code>xs</code> are inspected until an element |
| with a value equal to <code>x</code> is found. At that point, the loop ends with the |
| <code>break</code> statement, and the function returns a slice of the list.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-continue-statement">Continue statement</h5> |
| <div class="paragraph"> |
| <p>Another common case when executing the body of an inner-most loop is that the |
| remaining statements of the body should be skipped this time. It can be |
| expressed with an <code>if</code> statement, but a <code>continue</code> statement is often |
| easier.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/continue_statement.png" alt="continue statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax of the continue statement is just <code>continue</code>. |
| An example to demonstrate its operation:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">int s; |
| |
| for x in xs: |
| if x mod 5 == 0: |
| continue |
| end |
| s = s + x |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>for</code> statement iterates over every value in list <code>xs</code>. When the value |
| is a multiple of 5 (expressed by the condition <code>x mod 5 == 0</code>), the |
| <code>continue</code> is executed, which skips the remaining statements of the body of |
| the <code>for</code> statement, namely the <code>s = s + x</code> assignment. The result is that |
| after executing the <code>for</code> statement, variable <code>s</code> contains the sum of all |
| values of the list that are not a multiple of 5.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-choice-statement">Choice statement</h4> |
| <div class="paragraph"> |
| <p>The choice statement, also known as 'if statement', selects one alternative |
| from a list based on the current value of a boolean expression. The |
| alternatives are tried in turn, until a boolean expression one an alternative |
| yields true. The statements of that alternative are executed, and the choice |
| statement ends. The choice statement also ends when all boolean expressions |
| yield false. The boolean expression of the <code>else</code> alternative always holds.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax of the choice statement is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/choice_statement.png" alt="choice statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Processing starts with evaluating the <code>BooleanExpression</code> behind the <code>if</code>. |
| If it evaluates to <code>true</code>, the statements behind it are executed, and the |
| choice statement ends.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the boolean expression behind the <code>if</code> does not hold, the sequence |
| <code>elif</code> alternatives is tried. Starting from the first one, each boolean |
| expression is evaluated. If it holds, the statements of that alternative are |
| performed, and the choice statement ends. If the boolean expression does not |
| hold, the next <code>elif</code> alternative is tried.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When there are no <code>elif</code> alternatives or when all boolean expressions of |
| the <code>elif</code> alternatives do not hold, and there is an <code>else</code> alternative, |
| the statements behind the <code>else</code> are executed and the choice statement ends. |
| If there is no <code>else</code> alternative, the choice statement ends without |
| choosing any alternative.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An example with just one alternative:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">if x == 1: |
| x = 2 |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>which tests for <code>x == 1</code>. If it holds, <code>x = 2</code> is performed, else no |
| alternative is chosen.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An longer example with several alternatives:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">if x == 1: |
| y = 5 |
| elif x == 2: |
| y = 6; x = 6 |
| else: |
| y = 7 |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This choice statement first tests whether <code>x</code> is equal to <code>1</code>. If it is, |
| the <code>y = 5</code> statement is executed, and the choice statement finishes. If the |
| first test fails, the test <code>x == 2</code> is computed. If it holds, the statements |
| <code>y = 6; x = 6</code> are performed, and the choice statement ends. If the second |
| test also fails, the <code>y = 7</code> statement is performed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The essential points of this statement are</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The choice is computed now, you cannot wait for a condition to become true.</p> |
| </li> |
| <li> |
| <p>Each alternative is tried from the top down, until the first expression |
| that yields true.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The second point also implies that for an alternative to be chosen, the |
| boolean expressions of all previous alternatives have to yield false.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the above example, while executing the <code>y = 7</code> alternative, you |
| know that <code>x</code> is neither <code>1</code> nor <code>2</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-sub-process-statements">Sub-process statements</h4> |
| <div class="paragraph"> |
| <p>The sub-process statements deal with creating and managing of new processes. |
| The statement may only be used in <a href="#ref-process-definitions">Process definitions</a> and |
| <a href="#ref-model-definitions">Model definitions</a>.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/subprocess_statement.png" alt="subprocess statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>RunStartStatement</code> block creates new processes (see |
| <a href="#ref-run-and-start-statements">Run and start statements</a> for details), while the <code>FinishStatement</code> |
| waits for a process to end (further explanation at <a href="#ref-finish-statement">Finish statement</a>).</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-run-and-start-statements">Run and start statements</h5> |
| <div class="paragraph"> |
| <p>The <code>run</code> and <code>start</code> commands take a sequence of process instance as |
| their argument.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/run_start.png" alt="run start"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Both statements start all instances listed in the sequence. The <code>start</code> |
| statement ends directly after starting the processes, while the <code>run</code> |
| statement waits until all the started instances have ended. |
| Using <code>run</code> is generally recommended for creating new processes.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| A process instance has the following syntax.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/process_instance.png" alt="process instance"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The elementary process instance is created using Path 1. It consists of a |
| process name (which must be one of the names of the |
| <a href="#ref-process-definitions">Process definitions</a>), followed by a sequence of actual parameters |
| for the process between parentheses. The number of actual parameters and their |
| types must match pair-wise with the number and type of the formal parameters |
| of the referenced process definition. |
| Channel directions of the formal parameters must be a sub-set of the channel |
| directions of the actual parameters.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The optional assignment of the process to a process variable (which must be of |
| type <code>inst</code>, see <a href="#ref-inst-type">Instance type</a>) allows for checking whether the |
| started process has ended, or for waiting on that condition in a <code>select</code> |
| statement (explained in <a href="#ref-select-statement">Select statement</a>), or with a <code>finish</code> |
| statement (explained in <a href="#ref-finish-statement">Finish statement</a>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">chan c; |
| inst p, q; |
| |
| run P(18, c), Q(19, c); |
| start p = P(18, c), q = Q(19, c);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>First two processes are completely run, namely the instances <code>P(18, c)</code>, and |
| <code>Q(19, c)</code>. When both have ended, the <code>start</code> statement is executed, which |
| starts the same processes, and assigned the <code>P</code> process instance to instance |
| variable <code>p</code> and the <code>Q</code> process instance to variable <code>q</code>. After |
| starting the processes, the <code>start</code> ends. Unless one of started processes |
| has already ended, in the statement following the <code>start</code>, three processes |
| are running, namely the process that executed the start statement, and the two |
| started process instances referenced by variables <code>p</code> and <code>q</code>. (There may |
| be more processes of course, created either before the above statements were |
| executed, or the <code>P</code> or <code>Q</code> process may have created more processes.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Path 2 of the <code>ProcessInstance</code> diagram is used to construct many new |
| processes by means of an <code>unwind</code> loop. |
| Each value in the <code>Expression</code> gets assigned to the iterator variable |
| sequence of <code>VariableName</code> blocks (and this may be done several times as the |
| syntax supports several <code>Expression</code> loops). For each combination of |
| assignments, the process instances behind the colon are created. The <code>end</code> |
| keyword denotes the end of the <code>unwind</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Typical use of <code>unwind</code> is to start many similar processes, for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list int xs = [1, 2] |
| |
| run |
| unwind i in range(5), |
| j in range(3), |
| x in xs: P(i, j, x) |
| end;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This <code>run</code> statement runs 5*3*2 processes: <code>P(0, 0, 1)</code>, |
| <code>P(0, 0, 2)</code>, <code>P(0, 1, 1)</code>, …​, <code>P(0, 2, 2)</code>, <code>P(1, 0, 1)</code>, …​, |
| <code>P(4, 2, 2)</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Both the <code>run</code> and the <code>start</code> statements can always instantiate new |
| processes that have no exit type specified. |
| (see <a href="#ref-process-definitions">Process definitions</a> for details about exit types in process |
| definitions). If the definition containing the sub-process statement has an |
| exit type, the statements can also instantiate processes with the same exit |
| type.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This requirement ensures that all exit statements in a model simulation give |
| exit values of the same type.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-finish-statement">Finish statement</h5> |
| <div class="paragraph"> |
| <p>The <code>finish</code> statement allows waiting for the end of a process instance. |
| The statement may only be used in <a href="#ref-process-definitions">Process definitions</a> and |
| <a href="#ref-model-definitions">Model definitions</a>. |
| Its syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/finish_statement.png" alt="finish statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Each process variable must be of type <code>inst</code> (see <a href="#ref-inst-type">Instance type</a> for |
| details). The statement ends when all referenced process instances have ended. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">chan bool c; |
| inst p, q; |
| |
| start p = P(18, c), q = Q(19, c); |
| finish p, q;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>During the <code>start</code> statement (see <a href="#ref-run-and-start-statements">Run and start statements</a>), instance |
| variables <code>p</code> and <code>q</code> get a process instance assigned (this may also |
| happen in different <code>start</code> statements). |
| The <code>finish</code> statement waits until both process instances have ended.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-communication-statements">Communication statements</h4> |
| <div class="paragraph"> |
| <p>Communication with another process is the only means to forward information |
| from one process to another processes, making it the primary means to create |
| co-operating processes in the modeled system. |
| The statement may only be used in <a href="#ref-process-definitions">Process definitions</a> and |
| <a href="#ref-model-definitions">Model definitions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All communication is point-to-point (from one sender to one receiver) and |
| synchronous (send and receive occur together). A communication often exchanges |
| a message (a value), but communication without exchange of data is also |
| possible (like waving 'hi' to someone else, the information being sent is 'I |
| am here', but that information is already implied by the communication itself). |
| The latter form of communication is called <em>synchronization</em>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Send and receive does not specify the remote process directly, instead a |
| channel is used (see <a href="#ref-channel-type">Channel type</a> and <a href="#ref-channel-expression">Channel expressions</a> |
| sections for more informations about channels and how to create them). |
| Using a channel increases flexibility, the same channel can be used by several |
| processes (allowing communication with one of them). Channels can also be |
| created and exchanged during execution, for even more flexibility.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Setting up a communication channel between two processes is often done in the |
| following way:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">chan void sync; # Synchronization channel |
| chan int dch; # Channel with integer number messages |
| |
| run P(sync, dch), Q(sync, dch);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In a parent process, two channels are created, a synchronization channel |
| <code>sync</code>, and a communication channel with data called <code>dch</code>. The channel |
| values are given to processes <code>P</code> and <code>Q</code> through their formal parameters.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The communication statements are</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/communication_statement.png" alt="communication statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The elementary communication statements for sending and receiving at a single |
| channel are the <a href="#ref-send-statement">Send statement</a> and the <a href="#ref-receive-statement">Receive statement</a>. |
| The <a href="#ref-select-statement">Select statement</a> is used for monitoring several channels and |
| conditions at the same time, until at least one of them becomes available.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-send-statement">Send statement</h5> |
| <div class="paragraph"> |
| <p>The send statement send signals or data away through a channel. |
| The statement may only be used in <a href="#ref-process-definitions">Process definitions</a> and |
| <a href="#ref-model-definitions">Model definitions</a>. |
| It has the following syntax:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/send_statement.png" alt="send statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The statement takes a channel value (derived from |
| <code>ChannelExpression</code>), and waits until another process can receive on the |
| same channel. When that happens, and the channel is a synchronization channel, |
| a signal 'Communication has occurred' is being sent, if the channel also |
| carries data, the <code>Expression</code> value is computed and sent to the other |
| process. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc P(chan void a, chan! int b): |
| a!; |
| b!21; |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Process <code>P</code> takes two parameters, a synchronization channel locally called |
| <code>a</code> and a outgoing channel called <code>b</code> carrying integer values. |
| In the process body, it first synchronizes over the channel stored in <code>a</code>, |
| and then sends the value <code>21</code> of the channel stored in <code>b</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-receive-statement">Receive statement</h5> |
| <div class="paragraph"> |
| <p>The receive statement receives signals or data from a channel. |
| The statement may only be used in <a href="#ref-process-definitions">Process definitions</a> and |
| <a href="#ref-model-definitions">Model definitions</a>. |
| It has the following syntax:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/receive_statement.png" alt="receive statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The statement takes a channel value (derived from the <code>ChannelExpression</code>), |
| and waits until another process can send on the same channel. For |
| synchronization channels, it receives just a signal that the communication has |
| occurred, for channels carrying data, the data value is received and stored in |
| the variable indicated by <code>Addressable</code>. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc Q(chan void a, chan int b): |
| int x; |
| |
| a?; |
| b?x; |
| writeln("%s", x); |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Process <code>Q</code> takes a synchronization channel called <code>a</code> and a data channel |
| for integer values called <code>b</code> as parameters. |
| The process first waits for a synchronization over channel <code>a</code>, and then |
| waits for receiving an integer value over channel <code>b</code> which is stored in |
| local variable <code>x</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-select-statement">Select statement</h5> |
| <div class="paragraph"> |
| <p>The <a href="#ref-send-statement">Send statement</a> and the <a href="#ref-receive-statement">Receive statement</a> wait for |
| communication over a single channel. In some cases, it is unknown which |
| channel will be ready first. Additionally, there may be time-dependent |
| internal activities that must be monitored as well. |
| The select statement is the general purpose solution for such cases. |
| The statement may only be used in <a href="#ref-process-definitions">Process definitions</a> and |
| <a href="#ref-model-definitions">Model definitions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Its syntax is:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/select_statement.png" alt="select statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The statement has one or more <code>SelectCondition</code> alternatives that are all |
| monitored. The first alternative is prefixed with <code>select</code> to denote it is a |
| the start of a select statement, the other alternatives each start with |
| <code>alt</code> (which is an abbreviation of 'alternative').</p> |
| </div> |
| <div class="paragraph"> |
| <p>The statement monitors all conditions simultaneously, waiting for at least one |
| to become possible. At that moment, one of the conditions is selected to be |
| executed, and the select statement ends.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax of a <code>SelectCondition</code> is:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/select_condition.png" alt="select condition"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In its simplest form, a <code>SelectCondition</code> is a <code>SelectAlternative</code> (taking |
| Path 1). At Path 2, the condition is eventually also an <code>SelectAlternative</code>, |
| but prefixed with an <code>unwind</code> construct, and with an additional <code>end</code> |
| keyword at the end to terminate the unwind.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The unwind construct allows for a compact notation of a large number of |
| alternatives that must be monitored. Examples are provided below.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/select_alternative.png" alt="select alternative"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Using Path 1, a <code>SelectAlternative</code> can be a <a href="#ref-send-statement">Send statement</a> or a |
| <a href="#ref-receive-statement">Receive statement</a>, which may optionally have a |
| <code>BooleanExpression</code> condition prefix. Path 2 allows for a condition without |
| a send or receive statement.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The alternative checks the condition and monitors the channel. If the |
| condition holds <em>and</em> the channel has a communication partner, the alternative |
| can be chosen by the select statement. (Of course, omitting a condition skips |
| the check, and not specifying a send or receive statement skips monitoring of |
| the channel.) |
| When an alternative is chosen by the select statement, the send or receive |
| statement are performed (if it was present). If additional statements were |
| given in the alternative using Path 3, they are executed after the |
| communication has occurred (if a send or receive was present).</p> |
| </div> |
| <div class="paragraph"> |
| <p>A few examples to demonstrate use of the select statement:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">timer t = timer(5.2); |
| |
| select |
| a? |
| alt |
| b!7: |
| writeln("7 sent") |
| alt |
| ready(t): |
| writeln("done") |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This select waits until it can receive a signal from channel <code>a</code>, it can |
| send value <code>7</code> over channel <code>b</code>, or until <code>ready(t)</code> holds (which |
| happens <code>5.2</code> time units after starting the <code>select</code>, see |
| <a href="#tut-using-timers">Timers</a> for details). If <code>b!7</code> was selected, the |
| <code>writeln("7 sent")</code> is executed after the communication over channel <code>b</code>. |
| If the <code>ready(t)</code> alternative is chosen, the <code>writeln("done")</code> is |
| executed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A buffer can be specified with:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list int xs; |
| int x; |
| |
| select |
| a?x: |
| xs = xs + [x] |
| alt |
| not empty(xs), b!xs[0]: |
| xs = xs[1:] |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The select either receives a value through channel <code>a</code>, or it sends the |
| first element of list <code>xs</code> over channel <code>b</code> if the list is not empty (the |
| condition must hold and the channel must be able to send an item at the same |
| time to select the second alternative).</p> |
| </div> |
| <div class="paragraph"> |
| <p>After communication has been performed, the first alternative appends the |
| newly received value <code>x</code> to the list (the received value is stored in <code>x</code> |
| before the assignment is executed). In the second alternative, the assignment |
| statement drops the first element of the list (which just got sent away over |
| channel <code>b</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>unwind</code> loop 'unwinds' alternatives, for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list(5) chan int cs; |
| int x; |
| |
| select |
| unwind i, c in enumerate(cs): |
| c?x: |
| writeln("Received %s from channel number %d", x, i) |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Here <code>cs</code> is a list of channels, for example <code>list(5) chan int cs</code>. (See |
| <a href="#ref-list-type">List type</a> for details about lists.) The <code>unwind</code> iterates over |
| the <code>enumerate(cs)</code> (see <a href="#ref-list-expression">List expressions</a> for details about |
| <code>enumerate</code>), assigning the index and the channel to local <code>i</code> and <code>c</code> |
| variables. The <code>SelectAlternative</code> uses the variables to express the actions |
| to perform (wait for a receive, and output some text saying that a value has |
| been received).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The above is equivalent to (if list <code>cs</code> has length 5):</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">select |
| cs[0]?x: |
| writeln("Received %s from channel number %d", x, 0) |
| alt |
| cs[1]?x: |
| writeln("Received %s from channel number %d", x, 1) |
| |
| ... |
| |
| alt |
| cs[4]?x: |
| writeln("Received %s from channel number %d", x, 4)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>unwind</code> however works for any length of list <code>cs</code>. In addition, the |
| <code>unwind</code> allows for nested loops to unfold for example |
| <code>list list bool ds</code>, or to send one of several values over one of several |
| channels.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-other-statements">Other statements</h4> |
| <div class="paragraph"> |
| <p>Finally, there are a number of other useful statements.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/other_statements.png" alt="other statements"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <a href="#ref-delay-statement">Delay statement</a> waits for the given amount of time units, |
| the <a href="#ref-write-statement">Write statement</a> outputs text to the screen or a file, |
| the <a href="#ref-close-statement">Close statement</a> closes a file, |
| the <a href="#ref-return-statement">Return statement</a> returns a value from a function. |
| the <a href="#ref-exit-statement">Exit statement</a> ends the execution of all processes, and |
| the <a href="#ref-pass-statement">Pass statement</a> does nothing.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-delay-statement">Delay statement</h5> |
| <div class="paragraph"> |
| <p>The <code>delay</code> statement is useful to wait some time. |
| The statement may only be used in <a href="#ref-process-definitions">Process definitions</a> and |
| <a href="#ref-model-definitions">Model definitions</a>. |
| Its syntax is:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/delay_statement.png" alt="delay statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>IntegerExpression</code> or <code>RealExpression</code> is evaluated, and is the |
| amount of time that the |
| statement waits. The value of the expression is computed only at the start, it |
| is not evaluated while waiting. Changes in its value has thus no effect. |
| A negative value ends the statement immediately, you cannot go back in time.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">delay 1.5 # Delay for 1.5 time units.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-write-statement">Write statement</h5> |
| <div class="paragraph"> |
| <p>The write statement is used to output text to the screen or to a file. |
| Its syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/write_statement.png" alt="write statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>format string</em> at 2 is a literal string value (further explained at |
| <a href="#ref-string-expression">String expressions</a>) which defines what gets written. |
| Its text is copied to the output, except for two types of patterns which are |
| replaced before being copied. Use of the <code>writeln</code> (write line) keyword |
| causes an additional <code>\n</code> to be written afterwards.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The first group of pattern are the back-slash patterns. They all start with |
| the <code>\</code> character, followed by another character that defines the character |
| written to the output. The back-slash patterns are listed in the table below.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Pattern</th> |
| <th class="tableblock halign-left valign-top">Replaced by</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>\n</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The new-line character (U+000A)</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>\t</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The tab character (U+0009)</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>\"</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The double-quote character (U+0022)</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>\\</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">The back-slash character (U+005C)</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The second group of patterns are the percent patterns. Each percent pattern |
| starts with a <code>%</code> character. It is (normally) replaced by the (formatted) |
| value of a corresponding expression listed after the format string (the first |
| expression is used as replacement for the first percent pattern, the second |
| expression for the second pattern, etc). How the value is formatted depends on |
| the <em>format specifier</em>, the first letter after the percent character. Between |
| the percent character and the format specifier may be a <em>format definition</em> |
| giving control on how the value is output.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The format definition consists of five parts, each part is optional.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>A <code>-</code> character, denoting alignment of the value to the left. Cannot be |
| combined with a <code>0</code>, and needs a <em>width</em>.</p> |
| </li> |
| <li> |
| <p>A <code>+</code> character, denoting the value with always be printed with a sign, |
| only for formatting decimal integers, and real numbers.</p> |
| </li> |
| <li> |
| <p>A <code>0</code> character, denoting the value will be prefixed with zeros, only for |
| integer numbers. Cannot be combined with <code>-</code>, and needs a <em>width</em>.</p> |
| </li> |
| <li> |
| <p>A <em>width</em> as decimal number, denoting the minimal amount of space used for |
| the value. The value will be padded with space (or zeros if the <code>0</code> part |
| has been specified).</p> |
| </li> |
| <li> |
| <p>A <code>.</code> and a <em>precision</em> as decimal number, denoting the number of digits |
| to use for the fraction, only for real numbers.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The format definition is a single letter, the table below lists them and their |
| function.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Definition</th> |
| <th class="tableblock halign-left valign-top">Description</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>b</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Output boolean value.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>d</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Output integer value as decimal number.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>x</code>, <code>X</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Output integer value as hexadecimal number.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>f</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Output real value as number with a fraction.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>e</code>, <code>E</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Output real value in exponential notation.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>g</code>, <code>G</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Output real value either as <code>f</code> or as <code>e</code> (<code>E</code>) depending on the value</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>s</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Output value as a string (works for every printable value)</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>%</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Output a <code>%</code> character</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-close-statement">Close statement</h5> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/close_statement.png" alt="close statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>close</code> statement takes a value of type <code>file</code> as argument (see |
| <a href="#ref-file-type">File type</a> for details about the file type). It closes the given |
| file, which means that the file is no longer available for read or write. In |
| case data was previously written to the file, the <code>close</code> statement ensures |
| that the data ends up in the file itself.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that a close of a file is global in the system, none of the processes can |
| use the file any longer.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In <a href="#tut-reading-from-file">Reading from a file</a> and <a href="#tut-writing-to-file">Writing to a file</a>, use of the |
| close statement is shown.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-return-statement">Return statement</h5> |
| <div class="paragraph"> |
| <p>The return statement may only be used in a <a href="#ref-function-definitions">Function definitions</a>. |
| Its syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/return_statement.png" alt="return statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The statement starts with a <code>return</code> keyword, followed by one or more |
| (comma-separated) expressions that form the value to return to the caller of |
| the function.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The value of the expressions are calculated, and combined to a single return |
| value. The type of the value must match with the return type of the function. |
| Execution of the function statements stops (even when inside a loop or in an |
| alternative of an <code>if</code> statement), and the computed value is returned to the |
| caller of the function.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">return 4 # Return integer value 4 to the caller. |
| |
| return true, 3.7 # Return value of type tuple(bool b; real r).</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-exit-statement">Exit statement</h5> |
| <div class="paragraph"> |
| <p>The <code>exit</code> statement may only be used in <a href="#ref-process-definitions">Process definitions</a> and |
| <a href="#ref-model-definitions">Model definitions</a>. Its syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/exit_statement.png" alt="exit statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The exit statement allows for immediately stopping the current model |
| simulation. The statement may be used in <a href="#ref-process-definitions">Process definitions</a> and |
| <a href="#ref-model-definitions">Model definitions</a>. If arguments are provided, they become the exit |
| value of the model simulation. Such values can be processed further in an |
| <a href="#tut-experiment">Simulating several scenarios</a>, see also <a href="#ref-xper-definitions">Experiment definitions</a> on how to run a |
| model in an experiment.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The type of the combined arguments must match with the exit type of the |
| process or model that uses the statement. If no arguments are given, the exit |
| type must be a <code>void</code> type (see also <a href="#ref-void-type">Void type</a>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>If an experiment is running, execution continues by returning from the model |
| instantiation call. Otherwise, the simulation as a whole is terminated.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-pass-statement">Pass statement</h5> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/pass_statement.png" alt="pass statement"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>pass</code> statement does nothing. Its purpose is to act as a place holder |
| for a statement at a point where there is nothing useful to do (for example to |
| make an empty process), or to |
| explicitly state nothing is being done at some point:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">if x == 3: |
| pass |
| else: |
| x = x + 1 |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Here, <code>pass</code> is used to explicitly state that nothing is done when <code>x == 3</code>. |
| Such cases are often a matter of style, usually it is possible to rewrite |
| the code and eliminate the <code>pass</code> statement.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| </p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ref-chapter-expressions">Expressions</h3> |
| <div class="paragraph"> |
| <p>Expressions are computations to obtain a value. |
| The generic syntax of an expression is shown below.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/generic_expression.png" alt="generic expression"> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>As shown in Path 1, a name may be used in an expression. It must refer to a |
| value that can be used in an expression. |
| Names are explained further at <a href="#ref-lexical-names">Names</a>.</p> |
| <div class="paragraph"> |
| <p>The first four entries are quite normal, function names can be used for |
| variables with a function type (see <a href="#ref-function-type">Function type</a>) and process |
| names for variables with a process type (see <a href="#ref-process-type">Process type</a>). The |
| latter two are mainly useful as actual parameters of functions or processes.</p> |
| </div> |
| </li> |
| <li> |
| <p>Path 2 states that you can write parentheses around an expression. Its main |
| use is to force a different order of applying the unary and binary operators |
| (see <a href="#ref-operator-priorities">Operator priorities</a>). Parentheses may also be used to |
| clarify the meaning of a complicated expression.</p> |
| </li> |
| <li> |
| <p>Path 3 gives access to the other parts of expressions. |
| <a href="#ref-typed-expression">Typed expressions</a> gives the details about typed expressions.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-typed-expression">Typed expressions</h4> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/typed_expression.png" alt="typed expression"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The number of operators in expressions is quite large. Also, each node has an |
| associated type, and the allowed operators depend heavily on the types of the |
| sub-expressions. To make expressions easier to access, they have been split. |
| If possible the (result) type is leading, but in some cases (like the |
| <code>ReadExpression</code> for example) this is not feasible.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The expressions with a boolean type are denoted by the <code>BooleanExpression</code> |
| block and explained further in <a href="#ref-boolean-expression">Boolean expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with an integer type are denoted by the <code>IntegerExpression</code> |
| block and explained further in <a href="#ref-integer-expression">Integer expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a real number type are denoted by the <code>RealExpression</code> |
| block and explained further in <a href="#ref-real-expression">Real number expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a string type are denoted by the <code>StringExpression</code> |
| block and explained further in <a href="#ref-string-expression">String expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a list type are denoted by the <code>ListExpression</code> |
| block and explained further in <a href="#ref-string-expression">String expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a set type are denoted by the <code>SetExpression</code> |
| block and explained further in <a href="#ref-set-expression">Set expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a dictionary type are denoted by the |
| <code>DictionaryExpression</code> block and explained further in |
| <a href="#ref-dictionary-expression">Dictionary expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a tuple type are denoted by the <code>TupleExpression</code> |
| block and explained further in <a href="#ref-tuple-expression">Tuple expression</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a file handle type are denoted by the |
| <code>FileExpression</code> block and explained further in |
| <a href="#ref-file-expression">File handle expressions</a>.</p> |
| </li> |
| <li> |
| <p>The function to read values from an external source is shown in the |
| <code>ReadExpression</code> block, and further discussed in |
| <a href="#ref-read-expression">Read expression</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a timer type are denoted by the <code>TimerExpression</code> |
| block and explained further in <a href="#ref-timer-expression">Timer expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a channel type are denoted by the <code>ChannelExpression</code> |
| block and explained further in <a href="#ref-channel-expression">Channel expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a distribution type are denoted by the |
| <code>DistributionExpression</code> block and explained further |
| in <a href="#ref-distribution-expression">Distribution expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with a process type are denoted by the <code>ProcessExpression</code> |
| block and explained further in <a href="#ref-process-expression">Process expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions with an instance type are denoted by the |
| <code>InstanceExpression</code> block and explained further in |
| <a href="#ref-instance-expression">Instance expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions that convert one type to another are denoted by the |
| <code>CastExpression</code> block, and explained further in |
| <a href="#ref-cast-expression">Cast expressions</a>.</p> |
| </li> |
| <li> |
| <p>The expressions that perform a function call are denoted by the |
| <code>FunctionCallExpression</code> block, and explained further in |
| <a href="#ref-functioncall-expression">Function call expressions</a>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-enum-value-expression">Enumeration value</h4> |
| <div class="paragraph"> |
| <p>Enumeration values may be used as literal value in an expression</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/enum_value.png" alt="enum value"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="#ref-enum-definitions">Enumeration definitions</a> for a discussion about enumeration definitions |
| and enumeration values.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There are two binary operators for enumeration values.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>lhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type <strong>rhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>==</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>E</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>E</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for equality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>!=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>E</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>E</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for inequality</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Two enumeration values from the same enumeration definition <strong>E</strong> can be |
| compared against each other for equality (or in-equality). |
| Example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">enum FlagColours = {red, white, blue}; |
| |
| ... |
| |
| bool same = (red == white);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-boolean-expression">Boolean expressions</h4> |
| <div class="paragraph"> |
| <p>The literal values for the boolean data type are</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/bool_expression.png" alt="bool expression"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The values <code>true</code> and <code>false</code> are also the only available values of the |
| boolean data type.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>not</code> operation is the only boolean unary operator.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>op</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>not</code> <strong>op</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>op</strong> value is inverted.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The <code>and</code>, the <code>or</code>, and the equality tests are available for boolean |
| values.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>lhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type <strong>rhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>and</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Both operands hold</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>or</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">At least one operand holds</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>==</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for equality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>!=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for inequality</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-integer-expression">Integer expressions</h4> |
| <div class="paragraph"> |
| <p>The syntax of an integer literal number is (at character level)</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/literal_integer_number.png" alt="literal integer number"> |
| </div> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| This diagram works at lexical level (at the level of single |
| characters), white space or comments are not allowed between elements in this |
| diagram. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>An integer number is either <code>0</code>, or a sequence of decimal digits, starting |
| with a non-zero digit.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There are two unary operators on integer numbers.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>op</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code> <strong>op</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>op</strong> value is negated.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+</code> <strong>op</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>op</strong> value is copied.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>With the unary <code>-</code> operation, the sign of the operand gets toggled. The |
| <code>+</code> unary operation simply copies its argument.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There are many binary operations for integer numbers, see the table below.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>lhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type <strong>rhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>+</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Integer addition</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>-</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Integer subtraction</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>*</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Integer multiplication</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>/</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real division</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>div</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Integer divide operation</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>mod</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Modulo operation</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>^</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Power operation</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code><</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for less than</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code><=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for less or equal</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>==</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for equality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>!=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for inequality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>>=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for bigger or equal</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>></code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for bigger than</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The divide operator <code>/</code> and the power operator <code>^</code> always gives a real |
| result, integer division is performed with <code>div</code>. The operation always rounds |
| down, that is <strong>a</strong> <code>div</code> <strong>b</strong> == <code>floor</code>(<strong>a</strong> <code>/</code> <strong>b</strong>) for all integer |
| values <strong>a</strong> and <strong>b</strong>. The <code>mod</code> operation returns the remainder from the |
| <code>div</code>, that is <strong>a</strong> <code>mod</code> <strong>b</strong> == <strong>a</strong> - <strong>b</strong> * (<strong>a</strong> <code>div</code> <strong>b</strong>). The |
| table below gives examples. For clarity, the sign of the numbers is explicitly |
| added everywhere.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3334%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Example</th> |
| <th class="tableblock halign-left valign-top">Result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+7 div +4</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">+1</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>floor(+7/+4) = floor(+1.75) = +1</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+7 mod +4</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">+3</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+7 - +4 * (+7 div +4) = +7 - +4 * +1 = +7 - +4 = +3</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+7 div -4</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">-2</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>floor(+7/-4) = floor(-1.75) = -2</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+7 mod -4</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">-1</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+7 - -4 * (+7 div -4) = +7 - -4 * -2 = +7 - +8 = -1</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-7 div +4</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">-2</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>floor(-7/+4) = floor(-1.75) = -2</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-7 mod +4</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">+1</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-7 - +4 * (-7 div +4) = -7 - +4 * -2 = -7 - -8 = +1</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-7 div -4</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">+1</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>floor(-7/-4) = floor(+1.75) = +1</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-7 mod -4</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">-3</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-7 - -4 * (-7 div -4) = -7 - -4 * +1 = -7 - -4 = -3</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The Chi simulator uses 32 bit integer variables, which means that only values |
| from -2,147,483,647 to 2,147,483,647 (with an inclusive upper bound) can be |
| used. Using a value outside the valid range will yield invalid results. |
| Sometimes such values are detected and reported.</p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| The technical minimum value for integers is -2,147,483,648, but this |
| number cannot be entered as literal value due to parser limitations. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-real-expression">Real number expressions</h4> |
| <div class="paragraph"> |
| <p>Real numbers are an important means to express values in the contiguous domain. |
| The type of a real number expression is a <code>real</code> type, see |
| <a href="#ref-real-type">Real type</a> for more information about the type. |
| The syntax of real number values is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/real_number_values.png" alt="real number values"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>There are two ways to construct real numbers, by writing a literal real |
| number, or by using <code>time</code> which returns the current time in the model.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax of a literal real number (at character level) is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/lexical_real_number.png" alt="lexical real number"> |
| </div> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| This diagram works at lexical level (at the level of single |
| characters), white space or comments are not allowed between elements in this |
| diagram. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>A literal real number starts with one or more digits, and then either a dot or |
| an exponent. In the former case, an exponent is allowed as well. Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">3.14 |
| 0.314e1 |
| 314E-2</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A real number <strong>always</strong> has either a dot character, or an exponent notation in |
| the number.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Many of the integer operations can also be performed on real numbers. The unary |
| operators are the same, except for the type of the argument.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>op</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>-</code> <strong>op</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>op</strong> value is negated.</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+</code> <strong>op</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>op</strong> value is copied.</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>With the unary <code>-</code> operation, the sign of the operand gets toggled. The |
| <code>+</code> unary operation simply copies its argument.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The binary operators on real numbers is almost the same as the binary operators |
| on integer numbers. Only the <code>div</code> and <code>mod</code> operations are not here.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>lhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type <strong>rhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>+</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Addition</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>-</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Subtraction</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>*</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Multiplication</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>/</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Real division</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>^</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Power operation</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code><</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for less than</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code><=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for less or equal</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>==</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for equality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>!=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for inequality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>>=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for bigger or equal</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>></code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int,real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for bigger than</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>With these operations, one of the operands has to be a real number value, |
| while the other operand can be either an integer value or a real number value.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The standard library functions for real numbers contain a lot of math |
| functions. They can be found in <a href="#ref-real-stdlib">Real number functions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Chi simulator uses <a href="http://en.wikipedia.org/wiki/IEEE_floating_point">64-bit IEEE 754 floating point</a> |
| numbers to represent real |
| number values. Using a value outside the valid range of this format will yield |
| invalid results. Sometimes such values are detected and reported.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-string-expression">String expressions</h4> |
| <div class="paragraph"> |
| <p>Strings are sequences of characters. Their most frequent use is to construct |
| text to output to the screen. A string literal is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/lexical_string_literal.png" alt="lexical string literal"> |
| </div> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| This diagram works at lexical level (at the level of single |
| characters), white space or comments are not allowed between elements in this |
| diagram. |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>A string literal starts with a quote character <code>"</code>, and ends with another |
| quote character. In between, you may have a sequence of characters. Most |
| characters can be written literally (eg write a <code>a</code> to get an 'a' in the |
| string). The exceptions are a backslash <code>\</code>, a quote <code>"</code>, a TAB, and a NL |
| (newline) character. For those characters, write a backslash, followed by |
| <code>\</code>, <code>"</code>, <code>t</code>, or <code>n</code> respectively. (A TAB character moves the cursor |
| to the next multiple of 8 positions at a line, a NL moves the cursor to the |
| start of the next line.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>Strings have the following binary expressions.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>lhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type <strong>rhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>+</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Concatenation</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>[</code> <strong>rhs</strong> <code>]</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Element access</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>[</code> <strong>low</strong> <code>:</code> <strong>high</strong> <code>]</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int, int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Slicing with step <code>1</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>[</code> <strong>low</strong> <code>:</code> <strong>high</strong> <code>:</code> <strong>step</strong> <code>]</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int, int, int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Slicing</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code><</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for less than</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code><=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for less or equal</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>==</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for equality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>!=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for inequality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>>=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for bigger or equal</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>></code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for bigger than</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The <strong>concatenation</strong> operator joins two strings (<code>"a" + "bc"</code> gives <code>"abc"</code>).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>element access</strong> and <strong>slicing</strong> operators use numeric indices to denote a |
| character in the string. First character has index value <code>0</code>, second |
| character has index <code>1</code>, and so on. Negative indices count from the back of |
| the string, for example index value <code>-1</code> points to the last character of a |
| string. |
| Unlike lists, both the <strong>element access</strong> and the <strong>slicing</strong> operators return a |
| string. The former constructs a string with only the indicated character, |
| while the latter constructs a sub-string where the first character is at index |
| <strong>low</strong>, the second character at index <strong>low</strong> + <strong>step</strong>, and so on, until |
| index value <strong>high</strong> is reached or crossed. That final character is not included |
| in the result (that it, the <strong>high</strong> boundary is excluded from the result). |
| If <strong>low</strong> is omitted, it is 0, if <strong>high</strong> is omitted, it is the length of the |
| string (<code>size(</code> <strong>lhs</strong> <code>)</code>). If <strong>step</strong> is omitted, it is <code>1</code>. |
| A few examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">string s = "abcdef"; |
| |
| s[4] # results in "e" |
| s[2:4] # results in "cd" |
| s[1::2] # results in "bdf" |
| s[-1:0:-2] # results in "fdb" |
| s[-1:-7:-1] # results in "fedcba" |
| s[:4] # results in "abcd" |
| s[-1:] # results in "f" (from the last character to the end)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In the comparison operations, strings use lexicographical order.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There are also a few standard library functions on strings, see |
| <a href="#ref-string-stdlib">String functions</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that length of the string is not the same as the number of characters |
| needed for writing the string literal:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">size("a") # results in 1, string is 1 character long (namely 'a'). |
| size("\n") # results in 1, string contains one NL character.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-list-expression">List expressions</h4> |
| <div class="paragraph"> |
| <p>Lists are very versatile data structures, the Chi language has a large number |
| of operations and functions for them.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The most elementary list expression is a literal list. It has the following |
| syntax.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/literal_list.png" alt="literal list"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The first line shows the syntax of an empty list. The <code>Type</code> block denotes |
| the element type of the list, for example <code><int>[]</code> is an empty list of |
| integer values.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The second line shows how to write a non-empty literal list value. It is a |
| comma-separated sequence of expressions surrounded by square brackets. |
| The type of all expressions must be the same, and this is also the element type |
| of the list.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Some examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list int xs; |
| list int ys = <int>[]; |
| list int zs = [1, 4, 28];</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Variable <code>ys</code> is assigned an empty list with integer element type. |
| Since an empty list is the default value of a variable, <code>xs</code> has the same |
| value. Variable <code>zs</code> is initialized with a list holding three elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Two list values are equal when they have the same number of element values, |
| and each value is pair-wise equal.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Lists have no unary operators, the binary operators of lists are</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>lhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type <strong>rhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>[</code> <strong>rhs</strong> <code>]</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Element access</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>[</code> <strong>low</strong> <code>:</code> <strong>high</strong> <code>]</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int, int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Slicing with step <code>1</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>[</code> <strong>low</strong> <code>:</code> <strong>high</strong> <code>:</code> <strong>step</strong> <code>]</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int, int, int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Slicing</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>+</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Concatenation</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>-</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">List subtraction</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>==</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for equality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>!=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for inequality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>in</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Element test</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The <strong>element access</strong> operator '<strong>lhs</strong> <code>[</code> <strong>rhs</strong> <code>]</code> ' indexes with |
| zero-based positions, for example <code>xs[0]</code> |
| retrieves the first element value, <code>xs[1]</code> retrieves the second value, etc. |
| Negative indices count from the back of the list, <code>xs[-1]</code> retrieves the last |
| element of the list (that is, <code>xs[size(xs)-1]</code>), <code>xs[-2]</code> gets the second |
| to last element, ect. It is not allowed to index positions that do not exist. |
| Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list int xs = [4, 7, 18]; |
| int x; |
| |
| x = xs[0]; # assigns 4 |
| x = xs[2]; # assigns 18 |
| x = xs[-1]; # assigns 18 |
| x = xs[-2]; # assigns 7 |
| |
| xs[2] # ERROR, OUT OF BOUNDS |
| xs[-4] # ERROR, OUT OF BOUNDS</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>slicing</strong> operator '<strong>lhs</strong> <code>[</code> <strong>low</strong> <code>:</code> <strong>high</strong> <code>]</code> ' extracts |
| (sub-)lists from the <strong>lhs</strong> source. The <strong>low</strong> and <strong>high</strong> index expressions may |
| be omitted (and default to <code>0</code> respectively <code>size(</code> <strong>lhs</strong> <code>)</code> in that |
| case). As with element access, negative indices count from the back of the |
| list. The result is the list of values starting at index <strong>low</strong>, and up to but |
| not including the index <strong>high</strong>. If the <strong>low</strong> value is higher or equal to |
| <strong>high</strong>, the resulting list is empty. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list int xs = [4, 7, 18]; |
| list int ys; |
| |
| ys = xs[0:2]; # assigns [4, 7] |
| ys = xs[:2]; # == xs[0:2] |
| ys = xs[1:]; # == xs[1:3], assigns [7, 18] |
| ys = xs[:]; # == xs[0:3] == xs |
| |
| ys = xs[1:2]; # assigns [7] (note, it is a list!) |
| ys = xs[0:0]; # assigns <int>[] |
| ys = xs[2:1]; # assigns <int>[], lower bound too high |
| ys = xs[0:-1]; # == xs[0:2]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>slicing</strong> operator with the <strong>step</strong> expression (that is, the expression with |
| the form '<strong>lhs</strong> <code>[</code> <strong>low</strong> <code>:</code> <strong>high</strong> <code>:</code> <strong>step</strong> <code>]</code> ') can also |
| skip elements (with step values other than <code>1</code>) and traverse lists from back |
| to front (with negative step values). Omitting the <strong>step</strong> expression or using |
| <code>0</code> as its value, uses the step value <code>1</code>. This extended form does not |
| count from the back of the list for negative indices, since the <strong>high</strong> value |
| may need to be negative with a negative step size.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The first element of the result is at '<strong>lhs</strong> [<strong>low</strong> ]'. The |
| second element is at '<strong>lhs</strong> [<strong>low</strong> + <strong>step</strong> ]', the third element at |
| '<strong>lhs</strong> [<strong>low</strong> + 2 * <strong>step</strong> ]' and so on. For a positive <strong>step</strong> value, |
| the index of the last element is the highest value less than <strong>high</strong>, for a |
| negative <strong>step</strong> value, the last element is the smallest index bigger than |
| <strong>high</strong> (that is, boundary <strong>high</strong> is excluded from the result). |
| The (sub-)list is empty when the first value ('<strong>lhs</strong> [ <strong>low</strong> ]') already |
| violates the conditions of the <strong>high</strong> boundary.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list int xs = [4, 7, 18]; |
| list int ys; |
| |
| ys = xs[::2]; # == xs[0:3:2], assigns [4, 18] |
| ys = xs[::-1]; # == xs[2:-1:-1], assigns [18, 7, 4]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>With the latter example, not that the <code>-1</code> end value in <code>xs[2:-1:-1]</code> |
| really means index <code>-1</code>, it is <strong>not</strong> rewritten!!</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>concatenation</strong> operator <code>+</code> 'glues' two lists together by constructing a |
| new list, copying the value of the <strong>lhs</strong> list, and appending the values of the |
| <strong>rhs</strong>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">[1, 2] + [3, 4] == [1, 2, 3, 4] |
| <int>[] + [1] == [1] |
| [5] + <int>[] == [5]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>subtraction</strong> operator <code>-</code> subtracts two lists. It copies the <strong>lhs</strong> list, |
| and each element in the <strong>rhs</strong> list is searched in the copy, and the left-most |
| equal value is deleted. Searched values that do not exist are silently ignored. |
| The result of the operation has the same type as the <strong>lhs</strong> list. |
| Some examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">[1, 2, 4, 2] - [4] # results in [1, 2, 2], 4 is removed. |
| [1, 2, 4, 2] - [6] # results in [1, 2, 4 2], 6 does not exist. |
| [1, 2, 4, 2] - [1, 4] # results in [2, 2], 1 and 4 are removed. |
| [1, 2, 4, 2] - [2] # results in [1, 4, 2], first 2 is removed. |
| [1, 2, 4, 2] - [2, 2] # results in [1, 4]. |
| [1, 2, 4, 2] - [2, 2, 2] # results in [1, 4], no match for the 3rd '2'.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>element test</strong> operator <code>in</code> tests whether the value <strong>lhs</strong> exists in list |
| <strong>rhs</strong>. This operation is expensive to compute, if you need this operation |
| frequently, consider using a set instead. |
| Some examples of the element test operation:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">1 in [1, 2, 3] == true |
| 4 in [1, 2, 3] == false # there is no 4 in [1, 2, 3] |
| [1] in [[2], [1]] == true |
| [2, 1] in [[1, 2]] == false # [2, 1] != [1, 2] |
| <int>[] in <list int>[] == false # empty list contains no values.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>There are also standard library functions for lists, see |
| <a href="#ref-list-stdlib">List functions</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-set-expression">Set expressions</h4> |
| <div class="paragraph"> |
| <p>Literal sets are written like</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/literal_set.png" alt="literal set"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The first line shows the syntax of an empty set. The <code>Type</code> block denotes |
| the element type of the set, for example <code><int>{}</code> is an empty set of |
| integer values.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The second line shows how to write a non-empty literal set value. It is a |
| comma-separated sequence of expressions surrounded by curly brackets. |
| The type of all expressions must be the same, and this is also the element type |
| of the set. The order of the values in the literal is not relevant, and |
| duplicate values are silently discarded. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">set real xr = {1.0, 2.5, -31.28, 1.0}</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>assigns the set <code>{-31.28, 1.0, 2.5}</code> (any permutation of the values is |
| allowed). By convention, elements are written in increasing order in this |
| document.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Two set values are equal when they have the same number of element values |
| contained, and each value of one set is also in the other set. The order of the |
| elements in a set is not relevant, any permutation is equivalent.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Like lists, sets have no unary operators. They do have binary operators though, |
| which are</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>lhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type <strong>rhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>+</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Set union</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>-</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Set difference</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>*</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Set intersection</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>==</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for equality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>!=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for inequality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>in</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Element test</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>sub</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Sub-set test</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The <strong>union</strong> of two sets means that the <strong>lhs</strong> elements and the <strong>rhs</strong> elements |
| are merged into one set (and duplicates are silently discarded). |
| <strong>Set difference</strong> makes a copy of the <strong>lhs</strong> set, and removes all elements that |
| are also in the <strong>rhs</strong> operand. |
| The result of the operation has the same type as the <strong>lhs</strong> set. |
| <strong>Set intersection</strong> works the other way around, its result is a set with |
| elements that exist both in <strong>lhs</strong> and in <strong>rhs</strong>. Some examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">set int xr = {1, 3, 7}; |
| set int yr; |
| |
| yr = xr + {1, 2}; # assigns {1, 2, 3, 7} |
| yr = xs - {1, 2}; # assigns {3, 7} |
| yr = xs * {1, 2}; # assigns {1}</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>element test</strong> of sets tests whether the value <strong>lhs</strong> is an element in the |
| set <strong>rhs</strong>. This operation is very fast. |
| The <strong>sub-set test</strong> does the same for every element value in the <strong>lhs</strong> operand. |
| It returns <code>true</code> is every value of the left set is also in the right set. |
| A few examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">1 in {1, 3, 7} == true |
| 9 in {1, 3, 7} == false |
| |
| {1} sub {1, 3, 7} == true |
| {9} sub {1, 3, 7} == false |
| {1, 9} sub {1, 3, 7} == false # All elements must be present. |
| {1, 3, 7} sub {1, 3, 7} == true # All sets are a sub-set of themselves.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>There are also standard library functions for sets, see |
| <a href="#ref-set-stdlib">Set functions</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-dictionary-expression">Dictionary expressions</h4> |
| <div class="paragraph"> |
| <p>Literal dictionaries are written using the syntax shown below</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/literal_dictionary.png" alt="literal dictionary"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>An empty dictionary needs the key and value type prefix, for |
| example <code><string:int>{}</code> is an empty dictionary with strings as key, and |
| integer numbers as value. |
| Literal values of such a dictionary are:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">dict(string, int) d; # Initialized with the empty dictionary. |
| |
| d = {"one": 1, "twenty-three": 23};</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The key-value pairs can be put in any order. Also, the key value must be |
| unique. Two dictionaries are equal when they have the same number of keys, each |
| key in one dictionary is also in the other dictionary, and the value |
| associated with each key also match pair-wise.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The binary operators of dictionaries are</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>lhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type <strong>rhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>[</code> <strong>rhs</strong> <code>]</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">K</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">V</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Element access</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>+</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Update</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>-</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Subtraction</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>-</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list K</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Subtraction</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>-</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set K</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Subtraction</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>==</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for equality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>!=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for inequality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>in</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">K</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Element test</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>sub</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dict(K:V)</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Sub-set test</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The <strong>element access</strong> operator accesses the value of a key. Querying the value |
| of a non-existing key value is not allowed, however when used at the left side |
| of an assignment, it acts as an adding operation. A few examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">dict(int:bool) d = {1:true, 2:false}; |
| bool b; |
| |
| b = d[1]; # assigns 'true' (the value of key 1). |
| d[1] = false; # updates the value of key '1' to 'false'. |
| d[8] = true; # adds pair 8:true to the dictionary.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>+</code> operation on dictionaries is an <strong>update</strong> operation. It copies the |
| <strong>lhs</strong> dictionary, and assigns each key-value pair of the <strong>rhs</strong> dictionary to |
| the copy, overwriting values copied from the <strong>lhs</strong>. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">dict(int:bool) d = {1:true, 2:false}; |
| |
| d + {1:false} # result is {1:false, 2:false} |
| d + {3:false} # result is {1:true, 2:false, 3:false}</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>subtraction</strong> operator only takes keys into consideration, that is, it |
| makes a copy of the <strong>lhs</strong> dictionary, and removes key-value pairs where the key |
| is also in the <strong>rhs</strong> argument (for subtraction of lists and sets, the elements |
| are used, instead of the keys):</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">dict(int:bool) d = {1:true, 2:false}; |
| |
| d - {1:false} # results in {2:false}, value of '1' is not relevant |
| d - [1] # results in {2:false} |
| d - {1} # results in {2:false}</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>As with list subtraction and set difference, the type of the result is the |
| same as the type of the <strong>lhs</strong> dictionary.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>element test</strong> tests for presence of a key value, and the <strong>sub-set</strong> |
| operation tests whether all keys of the <strong>lhs</strong> value are also in the <strong>rhs</strong> |
| value. Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">dict(int:bool) d = {1:true, 2:false}; |
| bool b; |
| |
| b = 2 in d; # assigns 'true', 2 is a key in d. |
| b = 5 in d; # assigns 'false', 5 is not a key in d. |
| |
| {1:false} sub d # results in 'true', all keys are in d.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>There are also standard library functions for dictionaries, see |
| <a href="#ref-dictionary-stdlib">Dictionary functions</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-tuple-expression">Tuple expression</h4> |
| <div class="paragraph"> |
| <p>A tuple expression is a value of a tuple type (explained in |
| <a href="#ref-tuple-type">Tuple type</a>). A tuple expression literal value is written like</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/literal_tuple.png" alt="literal tuple"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A literal tuple is a comma separated sequence of expressions of length two or |
| longer, surrounded by a |
| pair of parentheses. The number of expressions and the type of each expression |
| decide the tuple type. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type tup = tuple(bool b; real r); |
| |
| tup t = (true, 3.48);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The type named <code>tup</code> is a tuple type with a boolean field and a real field. |
| The expression <code>(true, 3.48)</code> constructs the same tuple type, thus it can be |
| assigned to variable <code>t</code>. Names of the fields are not relevant in this |
| matching, for example variable declaration (and initialization) |
| <code>tuple(bool z; real w) u = t</code> is allowed, since the types of |
| the fields match in a pair-wise manner.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A field of a tuple can be accessed both for read and for assignment by the name |
| of the field:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">bool c; |
| |
| c = t.b; # Read the 'b' field. |
| t.b = false; # Assign a new value to the 'b' field.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In the latter case, only the assigned field changes, all other fields keep the |
| same value.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Tuples can also be packed and unpacked. Packing is assignment to all fields, |
| while unpacking is reading of all fields into separate variables:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">real q; |
| |
| t = false, 3.8; # Packing of values into a tuple. |
| |
| c, q = t; # Unpacking into separate variables.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Packing is very closely related to literal tuples above. The difference is |
| that packing can be done only like above in an assignment to a tuple value, |
| while a literal tuple works everywhere.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Unpacking is very useful when the right side (<code>t</code> in the example) is more |
| complex, for example, the return value of a function call, as |
| in <code>c, q = f();</code>. In such cases you don’t need to construct an intermediate |
| tuple variable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Packing and unpacking is also used in multi-assignment statements:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">a, b = 3, 4; # Assign 3 to 'a', and 4 to 'b'. |
| |
| a, b = b, a; # Swap values of 'a' and 'b'.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The latter works due to the intermediate tuple that is created as part in the |
| assignment.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-file-expression">File handle expressions</h4> |
| <div class="paragraph"> |
| <p>Variables of type <code>file</code> are created using a variable declaration with a |
| <code>file</code> type, see <a href="#ref-file-type">File type</a> for details about the type.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You cannot write a literal value for a file type (nor can you read or write |
| values of this type), file values are created by means of the <code>open</code> function |
| in the standard library, see <a href="#ref-file-stdlib">File functions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can test whether two files are the same with the binary <code>==</code> and <code>!=</code> |
| operators.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>lhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type <strong>rhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>==</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">file</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">file</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for equality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>!=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">file</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">file</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for inequality</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Values of type <code>file</code> are used for writing output to a file using the |
| <a href="#ref-write-statement">Write statement</a>, or for reading values from a file using the |
| <code>read</code> function explained in <a href="#ref-read-expression">Read expression</a>. |
| After use, a file should be closed with a <code>close</code> statement explained at |
| <a href="#ref-close-statement">Close statement</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-read-expression">Read expression</h4> |
| <div class="paragraph"> |
| <p>The read expression reads a value of a given type from the keyboard or from a |
| file. It has two forms:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>T</code> <strong>read</strong>(<code>T</code>)</dt> |
| <dd> |
| <p>Read a value of type <code>T</code> from the keyboard.</p> |
| </dd> |
| <dt class="hdlist1"><code>T</code> <strong>read</strong>(<code>file f, T</code>)</dt> |
| <dd> |
| <p>Read a value of type <code>T</code> from the file opened for reading by file <code>f</code> |
| (see the <code>open</code> function in <a href="#ref-file-stdlib">File functions</a> for details about |
| opening files).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>You can read values from types that contain data used for calculation, that is |
| values of types <code>bool</code>, <code>int</code>, <code>real</code>, <code>string</code>, <code>list T</code>, <code>set T</code>, |
| and <code>dict(K:V)</code>. Types <code>T</code>, <code>K</code>, and <code>V</code> must also be readable types of |
| data (that is, get chosen from the above list of types).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Reading a value takes a text (with the same syntax as Chi literal values of |
| the same type), and converts it into a value that can be manipulated in the Chi |
| model. Values read from the text have to be constant, for example the input |
| <code>time</code> cannot be interpreted as real number with the same value as the |
| current simulation time.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-timer-expression">Timer expressions</h4> |
| <div class="paragraph"> |
| <p>Timers are clocks that count down to 0. They are used to track the amount of |
| time you still have to wait. |
| Timers can be stored in data of type <code>timer</code> (see <a href="#ref-timer-type">Timer type</a> for |
| details of the type).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The standard library function <code>ready</code> exists to test whether a timer has |
| expired. See <a href="#ref-timer-stdlib">Timer functions</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-channel-expression">Channel expressions</h4> |
| <div class="paragraph"> |
| <p>Channels are used to connect processes with each other. See the |
| <a href="#ref-channel-type">Channel type</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Usually, channels are created by variable declarations, as in:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">chan void s; |
| chan int c, d;</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This creates three channels, one synchronization channel <code>s</code>, and two |
| channels (<code>c</code>, and <code>d</code>) communicating integers.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There is also a <code>channel</code> function to make new channels:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><code>chan T</code> <strong>channel</strong>(<code>T</code>)</dt> |
| <dd> |
| <p>Construct a new channel communicating data type <code>T</code>. When <code>T</code> is |
| <code>void</code>, a synchronization channel is created instead.</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>The only binary expressions on channels are equality comparison operations.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| <col style="width: 20%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>lhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type <strong>rhs</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>==</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">chan T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">chan T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for equality</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><strong>lhs</strong> <code>!=</code> <strong>rhs</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">chan T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">chan T</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Test for inequality</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>where <code>T</code> can be either a normal type, or <code>void</code>. |
| There has to be an overlap between the channel directions (that is, you cannot |
| compare a receive-only channel with a send-only channel).</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-distribution-expression">Distribution expressions</h4> |
| <div class="paragraph"> |
| <p>A distribution represents a stochastic distribution for drawing random numbers. |
| It use a pseudo-random number generator. See |
| <a href="#tut-chapter-stochastic-behavior">Modeling stochastic behavior</a> for a discussion how random numbers are |
| used.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Variables of type distribution (see <a href="#ref-distribution-type">Distribution type</a>) are |
| initialized by using a distribution function from the standard library, see |
| <a href="#ref-chapter-distributions">Distributions</a> for an overview.</p> |
| </div> |
| <div class="paragraph"> |
| <p>There is only one operator for variables with a distribution type, as shown |
| below</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| <col style="width: 25%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Expression</th> |
| <th class="tableblock halign-left valign-top">Type <strong>op</strong></th> |
| <th class="tableblock halign-left valign-top">Type result</th> |
| <th class="tableblock halign-left valign-top">Explanation</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sample</code> <strong>op</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dist bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Sample <strong>op</strong> distribution</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sample</code> <strong>op</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dist int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Sample <strong>op</strong> distribution</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>sample</code> <strong>op</strong></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">dist real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Sample <strong>op</strong> distribution</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The <code>sample</code> operator draws a random number from a distribution. |
| For example rolling a dice:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">model Dice(): |
| dist int d = uniform(1, 7); |
| |
| # Roll the dice 5 times |
| for i in range(5): |
| writeln("Rolled %d", sample d); |
| end |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-process-expression">Process expressions</h4> |
| <div class="paragraph"> |
| <p>A process expression refers to a process definition. It can be used to |
| parameterize the process that is being instantiated, by passing such a value |
| to a <code>run</code> or <code>start</code> statement. (See <a href="#ref-run-and-start-statements">Run and start statements</a> for |
| details on how to create a new process.) |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc A(int x): |
| writeln("A(%d)", x); |
| end |
| |
| proc B(int x): |
| writeln("B(%d)", x); |
| end |
| |
| proc P(proc (int) ab): |
| run ab(3); |
| end |
| |
| model M(): |
| run P(A); # Pass 'proc A' into P. |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Formal parameter <code>ab</code> of process <code>P</code> is a process variable that refers to |
| a process taking an integer parameter. The given process definition is |
| instantiated. Since in the model definition, <code>A</code> is given to process <code>P</code>, |
| the output of the above model is <code>A(3)</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-instance-expression">Instance expressions</h4> |
| <div class="paragraph"> |
| <p>Process instances represent running processes in the model. Their use is to |
| store a reference to such a running process, to allow testing for finishing.</p> |
| </div> |
| <div class="paragraph"> |
| <p>An instance variable is assigned during a <code>start</code> statement. (See |
| <a href="#ref-run-and-start-statements">Run and start statements</a> for details on how to start a new process.)</p> |
| </div> |
| <div class="paragraph"> |
| <p>The instance variable is used to test for termination of the instantiated |
| process, or to wait for it:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">proc Wait(): |
| delay 4.52; |
| end |
| |
| model M(): |
| inst w; |
| |
| start w = Wait(); |
| |
| delay 1.2; |
| writeln("is Wait finished? %b", finished(w)); |
| |
| # Wait until the process has finished. |
| finish w; |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><code>Wait</code> is a process that waits a while before terminating. In the <code>start</code> |
| statement, instance variable <code>w</code> is set up to refer to instantiated process |
| <code>Wait</code>. After assignment, you can use the variable for testing whether the |
| process has terminated. In the example, the test result is written to the |
| screen, but this could also be used as a guard in a select statement (See |
| <a href="#ref-select-statement">Select statement</a> for details).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The other thing that you can do is to wait for termination of the process by |
| means of the <code>finish</code> statement, see also <a href="#ref-finish-statement">Finish statement</a>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-matrix-expression">Matrix expression</h4> |
| <div class="paragraph"> |
| <p>The syntax of a matrix literal value is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/literal_matrix.png" alt="literal matrix"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The literal starts with a <code>[</code> symbol, and ends with a <code>]</code> symbol. |
| In between it has at least two comma-separated lists of real number values, |
| separated with a <code>;</code> symbol.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Each comma-separated list of real number values is a row of the matrix. The |
| number of columns of each row is the same at each row, which means the number |
| of real number values must be the same with each list. |
| As an example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">matrix(2, 3) m = [1.0, 2.0, 3.0; |
| 4.0, 5.0, 6.0]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><code>m</code> is a matrix with two rows and three columns. A comma separates two |
| columns from each other, a semi colon separates two rows.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax demands at least one semi colon in a literal matrix value, which |
| means you cannot write a matrix literal with a single row directly. Instead, |
| write a cast expression that converts a list of real numbers to a matrix with |
| a single row. See <a href="#ref-cast-expression">Cast expressions</a> for an explanation of cast |
| expressions.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-cast-expression">Cast expressions</h4> |
| <div class="paragraph"> |
| <p>A cast expression converts a value from one type to another. The syntax of a |
| cast expression is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/cast_expression.png" alt="cast expression"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>You write the result type, followed by an expression between parentheses. |
| The value of the expression is converted to the given type. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">real v = 3.81; |
| timer t; |
| |
| t = timer(v); # Convert from real to timer (third entry in the table)</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The conversion from a list to a matrix (the first entry in the table) is a |
| special case in the sense that you also need to specify the size of the |
| resulting matrix, as in:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list real xs = [1, 2, 3]; |
| |
| writeln("matrix with one row and three columns: %s", matrix(1, 3, xs));</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The expected number of rows and columns given in the first two arguments must |
| be constant. When the conversion is performed, the length of the given list |
| must be the same as the number of columns stated in the second argument.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The number of available conversions is quite limited, below is a table that |
| lists them.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3333%;"> |
| <col style="width: 33.3334%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Value type</th> |
| <th class="tableblock halign-left valign-top">Result type</th> |
| <th class="tableblock halign-left valign-top">Remarks</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">matrix</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Conversion of a list to a matrix with one row</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">list</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">set</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Construct a set from a list</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">timer</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Setting up a timer</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">timer</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Reading the current value of a timer</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Parsing a boolean value from a string</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Parsing an integer number from a string</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Parsing a real number from a string</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Converting a boolean to a string representation</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Converting an integer to a string representation</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">string</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Converting a real number to a string representation</p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">int</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">real</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">Widening an integer number to a real number</p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>The first entry exists for creating matrices with one row (which you cannot |
| write syntactically). The second entry constructs a set from a list of values. |
| The element type of the list and the resulting set are the same.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The pair of conversions between timer |
| type and real number type is for setting and reading timers, see |
| <a href="#tut-using-timers">Timers</a> for their use.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The conversions from string to boolean or numeric allows parsing of a |
| string. The other way around is also possible, although this is usually done |
| as part of a <strong>write</strong> statement (see <a href="#ref-write-statement">Write statement</a> for details).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The final entry is for widening an integer to a real number. The other way |
| around (from a real number to an integer number) does not exist as cast, but |
| there are stdlib functions <strong>ceil</strong>, <strong>floor</strong>, and <strong>round</strong> available instead |
| (explained in <a href="#ref-real-stdlib">Real number functions</a>).</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-functioncall-expression">Function call expressions</h4> |
| <div class="paragraph"> |
| <p>A function call starts a function to compute its result value from the input |
| parameters. The syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/func_call_expression.png" alt="func call expression"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>Expression</code> before the open parenthesis represents the function to |
| call. Often this is a simple name like <code>size</code> (the name of one of the |
| standard library functions), but you can have more complicated expressions.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The sequence of expressions inside the parentheses denote the values of the |
| input parameters of the functions. Their type has to match with the type |
| stated in the formal parameter at the corresponding position.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The result of the function call is a value with the same type as stated in the |
| return type of the function definition.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-operator-priorities">Operator priorities</h4> |
| <div class="paragraph"> |
| <p>Operator priorities aim to reduce the number of parentheses needed in |
| expressions. They do this by make choices in the order of applying operators on |
| their arguments. For example, <code>1 + 2 * 3</code> can be interpreted as |
| <code>(1 + 2) * 3</code> (if the addition operation is applied first), or as |
| <code>1 + (2 * 3)</code> (if the multiplication operation is performed first).</p> |
| </div> |
| <div class="paragraph"> |
| <p>In the following table, the order of applying operators in the Chi language |
| is defined.</p> |
| </div> |
| <table class="tableblock frame-all grid-all stretch"> |
| <colgroup> |
| <col style="width: 50%;"> |
| <col style="width: 50%;"> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Priority</th> |
| <th class="tableblock halign-left valign-top">Operators</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">(unary) <code>sample</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">unary <code>+</code>, unary <code>-</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">3</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>^</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>*</code>, <code>/</code>, <code>div</code>, <code>mod</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>+</code>, <code>-</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">6</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code><</code>, <code><=</code>, <code>==</code>, <code>!=</code>, <code>>=</code>, <code>></code>, <code>in</code>, <code>sub</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">7</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">(unary) <code>not</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">8</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>and</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">9</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>or</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Operators with a smaller priority number get applied before operators with a |
| higher priority number. Operators with the same priority get applied from left |
| to right.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ref-chapter-standard-library">Standard library functions</h3> |
| <div class="paragraph"> |
| <p> |
| The Chi language has many general purpose functions available. |
| They are organized by type and kind of use.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#ref-integer-stdlib">Integer functions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-real-stdlib">Real number functions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-string-stdlib">String functions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-list-stdlib">List functions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-set-stdlib">Set functions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-dictionary-stdlib">Dictionary functions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-chapter-distributions">Distributions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-timer-stdlib">Timer functions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-file-stdlib">File functions</a></p> |
| </li> |
| <li> |
| <p><a href="#ref-instance-stdlib">Process instance functions</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-integer-stdlib">Integer functions</h4> |
| <div class="paragraph"> |
| <p>The following standard library functions on integers exist</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>int</code> <strong>abs</strong><code>(int val)</code></p> |
| <div class="paragraph"> |
| <p>Return the absolute value of <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>int</code> <strong>sign</strong><code>(int val)</code></p> |
| <div class="paragraph"> |
| <p>Return <code>-1</code> if val less than zero, <code>1</code> if val more than zero, and |
| <code>0</code> otherwise.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>int</code> <strong>max</strong><code>(int a, b, ...)</code></p> |
| <div class="paragraph"> |
| <p>Return the biggest value of the parameters.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>int</code> <strong>min</strong><code>(int a, b, ...)</code></p> |
| <div class="paragraph"> |
| <p>Return the smallest value of the parameters.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-real-stdlib">Real number functions</h4> |
| <div class="paragraph"> |
| <p>The following standard library functions on real numbers exist</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>real</code> <strong>abs</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Return the absolute value of <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>int</code> <strong>sign</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Return <code>-1</code> if val less than zero, <code>1</code> if val more than zero, and |
| <code>0</code> otherwise.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>max</strong><code>(real a, b, ...)</code></p> |
| <div class="paragraph"> |
| <p>Return the biggest value of the parameters. Integer parameters are |
| silently promoted to real.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>min</strong><code>(real a, b, ...)</code></p> |
| <div class="paragraph"> |
| <p>Return the smallest value of the parameters. Integer parameters are |
| silently promoted to real.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Conversion from real number to integer can be performed in three different |
| ways.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>int</code> <strong>ceil</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Return smallest integer bigger or equal to <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>int</code> <strong>floor</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Return biggest integer less or equal to <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>int</code> <strong>round</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Round to nearest integer value (up if distance is <code>0.5</code>).</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The following power and logarithmic functions exist.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>real</code> <strong>sqrt</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Return the square root of <code>val</code> (argument must be non-negative).</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>cbrt</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Return the cube root of <code>val</code> (<code>val^(1/3)</code>).</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>exp</strong><code>(real x)</code></p> |
| <div class="paragraph"> |
| <p>Compute <code>e^x</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>ln</strong><code>(real x)</code></p> |
| <div class="paragraph"> |
| <p>Compute the natural logarithm of <code>x</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>log</strong><code>(real x)</code></p> |
| <div class="paragraph"> |
| <p>Compute the base-10 logarithm of <code>x</code>.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Finally, there are trigonometric functions available.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>real</code> <strong>cos</strong><code>(real a)</code></p> |
| <div class="paragraph"> |
| <p>Cosine function of angle <code>a</code> (in radians).</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>sin</strong><code>(real angle)</code></p> |
| <div class="paragraph"> |
| <p>Sine function of angle <code>a</code> (in radians).</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>tan</strong><code>(real angle)</code></p> |
| <div class="paragraph"> |
| <p>Tangent function of angle <code>a</code> (in radians).</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>acos</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Arc cosine function of value <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>asin</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Arc sine function of value <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>atan</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Arc tangent function of value <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>cosh</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Hyperbolic cosine function of value <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>sinh</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Hyperbolic sine function of value <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>tanh</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Hyperbolic tangent function of value <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>acosh</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Inverse hyperbolic cosine function of value <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>asinh</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Inverse hyperbolic sine function of value <code>val</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>real</code> <strong>atanh</strong><code>(real val)</code></p> |
| <div class="paragraph"> |
| <p>Inverse hyperbolic tangent function of value <code>val</code>.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-string-stdlib">String functions</h4> |
| <div class="paragraph"> |
| <p>The following string functions exist in the standard library.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>int</code> <strong>size</strong><code>(string s)</code></p> |
| <div class="paragraph"> |
| <p>Get the number of characters in string <code>s</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>string</code> <strong>max</strong><code>(string a, b, ...)</code></p> |
| <div class="paragraph"> |
| <p>Return the biggest string of the parameters.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>string</code> <strong>min</strong><code>(string a, b, ...)</code></p> |
| <div class="paragraph"> |
| <p>Return the smallest string of the parameters.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-list-stdlib">List functions</h4> |
| <div class="paragraph"> |
| <p>Getting an element out of list can be done in two ways.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>tuple(T value, list T ys)</code> <strong>pop</strong><code>(list T xs)</code></p> |
| <div class="paragraph"> |
| <p>Get the first element of non-empty list <code>xs</code> (with arbitrary element type |
| <code>T</code>), and return a tuple with the first element and the list without the |
| first element.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>list T</code> <strong>del</strong><code>(list T xs, int index)</code></p> |
| <div class="paragraph"> |
| <p>Remove element <code>xs[index]</code> from list <code>xs</code> (with arbitrary type <code>T</code>). |
| The index position must exist in the list. Returns a |
| list without the removed element.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For getting information about the number of elements in a list, the following |
| functions are available.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>bool</code> <strong>empty</strong><code>(list T xs)</code></p> |
| <div class="paragraph"> |
| <p>Is list <code>xs</code> empty (for any element type <code>T</code>)? |
| Returns <code>true</code> when <code>xs</code> contains no elements, and <code>false</code> when it has at |
| least one element.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>int</code> <strong>size</strong><code>(list T xs)</code></p> |
| <div class="paragraph"> |
| <p>Get the number of elements in list <code>xs</code> (for any element type <code>T</code>).</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>List functions mainly useful for using with a <code>for</code> statement (explained in |
| <a href="#ref-for-loop-statement">For loop statement</a>) follow next.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>list tuple(int index, T value)</code> <strong>enumerate</strong><code>(list T xs)</code></p> |
| <div class="paragraph"> |
| <p>Construct a copy of the list <code>xs</code> with arbitrary element type <code>T</code>, with |
| each element replaced by a tuple containing the index of the element as |
| well as the element itself. |
| For example, <code>enumerate(["a", "b"])</code> results in the list |
| <code>[(0, "a"), (1, "b")]</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>list int</code> <strong>range</strong><code>(int end)</code></p> |
| <div class="paragraph"> |
| <p>Construct a list with integer values running from <code>0</code> to (but not including) |
| <code>end</code>. For example <code>range(3)</code> produces list <code>[0, 1, 2]</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>list int</code> <strong>range</strong><code>(int start, end)</code></p> |
| <div class="paragraph"> |
| <p>Construct a list with integer values running from <code>start</code> to (but not including) |
| <code>end</code>. For example, <code>range(3, 7)</code> produces list <code>[3, 4, 5, 6]</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>list int</code> <strong>range</strong><code>(int start, end, step)</code></p> |
| <div class="paragraph"> |
| <p>Construct a list with integer values running from <code>start</code> to (but not |
| including) <code>end</code>, while incrementing the value with step size <code>step</code>. |
| For example <code>range(3, 8, 2)</code> produces <code>list [3, 5, 7]</code>. Negative step sizes |
| are also allowed to construct lists with decrementing values, but <code>start</code> has |
| to be larger than <code>end</code> in that case.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For occasionally getting the biggest or smallest element of a list, the <code>min</code> |
| and <code>max</code> functions are available. These functions take a lot of time, if |
| smallest or biggest values are needed often, it may be better to use a sorted |
| list.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>T</code> <strong>min</strong><code>(list T xs)</code></p> |
| <div class="paragraph"> |
| <p>Return the smallest element value of type <code>T</code> (<code>T</code> must be type |
| int, real, or string) from non-empty list <code>xs</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>T</code> <strong>max</strong><code>(list T xs)</code></p> |
| <div class="paragraph"> |
| <p>Return the biggest element value of type <code>T</code> (<code>T</code> must be type |
| int, real, or string) from non-empty list <code>xs</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>list</code> <code>T</code> <strong>sort</strong><code>(list T xs, func bool pred(T a, b))</code></p> |
| <div class="paragraph"> |
| <p>Sort list <code>xs</code> such that the predicate function <code>pred</code> holds for |
| every pair of elements in the list, and return the sorted list.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The predicate function <code>pred</code> must implement a total ordering on the |
| values. See also the <a href="#tut-sorted-lists">sorted lists</a> discussion |
| in the tutorial.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>list</code> <code>T</code> <strong>insert</strong><code>(list T xs, T x, func bool pred(T a, b))</code></p> |
| <div class="paragraph"> |
| <p>Given an already sorted list <code>xs</code> with respect to predicate function <code>pred</code> |
| (with arbitrary element type <code>T</code>), insert element value <code>x</code> into the list |
| such that the predicate function <code>pred</code> again holds for every pair of |
| elements in the list. Return the list with the inserted <code>element</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The predicate function <code>pred</code> must implement a total ordering on the |
| values. See also the <a href="#tut-sorted-lists">sorted lists</a> discussion |
| in the tutorial.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-set-stdlib">Set functions</h4> |
| <div class="paragraph"> |
| <p>Similar to lists, there are two functions for getting an element from a set.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>tuple(T val, set T yr)</code> <strong>pop</strong><code>(set T xr)</code></p> |
| <div class="paragraph"> |
| <p>Get an element of non-empty set <code>xr</code> (with arbitrary element type <code>T</code>), and |
| return a tuple with the retrieved element and the set without the retrieved |
| element. Note that the order of elements in a set has no meaning, and may |
| change at any moment.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>list tuple(int index, T val)</code> <strong>enumerate</strong><code>(set T xr)</code></p> |
| <div class="paragraph"> |
| <p>Construct a list of tuples with position <code>index</code> and element value <code>val</code> |
| from the set <code>xr</code> with arbitrary element type <code>T</code>. Note that the <code>index</code> |
| has no meaning in the set.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Removing a single element from a set can be done with the function below.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>set T</code> <strong>del</strong><code>(set T xr, T value)</code></p> |
| <div class="paragraph"> |
| <p>Remove from set <code>xr</code> (with arbitrary element type <code>T</code>) element |
| <code>value</code> if it exists in the set. Returns a set without the (possibly) |
| removed element.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For getting information about the number of elements in a set, the following |
| functions are available.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>bool</code> <strong>empty</strong><code>(set T xr)</code></p> |
| <div class="paragraph"> |
| <p>Is set <code>xr</code> empty (for any element type <code>T</code>)? |
| Returns <code>true</code> when <code>xr</code> contains no elements, and <code>false</code> when it has at |
| least one element.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>int</code> <strong>size</strong><code>(set T xr)</code></p> |
| <div class="paragraph"> |
| <p>Get the number of elements in set <code>xr</code> (for any element type <code>T</code>).</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For occasionally getting the biggest or smallest element of a set, the <code>min</code> |
| and <code>max</code> functions are available. These functions take a lot of time, if |
| smallest or biggest values are needed often, it may be better to make a sorted |
| list.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>T</code> <strong>min</strong><code>(set T xr)</code></p> |
| <div class="paragraph"> |
| <p>Return the smallest element value of type <code>T</code> (<code>T</code> must be type |
| <code>int</code>, <code>real</code>, or <code>string</code>) from non-empty set <code>xr</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>T</code> <strong>max</strong><code>(set T xr)</code></p> |
| <div class="paragraph"> |
| <p>Return the biggest element value of type <code>T</code> (<code>T</code> must be type |
| <code>int</code>, <code>real</code>, or <code>string</code>) from non-empty set <code>xr</code>.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-dictionary-stdlib">Dictionary functions</h4> |
| <div class="paragraph"> |
| <p>Getting a value or a sequence of values from a dictionary can be done with the |
| following functions.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>tuple(K key, V val, dict(K:V) e)</code> <strong>pop</strong><code>(dict(K:V) d)</code></p> |
| <div class="paragraph"> |
| <p>Get a key-value pair from non-empty dictionary <code>d</code> (with arbitrary key |
| type <code>K</code> and arbitrary value type <code>V</code>), and return a tuple with the |
| retrieved key, the retrieved value, and the dictionary without the |
| retrieved element.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>list tuple(int index, K key, V val)</code> <strong>enumerate</strong><code>(dict(K:V) d)</code></p> |
| <div class="paragraph"> |
| <p>Construct a list of tuples with position <code>index</code>, key <code>key</code> and value |
| <code>val</code> from dictionary <code>d</code> (with arbitrary key type <code>K</code> and arbitrary |
| value type <code>V</code>). Note that the <code>index</code> has no meaning in the |
| dictionary. In combination with a for statement (explained in |
| <a href="#ref-for-loop-statement">For loop statement</a>), it is also possible to iterate over the |
| dictionary directly.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>list K</code> <strong>dictkeys</strong><code>(dict(K:V) d)</code></p> |
| <div class="paragraph"> |
| <p>Return the keys of dictionary <code>d</code> (with any key type <code>K</code> and value type |
| <code>V</code>) as a list with element type <code>K</code>. Since a dictionary has no order, |
| the order of the elements in the resulting list is also undefined.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>list V</code> <strong>dictvalues</strong><code>(dict(K:V) d)</code></p> |
| <div class="paragraph"> |
| <p>Return the values of dictionary <code>d</code> (with any key type <code>K</code> and value type |
| <code>V</code>) as a list with element type <code>V</code>. Since a dictionary has no order, |
| the order of the elements in the resulting list is also undefined.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Removing a single element from a dictionary can be done with the function below.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>dict(K:V)</code> <strong>del</strong><code>(dict(K:V) d, K key)</code></p> |
| <div class="paragraph"> |
| <p>Remove element <code>key</code> from dictionary <code>d</code> (with arbitrary element key type <code>K</code> and |
| arbitrary value type <code>V</code>) if it exists in the dictionary. |
| Returns a dictionary without the (possibly) removed element.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The number of keys in a dictionary can be queried with the following |
| functions.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>bool</code> <strong>empty</strong><code>(dict(K:V) d)</code></p> |
| <div class="paragraph"> |
| <p>Is dictionary <code>d</code> empty? (with any key type <code>K</code> and value type <code>V</code>) |
| Returns <code>true</code> when <code>d</code> contains no elements, and <code>false</code> when it has at |
| least one key element.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>int</code> <strong>size</strong><code>(dict(K:V) d)</code></p> |
| <div class="paragraph"> |
| <p>Get the number of key elements in dictionary <code>d</code> (with any key type <code>K</code> |
| and value type <code>V</code>).</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For occasionally getting the biggest or smallest key value of a dictionary, the |
| <code>min</code> and <code>max</code> functions are available. These functions take a lot of |
| time, if smallest or biggest keys are needed often, it may be better to use a |
| sorted list.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>K</code> <strong>min</strong><code>(dict(K:V) d)</code></p> |
| <div class="paragraph"> |
| <p>Return the smallest key of type <code>K</code> (<code>K</code> must be type |
| <code>int</code>, <code>real</code>, or <code>string</code>) from non-empty dictionary <code>d</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>K</code> <strong>max</strong><code>(dict(K:V) d)</code></p> |
| <div class="paragraph"> |
| <p>Return the biggest key of type <code>K</code> (<code>K</code> must be type |
| <code>int</code>, <code>real</code>, or <code>string</code>) from non-empty dictionary <code>d</code>.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-timer-stdlib">Timer functions</h4> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>bool</code> <strong>ready</strong><code>(timer t)</code></p> |
| <div class="paragraph"> |
| <p>Return whether timer <code>t</code> has expired (or was never set). Returns <code>true</code> |
| if the timer has reached <code>0</code> or was never set, and <code>false</code> if it is still |
| running.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-file-stdlib">File functions</h4> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>bool</code> <strong>eof</strong><code>(file handle)</code></p> |
| <div class="paragraph"> |
| <p>For files that are read, this function tests whether the end of the file |
| (EOF) has been reached. That is, it tests whether you have read the last |
| value in the <code>file</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the call returns <code>true</code>, there are no more values to read. If it |
| returns <code>false</code>, another value is still available. |
| For an example of how to use <code>eof</code> and <code>eol</code>, see |
| <a href="#tut-advanced-file-reading">Advanced reading from a file</a>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>bool</code> <strong>eol</strong><code>(file handle)</code></p> |
| <div class="paragraph"> |
| <p>For files that are read, this function tests whether the end of a line |
| (EOL) has been reached. That is, it tests whether you have read the last |
| value at the current line.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If the call returns <code>true</code>, there are no more values to read at this |
| line. If it returns <code>false</code>, another value can be read. |
| For an example of how to use <code>eof</code> and <code>eol</code>, see |
| <a href="#tut-advanced-file-reading">Advanced reading from a file</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that 'the same line' is applied only to the leading white space. It |
| does not say anything about the number lines that a value itself uses. |
| For example, you could spread a list or set with numbers over multiple lines.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>int</code> <strong>newlines</strong><code>(file handle)</code></p> |
| <div class="paragraph"> |
| <p>For files that are read, this function returns how many lines down the |
| next value can be found. It returns a negative number if the end of the |
| file has been reached.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example, executing:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">int i; |
| file f = open("data.txt", "r"); |
| |
| i = read(f, int); |
| writeln("read %d, eol count is %d", i, newlines(f)); |
| i = read(f, int); |
| writeln("read %d, eol count is %d", i, newlines(f)); |
| i = read(f, int); |
| writeln("read %d, eol count is %d", i, newlines(f)); |
| close(f);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>where "data.txt" contains:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">123 345 |
| 789</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>produces:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="console">read 123, eol count is 0 |
| read 345, eol count is 1 |
| read 789, eol count is -1</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>After reading <code>123</code>, the next integer is at the same line, which is <code>0</code> |
| lines down. After reading <code>345</code>, the next value is at the next line, |
| which is <code>1</code> line down. After reading the final value, a negative line |
| count is returned to indicate lack of a next value.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that 'number of lines down' is applied only to the leading white |
| space. It does not say anything about the number lines that a value itself |
| uses, a set of list could use several lines.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>file</code> <strong>open</strong><code>(string filename, string mode)</code></p> |
| <div class="paragraph"> |
| <p>Open the file with name <code>filename</code> using access mode <code>mode</code>. |
| When the access mode is <code>"r"</code>, the file should exist and is opened for |
| reading. When the access mode is <code>"w"</code>, the file is either created or its |
| previous contents is erased. There is no way to append output to an |
| existing file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Notice that filename is a normal Chi string, which means that the <code>\</code> |
| character needs to be escaped to <code>\\</code>. (That is, use a string like |
| <code>"mydir\\myfile.txt"</code> to open the file with the name <code>myfile.txt</code> in |
| directory (map) <code>mydir</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Alternatively, you may want to use the forward slash <code>/</code> instead as path |
| component separator.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-instance-stdlib">Process instance functions</h4> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>bool</code> <strong>finished</strong><code>(inst p)</code></p> |
| <div class="paragraph"> |
| <p>Return whether the process stored by process instance <code>p</code> has finished. |
| Returns <code>true</code> when the process has finished, and <code>false</code> if it has not ended yet.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ref-chapter-distributions">Distributions</h3> |
| <div class="paragraph"> |
| <p> |
| |
| The Chi language has three kinds of distributions:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#ref-constant-distributions">Constant distributions</a>, distributions returning always the same value</p> |
| </li> |
| <li> |
| <p><a href="#ref-discrete-distributions">Discrete distributions</a>, distributions returning a boolean or integer value</p> |
| </li> |
| <li> |
| <p><a href="#ref-continuous-distributions">Continuous distributions</a>, distributions returning a real number value</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The constant distributions are used during creation of the Chi program. |
| Before adding stochastic behavior, you want to make sure the program itself |
| is correct. It is much easier to verify correctness without stochastic |
| behavior, but if you have to change the program again after the verification, |
| you may introduce new errors in the process.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The constant distributions solve this by allowing you to program with |
| stochastic sampling in the code, but it is not doing anything (since you get |
| the same predictable value on each sample operation). After verifying |
| correctness of the program, you only need to modify the distributions that you |
| use to get proper stochastic behavior.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-constant-distributions">Constant distributions</h4> |
| <div class="paragraph"> |
| <p>The constant distributions have very predictable samples, which makes them |
| ideal for testing functioning of the program before adding stochastic |
| behavior.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>dist</code> <code>bool</code> <strong>constant</strong><code>(bool b)</code></p> |
| <div class="paragraph"> |
| <p>Distribution always returning <code>b</code>.</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>b</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>b</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p>-</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>int</code> <strong>constant</strong><code>(int i)</code></p> |
| <div class="paragraph"> |
| <p>Distribution always returning <code>i</code>.</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>i</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>i</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p>-</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>constant</strong><code>(real r)</code></p> |
| <div class="paragraph"> |
| <p>Distribution always returning <code>r</code>.</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>r</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>r</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p>-</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-discrete-distributions">Discrete distributions</h4> |
| <div class="paragraph"> |
| <p>The discrete distributions return integer or boolean sample values.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>dist</code> <code>bool</code> <strong>bernoulli</strong><code>(real p)</code></p> |
| <div class="paragraph"> |
| <p>Outcome of an experiment with chance <code>p</code> <code>(0 <= p <= 1)</code>.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/bernoulli.svg" alt="bernoulli"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>{false, true}</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>p</code> (where <code>false</code> is interpreted as <code>0</code>, and <code>true</code> is interpreted as <code>1</code>)</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>1 - p</code> (where <code>false</code> is interpreted as <code>0</code>, and <code>true</code> is interpreted as <code>1</code>)</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>Bernoulli(p), <a href="#law-ref">[law-ref]</a>, page 302</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>int</code> <strong>binomial</strong><code>(int n, real p)</code></p> |
| <div class="paragraph"> |
| <p>Number of successes when performing <code>n</code> experiments <code>(n > 0)</code> with chance <code>p</code> <code>(0 <= p <= 1)</code>.</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>{0, 1, ..., n}</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>n * p</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>n * p * (1 - p)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>bin(n, p), <a href="#law-ref">[law-ref]</a>, page 304</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>int</code> <strong>geometric</strong><code>(real p)</code></p> |
| <div class="paragraph"> |
| <p>Geometric distribution, number of failures before success for an experiment with chance <code>p</code> <code>(0 < p <= 1)</code>.</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>{0, 1, ...}</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>(1 - p) / p</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>(1 - p) / p^2</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>geom(p), <a href="#law-ref">[law-ref]</a>, page 305</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>int</code> <strong>poisson</strong><code>(real lambda)</code></p> |
| <div class="paragraph"> |
| <p>Poisson distribution.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/poisson.svg" alt="poisson"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>{0, 1, ...}</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>lambda</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>lambda</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>Poison(lambda), <a href="#law-ref">[law-ref]</a>, page 308</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>int</code> <strong>uniform</strong><code>(int a, b)</code></p> |
| <div class="paragraph"> |
| <p>Integer uniform distribution from <code>a</code> to <code>b</code> excluding the upper bound.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/disc_uni.svg" alt="disc uni"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>{a, a+1, ..., b-1}</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>(a + b - 1) / 2</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>((b - a)^2 - 1) / 12</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>DU(a, b - 1), <a href="#law-ref">[law-ref]</a>, page 303</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-continuous-distributions">Continuous distributions</h4> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>beta</strong><code>(real p, q)</code></p> |
| <div class="paragraph"> |
| <p>Beta distribution with shape parameters <code>p</code> and <code>q</code>, with <code>p > 0</code> and <code>q > 0</code>.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/beta.svg" alt="beta"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>[0, 1]</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>p / (p + q)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>p * q / ((p + q)^2 * (p + q + 1))</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>Beta(p, q), <a href="#law-ref">[law-ref]</a>, page 291</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>erlang</strong><code>(double m, int k)</code></p> |
| <div class="paragraph"> |
| <p>Erlang distribution with <code>k</code> a positive integer and <code>m > 0</code>. |
| Equivalent to <code>gamma(k, m / k)</code>.</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>m</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>m * m / k</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>ERL(m, k), <a href="#banks-ref">[banks-ref]</a>, page 153</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>exponential</strong><code>(real m)</code></p> |
| <div class="paragraph"> |
| <p>(Negative) exponential distribution with mean <code>m</code>, with <code>m > 0</code>.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/exponential.svg" alt="exponential"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>[0, infinite)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>m</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>m * m</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>expo(m), <a href="#law-ref">[law-ref]</a>, page 283</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>gamma</strong><code>(real a, b)</code></p> |
| <div class="paragraph"> |
| <p>Gamma distribution, with shape parameter <code>a > 0</code> and scale parameter <code>b > 0</code>.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/gamma.svg" alt="gamma"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>a * b</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>a * b^2</code></p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>lognormal</strong><code>(real m, v2)</code></p> |
| <div class="paragraph"> |
| <p>Log-normal distribution.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/lognormal.svg" alt="lognormal"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>[0, infinite)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>exp(m + v2/2)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>exp(2*m + v2) * (exp(v2) - 1)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>N(m, v2), <a href="#law-ref">[law-ref]</a>, page 290</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>normal</strong><code>(real m, v2)</code></p> |
| <div class="paragraph"> |
| <p>Normal distribution.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/normal.svg" alt="normal"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>(-infinite, infinite)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>m</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>v2</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>N(m, v2), <a href="#law-ref">[law-ref]</a>, page 288</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>random</strong><code>()</code></p> |
| <div class="paragraph"> |
| <p>Random number generator.</p> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>[0, 1)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>0.5</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>1 / 12</code></p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>triangle</strong><code>(real a, b, c)</code></p> |
| <div class="paragraph"> |
| <p>Triangle distribution, with <code>a < b < c</code>.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/triangle.svg" alt="triangle"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>[a, c]</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>(a + b + c) /3</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>(a^2 + c^2 + b^2 - a*b - a*c - b*c) / 18</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>Triangle(a, c, b), <a href="#law-ref">[law-ref]</a>, page 300</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>uniform</strong><code>(real a, b)</code></p> |
| <div class="paragraph"> |
| <p>Real uniform distribution from <code>a</code> to <code>b</code>, excluding upper bound.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/cont_uni.svg" alt="cont uni"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>[a, b)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>(a + b) / 2</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>(b - a)^2 / 12</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>U(a,b), <a href="#law-ref">[law-ref]</a>, page 282, except that distribution has an inclusive upper bound.</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| <li> |
| <p><code>dist</code> <code>real</code> <strong>weibull</strong><code>(real a, b)</code></p> |
| <div class="paragraph"> |
| <p>Weibull distribution with shape parameter <code>a</code> and scale parameter <code>b</code>, with <code>a > 0</code> and <code>b > 0</code>.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/distribution_plots/weibull.svg" alt="weibull"> |
| </div> |
| </div> |
| <div class="hdlist"> |
| <table> |
| <tr> |
| <td class="hdlist1"> |
| Range |
| </td> |
| <td class="hdlist2"> |
| <p><code>[0, infinite)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Mean |
| </td> |
| <td class="hdlist2"> |
| <p><code>(b / a) * G(1 / a)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| Variance |
| </td> |
| <td class="hdlist2"> |
| <p><code>(b^2 / a) * (2 * G(2 / a) - (1 / a) * G(1 / a)^2)</code> with <code>G(x)</code> the Gamma function, |
| <code>G(x)</code> <code>=</code> integral over <code>t</code> from <code>0</code> to <code>infinity</code>, for <code>t^(x - 1) * exp(-t)</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td class="hdlist1"> |
| See also |
| </td> |
| <td class="hdlist2"> |
| <p>Weibull(a, b), <a href="#law-ref">[law-ref]</a>, page 284</p> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-references">References</h4> |
| <div class="ulist bibliography"> |
| <ul class="bibliography"> |
| <li> |
| <p><a id="banks-ref"></a>[banks-ref] Handbook of Simulation, |
| Principles, Methodology, Advances, Applications, and Practice, |
| editor Jerry Banks, |
| publisher John Wiley & Sons, inc, 1998</p> |
| </li> |
| <li> |
| <p><a id="law-ref"></a>[law-ref] Simulation Modeling & Analysis, fourth edition, |
| by Averill M. Law, |
| publisher McGraw-Hill, International Edition, 2007, |
| ISBN 978-007-125519-6</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ref-chapter-types">Types</h3> |
| <div class="paragraph"> |
| <p> |
| A type defines the set of possible values of an expression or a variable. |
| Its syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/type.png" alt="type"> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The <code>ElementaryType</code> block contains types that do not build on other types. |
| They are explained further in <a href="#ref-elementary-type">Elementary types</a>.</p> |
| </li> |
| <li> |
| <p>The <code>ContainerType</code> block contains types that can store values of a single |
| other type, the 'list', 'set', and 'dictionary' type. These types are further |
| explained in <a href="#ref-container-type">Container types</a>.</p> |
| </li> |
| <li> |
| <p>The <code>TupleType</code> block describes 'tuples', a type that can hold values of |
| several other types.</p> |
| </li> |
| <li> |
| <p>The <code>ChannelType</code> blocks describes communication channels that connect |
| processes with each other, see <a href="#ref-channel-type">Channel type</a> for more explanation.</p> |
| </li> |
| <li> |
| <p>The <code>DistributionType</code> block contains the stochastic distribution type, |
| explained in <a href="#ref-distribution-type">Distribution type</a>.</p> |
| </li> |
| <li> |
| <p>The <code>FunctionType</code> can hold a function definition. It allows you to pass |
| a function to a process or another function. It is further explained in |
| <a href="#ref-function-type">Function type</a>.</p> |
| </li> |
| <li> |
| <p>The <code>ProcessType</code> can hold a process definition. It allows you to pass |
| a process definition to a another process. It is further explained in |
| <a href="#ref-process-type">Process type</a>.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>TypeName</code> is the name of a type defined with a <code>type</code> definition |
| (explained in <a href="#ref-type-definitions">Type definitions</a>). For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">type lot = real; |
| |
| model M(): |
| lot x; |
| |
| ... |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>lot x</code> variable declaration (explained in <a href="#ref-variable-declarations">Local variables</a>) |
| uses the type definition of <code>lot</code> at the first line to define the type of |
| variable <code>x</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>EnumTypeName</code> is similar, except it uses an enumeration definition (see |
| <a href="#ref-enum-definitions">Enumeration definitions</a>) as type. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">enum FlagColours = {red, white, blue}; |
| |
| model M(): |
| FlagColours x = white; |
| |
| ... |
| end</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>FlagColours x</code> variable declaration defines that variable <code>x</code> has the |
| type of the enumeration, and can hold its values.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-elementary-type">Elementary types</h4> |
| <div class="paragraph"> |
| <p>The elementary types do not depend on other types to define their set of |
| allowed values. Their syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/elementary_type.png" alt="elementary type"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>As you can see, they are mostly just a single keyword. The |
| <code>ConstantExpression</code> nodes in the <code>matrix</code> type line are integer |
| expressions with a fixed (and known) value before execution of the program. |
| More information about the elementary types is provided below.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-boolean-type">Boolean type</h5> |
| <div class="paragraph"> |
| <p>The <code>bool</code> keyword denotes the boolean data type. The allowed values are |
| <code>false</code> and <code>true</code>. While it is allowed to store boolean values in other |
| data types, their most frequent use is in expressions of statements that |
| decide what to do, for example, the condition in the <code>while</code>, <code>if</code> or |
| select statement (see <a href="#ref-while-loop-statement">While loop statement</a>, |
| <a href="#ref-choice-statement">Choice statement</a> and <a href="#ref-select-statement">Select statement</a>). |
| Expressions with booleans are explained in <a href="#ref-boolean-expression">Boolean expressions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-integer-type">Integer type</h5> |
| <div class="paragraph"> |
| <p>The <code>int</code> keyword denotes the integer data type, integer numbers from |
| <code>2147483647</code> to <code>-2147483648</code> (a standard signed 32 bit number). Values outside |
| that range give undefined behavior. |
| Expressions with integers are explained in <a href="#ref-integer-expression">Integer expressions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-real-type">Real type</h5> |
| <div class="paragraph"> |
| <p>The <code>real</code> keyword denotes the real number data type, real numbers between |
| <code>4.94065645841246544e-324</code> to <code>1.79769313486231570e+308</code> positive or negative (a |
| standard 8 bytes IEEE 754 number). As normal with floating point numbers in |
| computer systems, many values are missing from the above range. Expect |
| rounding errors with each calculation. |
| Expressions with real numbers are explained in <a href="#ref-real-expression">Real number expressions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-string-type">String type</h5> |
| <div class="paragraph"> |
| <p>The <code>string</code> keyword denotes strings, sequences of characters. It contains |
| all printable ASCII characters U+0020 to U+007E, and 'tab' (U+0009) and |
| 'new line' (U+000A). |
| Expressions with strings are explained in <a href="#ref-string-expression">String expressions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-file-type">File type</h5> |
| <div class="paragraph"> |
| <p>The <code>file</code> keyword denotes a file at the file system of the computer. It |
| allows reading and writing values of many data types (not all data types can |
| be read or written). Expressions with files are explained in |
| <a href="#ref-file-expression">File handle expressions</a>. |
| How to work with files is explained in <a href="#tut-chapter-input-and-output">Input and output</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-inst-type">Instance type</h5> |
| <div class="paragraph"> |
| <p>The <code>inst</code> keyword denotes an instance type, it can store a running |
| process. Its use is to check whether the stored process has ended. |
| The <a href="#ref-finish-statement">Finish statement</a> gives more details and provides an example.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-timer-type">Timer type</h5> |
| <div class="paragraph"> |
| <p>The <code>timer</code> keyword denotes a count-down timer. Variables of this type |
| measure time that has passed since their initialization. Expressions with |
| timers are given in <a href="#ref-timer-expression">Timer expressions</a>, a tutorial about using |
| timers can be found in <a href="#tut-using-timers">Timers</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-matrix-type">Matrix type</h5> |
| <div class="paragraph"> |
| <p>The <code>matrix</code> type takes two constant expressions that define the number of |
| rows and the number of columns of the matrix. The main purpose of the data |
| type is to allow temporary storage of matrices so they can be passed on to |
| other software. The Chi language also has expressions to write literal |
| matrices, see <a href="#ref-matrix-expression">Matrix expression</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-void-type">Void type</h5> |
| <div class="paragraph"> |
| <p>The <code>void</code> type denotes that no data is involved. Values of type <code>void</code> do |
| not exist. The type is allowed at two places in the Chi specification, namely</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>As data type of synchronization channels. Further explanation can be found |
| at <a href="#ref-communication-statements">Communication statements</a> and <a href="#ref-channel-type">Channel type</a>.</p> |
| </li> |
| <li> |
| <p>As exit type of <a href="#ref-model-definitions">Model definitions</a> and |
| <a href="#ref-process-definitions">Process definitions</a>, to express that it may return an exit value |
| from an <a href="#ref-exit-statement">Exit statement</a> without arguments.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-container-type">Container types</h4> |
| <div class="paragraph"> |
| <p>The main function of container types is to organize and hold a collection of |
| values of another type (the <em>element type</em>). |
| The syntax diagram of the container types is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/container_type.png" alt="container type"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The language has three container types, <em>lists</em> (explained in |
| <a href="#ref-list-type">List type</a>), <em>sets</em> (explained in <a href="#ref-set-type">Set type</a>), and |
| <em>dictionaries</em> (explained in <a href="#ref-dictionary-type">Dictionary type</a>).</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-list-type">List type</h5> |
| <div class="paragraph"> |
| <p>The list type has an ordered collection of values from its element type as its |
| value. Duplicate element values are allowed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax of a list type is given below.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/list_type.png" alt="list type"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It starts with the keyword <code>list</code>, optionally followed by a parenthesized |
| (non-negative) integer expression denoting the initial number of element |
| values in the collection, and finally the type of the element values.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The default size of the collection is the value of the integer expression, or |
| 0 if there is no such expression. The value of the elements in the initial |
| list value depends on the type of the elements.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A few examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">list bool # A list of boolean values, initial value is <bool>[] |
| list (2) int # A list of integer values, initial value is [0, 0]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For a discussion of operations on values of this type, |
| see <a href="#ref-list-expression">List expressions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-set-type">Set type</h5> |
| <div class="paragraph"> |
| <p>The set type has an unordered collection of values from its element type as |
| its value. Duplicate element values are silently discarded.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax of the set type is given below.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/set_type.png" alt="set type"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The set type starts with a <code>set</code> keyword, followed by the type of its |
| elements. Its initial value is the empty set. |
| An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">set real # A set of real numbers, initial value <real>{}.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For a discussion of operations on values of this type, see |
| <a href="#ref-set-expression">Set expressions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="ref-dictionary-type">Dictionary type</h5> |
| <div class="paragraph"> |
| <p>The dictionary type has an unordered collection of values of its key type, so |
| called keys. The keys are unique in the collection. In addition, |
| the dictionary has a value of its value type associated with each key.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax of a dictionary type is given below.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/dictionary_type.png" alt="dictionary type"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The syntax starts with a <code>dict</code> keyword, and the key type and value type |
| between parentheses, separated by a colon. |
| The initial value of a dictionary type is the empty dictionary. An example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">dict (bool : int) # A dictionary with boolean keys, and integer values. |
| # Initial value <bool:int>{}.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For a discussion of operations on values of this type, see |
| <a href="#ref-dictionary-expression">Dictionary expressions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-tuple-type">Tuple type</h4> |
| <div class="paragraph"> |
| <p>A tuple contains a fixed number of values of (possibly) different types. Its |
| syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/tuple_type.png" alt="tuple type"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A tuple type starts with the keyword <code>tuple</code>, followed by the list of its |
| fields between parentheses. Each field has a name and a type. Sequences of |
| fields with the same type can share their type description, which reduces the |
| amount of text of the tuple type. |
| Tuple types must have at least two fields.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Examples:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="CodeRay highlight"><code data-lang="chi">tuple(int a, b) # A tuple containing fields 'a' and 'b', both of type int |
| tuple(int a; int b) # A tuple containing fields 'a' and 'b', both of type int |
| |
| tuple(lot x; real start) # A tuple with a 'lot' and a 'real' type.</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The first two examples are equivalent, the first form is just a bit shorter in |
| notation. The third example is more common fields of different types that are |
| kept together in the modeled system. |
| Expressions with tuples are discussed in <a href="#ref-tuple-expression">Tuple expression</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-channel-type">Channel type</h4> |
| <div class="paragraph"> |
| <p>The channel type defines the direction and the type of values transported. |
| The syntax of the channel type is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/channel_type.png" alt="channel type"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>chan</code> keyword denotes a channel type is being created. It may be |
| followed by allowed directions of transport, a <code>!</code> means that sending values |
| is allowed but not for receiving, and a <code>?</code> means that receiving values is |
| allowed and sending is not allowed. Finally <code>!?</code> means |
| both sending and receiving is allowed. The latter is also selected when no |
| direction is specified. |
| The language silently discards allowed directions. A channel usable for both |
| sending and receiving may be used as a channel for sending only (dropping |
| the ability to receive at that point). It does not allow adding directions, a |
| receive-only channel cannot be used for sending. It can also not be used as a |
| channel for sending and receiving, even if then latter is only used for |
| receiving values (that is, sending is never done).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The type of data that is transported with a communication is given by the |
| <code>Type</code> block. Signalling channels (that only synchronize without |
| transporting data) are indicated by the <code>void</code> keyword. |
| The only expressions available for channels are the equality tests, and a |
| function to create new channels, see |
| <a href="#ref-channel-expression">Channel expressions</a> for details.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-distribution-type">Distribution type</h4> |
| <div class="paragraph"> |
| <p>The distribution type represents a stochastic distribution. The syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/distribution_type.png" alt="distribution type"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A stochastic distribution allows modeling of random behavior, but with a known |
| chance distribution. The <code>Type</code> block in the <code>DistributionType</code> diagram |
| defines the type of values drawn. For a discussion of expressions for the |
| distribution type, see <a href="#ref-distribution-expression">Distribution expressions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-function-type">Function type</h4> |
| <div class="paragraph"> |
| <p>The function type can hold a function. Its syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/function_type.png" alt="function type"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>A function type starts with the keyword <code>func</code> followed by the return type |
| of the function and the type of the formal parameters. |
| The purpose of the function type is to pass functions to processes or other |
| functions, for example, the predicate function in <code>sort</code> and <code>insert</code>, see |
| <a href="#ref-list-stdlib">List functions</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-process-type">Process type</h4> |
| <div class="paragraph"> |
| <p>The process type is similar to the function type (discussed in |
| <a href="#ref-function-type">Function type</a>), except this type can hold a process definition. |
| The syntax is</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./reference-manual/rail_diagrams/process_type.png" alt="process type"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The type starts with the keyword <code>proc</code> followed by the formal parameters of |
| the process definition to store between parentheses. |
| Expressions with process types are explained in <a href="#ref-process-expression">Process expressions</a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ref-chapter-lexical-syntax">Lexical syntax</h3> |
| <div class="paragraph"> |
| <p>At the lowest level, a Chi specification file consists of a sequence of |
| characters. The characters are grouped together to form keywords, names, |
| literal values such as numbers, and symbols such as expression operators |
| like <code>+</code> and statement separator <code>;</code>. Also comments are recognized at this |
| level.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-whitespace">Whitespace</h4> |
| <div class="paragraph"> |
| <p>The characters that delimit groups and lines from each other is known as |
| <em>whitespace</em>. It contains the 'tab' character (U0009), the 'line feed' |
| character (U000A), the 'carriage return' character (U000D), and the 'space' |
| character (U0020).</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-comment">Comment</h4> |
| <div class="paragraph"> |
| <p>A comment is a line of text intended for annotating the program text. It can |
| also be used to (temporarily) add or remove statements. |
| In the latter case, do note that the meaning of the program may change.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A line of comment starts with a 'hash' character <code>#</code>, and continues |
| until a 'line feed' character (or the end of the file). All characters in the |
| comment are ignored by the simulator.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-lexical-names">Names</h4> |
| <div class="paragraph"> |
| <p>A name is a word-like group of characters. It may start with a <code>$</code> prefix. |
| After the prefix (if one is provided), first a letter (<code>A</code> to <code>Z</code> or <code>a</code> |
| to <code>z</code>) or an 'underscore' character <code>_</code> should be used, optionally |
| followed by more letters, 'underscore' characters, or digits <code>0</code> to <code>9</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Some names are special in the sense that the Chi language reserves them for |
| its own use, for example the names <code>model</code> and <code>end</code>. Keywords are always |
| written using lowercase letters. In the grammar diagrams, the keywords are |
| shown in a rounded box. Names starting with a <code>$</code> prefix are never used as |
| keyword.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Names not used as keyword can be used to give entities in the Chi program a |
| unique identification. In the grammar of this reference manual names are split |
| according to the kind of entity that they refer to:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">ConstantName</dt> |
| <dd> |
| <p>Name that refers to a constant value, see <a href="#ref-constant-definitions">Constant definitions</a> |
| for details.</p> |
| </dd> |
| <dt class="hdlist1">EnumtypeName</dt> |
| <dd> |
| <p>Name that refers to an enum type, see <a href="#ref-enum-definitions">Enumeration definitions</a> for |
| details.</p> |
| </dd> |
| <dt class="hdlist1">EnumvalueName</dt> |
| <dd> |
| <p>Name that refers to a value within an enum type, see |
| <a href="#ref-enum-value-expression">Enumeration value</a> for details.</p> |
| </dd> |
| <dt class="hdlist1">FieldName</dt> |
| <dd> |
| <p>Name that refers to a field in a tuple type, see <a href="#ref-tuple-type">Tuple type</a> |
| for more details about tuples.</p> |
| </dd> |
| <dt class="hdlist1">FunctionName</dt> |
| <dd> |
| <p>Name that refers to a function definition, see |
| <a href="#ref-function-definitions">Function definitions</a> for details.</p> |
| </dd> |
| <dt class="hdlist1">ModelName</dt> |
| <dd> |
| <p>Name that refers to a model definition, see <a href="#ref-model-definitions">Model definitions</a> |
| for details.</p> |
| </dd> |
| <dt class="hdlist1">ProcessName</dt> |
| <dd> |
| <p>Name that refers to a process definition, see |
| <a href="#ref-process-definitions">Process definitions</a> for details.</p> |
| </dd> |
| <dt class="hdlist1">TypeName</dt> |
| <dd> |
| <p>Name that refers to a type, see <a href="#ref-type-definitions">Type definitions</a> for details.</p> |
| </dd> |
| <dt class="hdlist1">VariableName</dt> |
| <dd> |
| <p>Name that refers to a variable (see <a href="#ref-variable-declarations">Local variables</a>) or |
| formal parameter in a process or function (see <a href="#ref-formal-parameters">Formal parameters</a>).</p> |
| </dd> |
| </dl> |
| </div> |
| <div class="paragraph"> |
| <p>Names are also shown in a rounded box, but as shown above, start with an |
| uppercase letter and end with <code>Name</code>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ref-chapter-migration">Model migration</h3> |
| <div class="paragraph"> |
| <p>There are currently no migrations to upgrade from older versions of Chi.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="ref-chapter-svg-visualization">SVG visualization</h3> |
| <div class="paragraph"> |
| <p>The Chi simulator has the possibility to display an SVG file during the |
| simulation. The model can modify the displayed image depending on the state of |
| the simulated system, thus visualizing the system.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Such a visualization is useful for getting a quick global verification, as |
| well as explaining the purpose of the model to people that do not know the |
| detailed ins and outs of the problem being solved.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Below are the technical details of the SVG visualization. The tutorial has a |
| <a href="#tut-chapter-svg-visualization">more gentle introduction</a> into the subject.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-svg-interface">SVG interface</h4> |
| <div class="paragraph"> |
| <p>The SVG visualization itself is controlled by the simulator. Normally, it is |
| updated just before a time step is performed. The simulation can however |
| force an update with the <code>redraw</code> command (see below for details).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The simulation accesses the SVG visualization by opening a file for writing |
| with a name like <code>SVG:xyz.svg</code>. The <code>SVG:</code> prefix redirects the request to |
| the SVG visualizer, the <code>xyz.svg</code> suffix is the name of the SVG file to |
| display. The file should be available at the file system.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Different Chi processes may open the same file at the same time. The SVG |
| visualizer can only display one SVG file at a time, it is not allowed for |
| processes to open different <code>.svg</code> files.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="ref-visualization-modification-commands">Visualization modification commands</h4> |
| <div class="paragraph"> |
| <p>After opening the file, the content of the SVG file can be changed by |
| modifying the nodes. This is done by writing lines with commands (one command |
| at each line). Available commands are:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong>Copy an element (recursively)</strong></p> |
| <div class="paragraph"> |
| <p><code>copy [orig-id], [opt-prefix], [op-suffix]</code>, with <code>[orig-id]</code> the |
| id-name of the element to copy, <code>[opt-prefix]</code> an optional prefix that is |
| added to the <code>id</code> of all copied elements, and <code>[opt-suffix]</code> an optional |
| suffix that is added to the <code>id</code> of all copied elements. Since the <code>id</code> |
| of all elements must be unique, leaving both the prefix and the suffix empty |
| gives an error about duplicate <code>id</code> labels.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the element (and its descendants) is only copied, but not moved. |
| In other words, after copying it is fully obscured by the original element. |
| The next step is normally an absolute move command or an attribute command |
| to perform a relative translate transformation.</p> |
| </div> |
| </li> |
| <li> |
| <p><strong>Move an element to an absolute position</strong></p> |
| <div class="paragraph"> |
| <p><code>absmove [id] ([xpos], [ypos])</code> with <code>[id]</code> the id-name of the |
| element to move, <code>[xpos]</code> the horizontal position to move to, and |
| <code>[ypos]</code> the vertical position to move to. This operation adds a |
| translation to the <code>transform</code> attribute of the node such that the |
| top-left corner of the bounding rectangle is moved to the provided position. |
| It also takes the existing transformation into account, and in doing so, |
| will fail if the transformation cannot be reversed.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The origin of the coordinate system is at the top-left of the SVG |
| visualization window, with positive X running to the right, and positive Y |
| running down.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Avoid using this operation repeatedly on the same element. Instead move it |
| once to a base position, and perform relative translate transformations |
| on a child element to move it to the desired position.</p> |
| </div> |
| </li> |
| <li> |
| <p><strong>Change an attribute of an element</strong></p> |
| <div class="paragraph"> |
| <p><code>attr [id].[atrribute] = [value]</code> with <code>[id]</code> the id-name of the |
| element, <code>[attribute]</code> the name of the attribute of the element to change, |
| and <code>[value]</code> the new value of the attribute.</p> |
| </div> |
| <div class="paragraph"> |
| <p>A change overwrites any previous value of the attribute. Also, names of |
| attributes and syntax of values are not checked.</p> |
| </div> |
| </li> |
| <li> |
| <p><strong>Change the text of an element</strong></p> |
| <div class="paragraph"> |
| <p><code>text [id] = [value]</code> with <code>[id]</code> the id-name of the element, and |
| <code>[value]</code> the new text.</p> |
| </div> |
| </li> |
| <li> |
| <p><strong>Force a redraw of the image</strong></p> |
| <div class="paragraph"> |
| <p>Normally the program redraws the SVG image when it detects a change in time |
| after making changes in the image by using one of the previous commands. |
| With this command you can fake a change in time, thus allowing you to also |
| display intermediate states.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The command is mostly useful in experiments, where time never changes.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="tool-chapter-tool-manual">Chi Tool Manual</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This manual explains how to use the Chi simulation software. Before using |
| the software however, you need to install it. The software is part of the |
| Eclipse ESCET software.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Once you’re finished installing, you can start to |
| <a href="#tool-chapter-software-operation">simulate</a> Chi programs. The easiest way to |
| start simulation is to press the <em>F9</em> key in a Chi text editor, or when a Chi |
| (a file with a <code>.chi</code> extension) is selected in the |
| <em>Project Explorer</em> or <em>Package Explorer</em> tab.</p> |
| </div> |
| <div class="paragraph"> |
| <p><em>Topics</em></p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="#tool-chapter-software-operation">Available operations on a <code>chi</code> file</a></p> |
| </li> |
| <li> |
| <p><a href="#tool-chapter-command-line">Command line options</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="sect2"> |
| <h3 id="tool-chapter-software-operation">Software operation</h3> |
| <div class="paragraph"> |
| <p>The Chi simulator software performs two steps internally:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Type checking of the Chi source file, and building a simulator for it.</p> |
| </li> |
| <li> |
| <p>Running the created simulator.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Starting with a <code>.chi</code> source file, both steps have to be performed for a |
| simulation. As this is the common situation, the software normally combines |
| both steps. |
| If you run many experiments with the same file, it becomes useful to skip the |
| first step. How to do this is explained in <a href="#tool-compile-or-simulate">Compile only</a>. |
| In addition, the software can be run from the command line. In that case, |
| command-line options as explained in <a href="#tool-chapter-command-line">Command line options</a> need to be |
| specified.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tool-compile-and-simulate">Compile and simulate</h4> |
| <div class="paragraph"> |
| <p>Normally, you want to simulate a <code>.chi</code> source file. The Chi simulator |
| software uses two steps internally (first checking the input and building the |
| simulator, then running the just created simulator), but these steps are |
| combined in the dialog.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The process starts by selecting the source file you want to use (a file with |
| a <code>.chi</code> extension) in the <em>Project Explorer</em> or <em>Package Explorer</em> tab, and opening the |
| popup menu with the right mouse button from that selection. |
| Alternatively, open the file in the editor, and use the right mouse button to |
| get a similar popup menu.</p> |
| </div> |
| <div class="paragraph"> |
| <p>From the popup menu, select <em>Simulate Chi file</em> entry. The |
| selection causes the <em>Console</em> view to be opened in Eclipse, and a |
| dialog window pops up to set the simulator options like below.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./tool-manual/chi_simulator_dialog.png" alt="chi simulator dialog"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The dialog shows the source file being used in the <em>Input file path</em> box. |
| Below it, in the <em>Instance</em> box, you can enter how to run the |
| model or the experiment of the source file. The syntax of the input is the same |
| as you would |
| write it in your Chi file. For example, with a model definition |
| <code>model M(list real xs, int n): ... end</code>, you could write <code>M([1.5, 2.81], 15)</code> as |
| model instantiation. If you leave the entry empty, the simulator tries to find |
| an experiment without any parameters (for example <code>X()</code>). If that fails, it |
| tries to find a model without any parameters (typically <code>M()</code>). If both |
| attempts fail, or the simulator finds more than one such experiment or model, |
| an error is reported.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you want to set an initial seed (see |
| <a href="#tut-simulating-stochastic-behavior">Simulating stochastic behavior</a> for a discussion), you can use the |
| <em>Initial seed value</em> box. Value <code>0</code> means 'create a new one'.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This is all you have to do, select <em>OK</em> at the bottom. The software |
| performs its two steps, and if no errors are found, it runs the model.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="tool-quick-simulate">Quick simulate</h5> |
| <div class="paragraph"> |
| <p>For files that do not need any further configuration before |
| they are run, there is a <em>Quick simulate Chi file</em>. This menu |
| option assumes the default configuration (a parameter-less experiment or |
| model needs to be run with a new seed), skips the dialog (saving you from |
| having to press <em>OK</em>) and immediately proceeds with processing the Chi file.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This functionality is also available from the Chi text editor, by pressing |
| the <em>F9</em> key. Alternatively, you can select a Chi file in the |
| <em>Project Explorer</em> or <em>Package Explorer</em>, and press the |
| <em>F9</em> key.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tool-compile-or-simulate">Compile only</h4> |
| <div class="paragraph"> |
| <p>The above is convenient for simple experiments, but checking the input and |
| building a simulator each time is tedious if you want to do several |
| experiments with the same source file. |
| For this reason, each step can be done separately as well.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Only building a simulator starts in the same way as above, select a <code>.chi</code> |
| source file from the <em>Project Explorer</em>, the <em>Package Explorer</em> |
| or an editor window, and right-click at it. Select the <em>Simulate Chi file</em> |
| option from the popup menu. As the file only gets compiled, the |
| simulator options are of no interest. Instead switch to the <em>Compiler</em> |
| tab. It looks like this:</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="./tool-manual/chi_compiler_dialog.png" alt="chi compiler dialog"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Most settings are only useful for developers, but at the bottom, check the |
| <em>Write the compiled Java code to a .cchi file</em> box, and click |
| <em>OK</em> at the bottom. Setting this option causes the simulator |
| software to check the input file, build a simulator, write the constructed |
| simulator to a <code>.cchi</code> file (a compiled Chi file), and quit. No simulation |
| of the Chi model is performed at this time.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tool-simulate-a-compiled-model">Simulate a compiled model</h4> |
| <div class="paragraph"> |
| <p>You can simulate the Chi model from the <code>.cchi</code> file now, by selecting |
| that file as source file by right-clicking on it. Select the |
| <em>Simulate Chi file</em> or the <em>Quick simulate Chi file</em> |
| option as before, and proceed with setting the |
| simulator options and running the model as-if you selected a normal <code>.chi</code> |
| file, as explained in <a href="#tool-compile-and-simulate">Compile and simulate</a> above.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tool-terminating-a-simulation">Terminating a simulation</h4> |
| <div class="paragraph"> |
| <p>A simulation ends when:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>The model goes into a deadlock state,</p> |
| </li> |
| <li> |
| <p>An <code>exit</code> statement is performed (see <a href="#tut-exit">experiments</a> |
| in the tutorial),</p> |
| </li> |
| <li> |
| <p>The simulation is terminated by the user, via the console |
| <em>Terminate</em> button (explained below), or</p> |
| </li> |
| <li> |
| <p>A runtime error occurs.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The simulation can be stopped at any time by using the <em>Terminate</em> button |
| (image::./tool-manual/terminate_button.png[]), |
| located at the upper right corner of the console. |
| Note however that if the console does not have the focus, this button may not |
| be visible. If the button is not visible, click somewhere in the console to |
| make the button appear. If even then the button is still not available, it may |
| still appear if you <em>Maximize</em> the console. Also note that the |
| button has no effect while the simulator interactively asks for input from the |
| console. However, once the console input is provided, and <em>ENTER</em> is |
| pressed, the termination request will be processed.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="tool-chapter-command-line">Command line options</h3> |
| <div class="paragraph"> |
| <p>When you run the Chi software from the command line, the interactive dialog |
| as shown in <a href="#tool-chapter-software-operation">Software operation</a> is not shown (at least not by |
| default), and everything has to be specified at the command line instead.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The Chi simulator software takes one input file, which is a filename |
| with <code>.chi</code> extension, or a filename with <code>.cchi</code> extension.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Below is a list of the available options of such a command line. Most of them |
| are for advanced uses only, and not of interest to most users.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="tool-simulator-options">Simulator options</h4> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>--instance=<instance></code>, <code>-i <instance></code></p> |
| <div class="paragraph"> |
| <p>Instantiate the model of the file as given by instance. |
| Default is instantiation of a model without parameters.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tool-general-application-options">General application options</h4> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>--help, -h</code></p> |
| <div class="paragraph"> |
| <p>Prints the help text of the application to the console.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>--option-dialog=<bool></code></p> |
| <div class="paragraph"> |
| <p>Whether to show the option dialog after the command line options have |
| been processed. Default is <code>off</code>.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>--output-mode=<outmode></code>, <code>-m <outmode></code></p> |
| <div class="paragraph"> |
| <p>The output mode. Specify <code>error</code> for errors only; <code>warning</code> for errors |
| and warnings only; <code>normal</code> (default) for errors, warnings, and normal |
| output; or <code>debug</code> for errors, warnings, normal, and debug output.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>--show-license</code></p> |
| <div class="paragraph"> |
| <p>Prints the license text of the application to the console.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>--devmode=<bool></code></p> |
| <div class="paragraph"> |
| <p>Whether exceptional situations return limited user friendly information |
| (<code>--devmode=off</code>), or extended developer oriented information |
| (<code>--devmode=on</code>). |
| Default is user friendly information.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="tool-compiler-options">Compiler options</h4> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>--emf=<bool></code>, <code>-e <bool></code></p> |
| <div class="paragraph"> |
| <p>Whether or not to write the generated EMF model after type checking |
| (default is <code>off</code>).</p> |
| </div> |
| </li> |
| <li> |
| <p><code>--directory=<dir></code>, <code>-d <dir></code></p> |
| <div class="paragraph"> |
| <p>Output directory for generated Java files. Output is not written when the |
| option is empty or not provided.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>--java-compile=<bool></code>, <code>-c <bool></code></p> |
| <div class="paragraph"> |
| <p>Whether or not to perform compilation of the generated Java code (default |
| is <code>on</code>).</p> |
| </div> |
| </li> |
| <li> |
| <p><code>--jar=<bool></code>, <code>-j <bool></code></p> |
| <div class="paragraph"> |
| <p>Whether or not to write the compiled Java simulator classes (default is |
| <code>off</code>).</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="release-notes-chapter-index">Chi release notes</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The release notes for the releases of Chi and the associated tools, as |
| part of the Eclipse ESCET project, are listed below in reverse chronological |
| order.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="version-0-1-unreleased">Version 0.1 (unreleased)</h3> |
| <div class="paragraph"> |
| <p>The first release of Chi as part of the Eclipse ESCET project.</p> |
| </div> |
| <div class="paragraph"> |
| <p></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="legal-chapter-index">Legal</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The material in this documentation is |
| Copyright (c) 2010, 2020 Contributors to the Eclipse Foundation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Eclipse ESCET and ESCET are trademarks of the Eclipse Foundation. |
| Eclipse, and the Eclipse Logo are registered trademarks of the |
| Eclipse Foundation. Other names may be trademarks of their |
| respective owners.</p> |
| </div> |
| <div class="paragraph"> |
| <p><strong>License</strong></p> |
| </div> |
| <div class="paragraph"> |
| <p>The Eclipse Foundation makes available all content in this document |
| ("Content"). Unless otherwise indicated below, the Content is provided to you |
| under the terms and conditions of the MIT License. A copy of the MIT License |
| is available at <a href="https://opensource.org/licenses/MIT" class="bare">https://opensource.org/licenses/MIT</a>. For purposes of the |
| MIT License, "Software" will mean the Content.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you did not receive this Content directly from the Eclipse Foundation, |
| the Content is being redistributed by another party ("Redistributor") and |
| different terms and conditions may apply to your use of any object code in |
| the Content. Check the Redistributor’s license that was provided with the |
| Content. If no such license exists, contact the Redistributor. Unless |
| otherwise indicated below, the terms and conditions of the MIT License |
| still apply to any source code in the Content and such source code may be |
| obtained at <a href="http://www.eclipse.org" class="bare">http://www.eclipse.org</a>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <style> |
| /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */ |
| pre.CodeRay{background:#f7f7f8} |
| .CodeRay .line-numbers{border-right:1px solid currentColor;opacity:.35;padding:0 .5em 0 0} |
| .CodeRay span.line-numbers{display:inline-block;margin-right:.75em} |
| .CodeRay .line-numbers strong{color:#000} |
| table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none} |
| table.CodeRay td{vertical-align:top;line-height:inherit} |
| table.CodeRay td.line-numbers{text-align:right} |
| table.CodeRay td.code{padding:0 0 0 .75em} |
| .CodeRay .debug{color:#fff !important;background:#000080 !important} |
| .CodeRay .annotation{color:#007} |
| .CodeRay .attribute-name{color:#000080} |
| .CodeRay .attribute-value{color:#700} |
| .CodeRay .binary{color:#509} |
| .CodeRay .comment{color:#998;font-style:italic} |
| .CodeRay .char{color:#04d} |
| .CodeRay .char .content{color:#04d} |
| .CodeRay .char .delimiter{color:#039} |
| .CodeRay .class{color:#458;font-weight:bold} |
| .CodeRay .complex{color:#a08} |
| .CodeRay .constant,.CodeRay .predefined-constant{color:#008080} |
| .CodeRay .color{color:#099} |
| .CodeRay .class-variable{color:#369} |
| .CodeRay .decorator{color:#b0b} |
| .CodeRay .definition{color:#099} |
| .CodeRay .delimiter{color:#000} |
| .CodeRay .doc{color:#970} |
| .CodeRay .doctype{color:#34b} |
| .CodeRay .doc-string{color:#d42} |
| .CodeRay .escape{color:#666} |
| .CodeRay .entity{color:#800} |
| .CodeRay .error{color:#808} |
| .CodeRay .exception{color:inherit} |
| .CodeRay .filename{color:#099} |
| .CodeRay .function{color:#900;font-weight:bold} |
| .CodeRay .global-variable{color:#008080} |
| .CodeRay .hex{color:#058} |
| .CodeRay .integer,.CodeRay .float{color:#099} |
| .CodeRay .include{color:#555} |
| .CodeRay .inline{color:#000} |
| .CodeRay .inline .inline{background:#ccc} |
| .CodeRay .inline .inline .inline{background:#bbb} |
| .CodeRay .inline .inline-delimiter{color:#d14} |
| .CodeRay .inline-delimiter{color:#d14} |
| .CodeRay .important{color:#555;font-weight:bold} |
| .CodeRay .interpreted{color:#b2b} |
| .CodeRay .instance-variable{color:#008080} |
| .CodeRay .label{color:#970} |
| .CodeRay .local-variable{color:#963} |
| .CodeRay .octal{color:#40e} |
| .CodeRay .predefined{color:#369} |
| .CodeRay .preprocessor{color:#579} |
| .CodeRay .pseudo-class{color:#555} |
| .CodeRay .directive{font-weight:bold} |
| .CodeRay .type{font-weight:bold} |
| .CodeRay .predefined-type{color:inherit} |
| .CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold} |
| .CodeRay .key{color:#808} |
| .CodeRay .key .delimiter{color:#606} |
| .CodeRay .key .char{color:#80f} |
| .CodeRay .value{color:#088} |
| .CodeRay .regexp .delimiter{color:#808} |
| .CodeRay .regexp .content{color:#808} |
| .CodeRay .regexp .modifier{color:#808} |
| .CodeRay .regexp .char{color:#d14} |
| .CodeRay .regexp .function{color:#404;font-weight:bold} |
| .CodeRay .string{color:#d20} |
| .CodeRay .string .string .string{background:#ffd0d0} |
| .CodeRay .string .content{color:#d14} |
| .CodeRay .string .char{color:#d14} |
| .CodeRay .string .delimiter{color:#d14} |
| .CodeRay .shell{color:#d14} |
| .CodeRay .shell .delimiter{color:#d14} |
| .CodeRay .symbol{color:#990073} |
| .CodeRay .symbol .content{color:#a60} |
| .CodeRay .symbol .delimiter{color:#630} |
| .CodeRay .tag{color:#008080} |
| .CodeRay .tag-special{color:#d70} |
| .CodeRay .variable{color:#036} |
| .CodeRay .insert{background:#afa} |
| .CodeRay .delete{background:#faa} |
| .CodeRay .change{color:#aaf;background:#007} |
| .CodeRay .head{color:#f8f;background:#505} |
| .CodeRay .insert .insert{color:#080} |
| .CodeRay .delete .delete{color:#800} |
| .CodeRay .change .change{color:#66f} |
| .CodeRay .head .head{color:#f4f} |
| </style> |
| <script type="text/x-mathjax-config"> |
| MathJax.Hub.Config({ |
| messageStyle: "none", |
| tex2jax: { |
| inlineMath: [["\\(", "\\)"]], |
| displayMath: [["\\[", "\\]"]], |
| ignoreClass: "nostem|nolatexmath" |
| }, |
| asciimath2jax: { |
| delimiters: [["\\$", "\\$"]], |
| ignoreClass: "nostem|noasciimath" |
| }, |
| TeX: { equationNumbers: { autoNumber: "none" } } |
| }) |
| MathJax.Hub.Register.StartupHook("AsciiMath Jax Ready", function () { |
| MathJax.InputJax.AsciiMath.postfilterHooks.Add(function (data, node) { |
| if ((node = data.script.parentNode) && (node = node.parentNode) && node.classList.contains('stemblock')) { |
| data.math.root.display = "block" |
| } |
| return data |
| }) |
| }) |
| </script> |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_HTMLorMML"></script> |
| <!-- |
| Copyright (c) 2010, 2020 Contributors to the Eclipse Foundation |
| |
| See the NOTICE file(s) distributed with this work for additional |
| information regarding copyright ownership. |
| |
| This program and the accompanying materials are made available under the terms |
| of the MIT License which is available at https://opensource.org/licenses/MIT |
| |
| SPDX-License-Identifier: MIT |
| --> |
| |
| <div id="footer"> |
| <div id="footer-text"> |
| <a href="https://www.eclipse.org">Eclipse Home</a> |
| | |
| <a href="https://www.eclipse.org/legal/privacy.php">Privacy Policy</a> |
| | |
| <a href="https://www.eclipse.org/legal/termsofuse.php">Terms of Use</a> |
| | |
| <a href="https://www.eclipse.org/legal/copyright.php">Copyright Agent</a> |
| | |
| <a href="https://www.eclipse.org/legal">Eclipse Legal</a> |
| </div> |
| </div> |
| </body> |
| </html> |
