class OverView "Overview of library"
extends Modelica.Icons.Information;
annotation (Documentation(info = "<html>\n<p>\nIn this section, an overview of the most important features\nof this library is given.\n</p>\n<h4>Steps and Transitions</h4>\n<p>\nA <strong>StateGraph</strong> is an enhanced finite state machine.\nIt is based on the JGrafchart method and\ntakes advantage of Modelica features for\nthe \"action\" language. JGrafchart is a further development of\nGrafcet to include elements of StateCharts that are not present\nin Grafcet/Sequential Function Charts. Therefore, the StateGraph\nlibrary has a similar modeling power as StateCharts but avoids\nsome deficiencies of StateCharts.\n</p>\n<p>\nThe basic elements of StateGraphs are <strong>steps</strong> and <strong>transitions</strong>:\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/StateGraph/UsersGuide/StepAndTransition1.png\">\n</p>\n\n<p>\n<strong>Steps</strong> represent the possible states a StateGraph can have.\nIf a step is active the Boolean variable <strong>active</strong> of\nthe step is <strong>true</strong>. If it is deactivated,\n<strong>active</strong> = <strong>false</strong>. At the initial time, all \"usual\"\nsteps are deactivated. The <strong>InitialStep</strong> objects are steps\nthat are activated at the initial time. They are characterized\nby a double box (see figure above).\n</p>\n<p>\n<strong>Transitions</strong> are used to change the state of a StateGraph.\nWhen the step connected to the input of a transition is active,\nthe step connected to the output of this transition is deactivated\nand the transition condition becomes true, then the\ntransition fires. This means that the step connected to the input to the\ntransition is deactivated and the step connected to the output\nof the transition is activated.\n</p>\n<p>\nThe transition <strong>condition</strong> is defined via the parameter menu\nof the transition object. Clicking on object \"transition1\" in\nthe above figure, results in the following menu:\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/StateGraph/UsersGuide/StepAndTransition2.png\">\n</p>\n\n<p>\nIn the input field \"<strong>condition</strong>\", any type of time varying\nBoolean expression can be given (in Modelica notation, this is\na modification of the time varying variable <strong>condition</strong>).\nWhenever this condition is true, the transition can fire.\nAdditionally, it is possible to activate a timer, via\n<strong>enableTimer</strong> (see menu above) and provide a\n<strong>waitTime</strong>. In this case the firing of the transition\nis delayed according to the provided waitTime. The transition\ncondition and the waitTime are displayed in the transition icon.\n</p>\n<p>\nIn the above example, the simulation starts at <strong>initialStep</strong>.\nAfter 1 second, <strong>transition1</strong> fires and <strong>step1</strong> becomes\nactive. After another second <strong>transition2</strong> fires and\n<strong>initialStep</strong> becomes again active. After a further\nsecond <strong>step1</strong> becomes again active, and so on.\n</p>\n<p>\nIn JGrafcharts, Grafcet and Sequential Function Charts, the\nnetwork of steps and transitions is drawn from top to bottom.\nIn StateGraphs, no particular direction is defined, since\nsteps and transitions are blocks with input and output connectors\nthat can be arbitrarily placed and connected. Usually, it is\nmost practical to define the network from left to right,\nas in the example above, since then it is easy to read the\nlabels on the icons.\n</p>\n<h4>Conditions and Actions</h4>\n<p>\nWith the block <strong>TransitionWithSignal</strong>, the firing condition\ncan be provided as Boolean input signal, instead as entry in the\nmenu of the transition. An example is given in the next\nfigure:\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/StateGraph/UsersGuide/StepAndTransition3.png\">\n</p>\n\n<p>\nComponent \"step\" is an instance of \"StepWithSignal\" that is\na usual step where the active flag is available as Boolean\noutput signal. To this output, component \"Timer\" from\nlibrary \"Modelica.Blocks.Logical\" is connected. It measures the\ntime from the time instant where the Boolean input (i.e., the\nactive flag of the step) became true up to the current\ntime instant. The timer is connected to a comparison\ncomponent. The output is true, once the timer reaches\n1 second. This signal is used as condition input of the\ntransition. As a result, \"transition2\" fires, once step\n\"step\" has been active for 1 second.\nOf course, any other\nModelica block with a Boolean output signal can be\nconnected to the condition input of such a transition block\nas well.\n</p>\n<p>\nConditions of a transition can either be computed by\na network of logical blocks from the Logical library as\nin the figure above, or via the \"SetBoolean\" component\nany type of logical expression can be defined in textual\nform, as shown in the next figure:\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/StateGraph/UsersGuide/StepAndTransition4.png\">\n</p>\n\n<p>\nWith the block \"<strong>SetBoolean</strong>\", a time varying expression\ncan be provided as modification to the output signal <strong>y</strong>\n(see block with icon text \"timer.y > 1\" in the figure above).\nThe output signal can be in turn connected to the condition\ninput of a TransitionWithSignal block.\n</p>\n<p>\nThe \"<strong>SetBoolean</strong>\" block can also be used to\ncompute a Boolean signal depending on the active step.\nIn the figure above, the output of the block with the\nicon text \"step.active\" is\ntrue, when \"step\" is active, otherwise it is false\n(note, the icon text of \"SetBoolean\" displays the modification\nof the output signal \"y\").\nThis signal can then be used to compute desired <strong>actions</strong>\nin the physical systems model. For example, if a <strong>valve</strong>\nshall be open, when the StateGraph is in \"step1\" or\nin \"step4\", a \"SetBoolean\" block may be connected to the\nvalve model using the following condition:\n</p>\n<pre>\n valve = step1.active <strong>or</strong> step2.active\n</pre>\n<p>\nVia the Modelica operators <strong>edge</strong>(..) and <strong>change</strong>(..),\nconditions depending on rising and falling edges of\nBoolean expressions can be used when needed.\n</p>\n<p>\nIn JGrafcharts, Grafcet, Sequential Function Charts and StateCharts,\n<strong>actions</strong> are formulated <strong>within a step</strong>. Such actions are\ndistinguished as <strong>entry</strong>, <strong>normal</strong>, <strong>exit</strong> and\n<strong>abort</strong> actions. For example, a valve might be opened by\nan entry action of a step and might be closed by an exit\naction of the same step. In StateGraphs, this is (fortunately)\n<strong>not possible</strong>\ndue to Modelica's \"single assignment rule\" that requires that every\nvariable is defined by exactly one equation. Instead, the\napproach explained above is used. For example, via the\n\"SetBoolean\" component, the valve variable is set to true\nwhen the StateGraph is in particular steps.\n</p>\n<p>\nThis feature of a StateGraph is <strong>very useful</strong>, since it allows\na Modelica translator to <strong>guarantee</strong> that a given StateGraph\nhas always <strong>deterministic</strong> behaviour without conflicts.\nIn the other methodologies this is much more cumbersome. For example,\nif two steps are executed in parallel and both step actions\nmodify the same variable, the result is either non-deterministic\nor non-obvious rules have to be defined which action\ntakes priority. In a StateGraph, such a situation is detected by\nthe translator resulting in an error, since there are two equations\nto compute one variable. Additional benefits of the StateGraph\napproach are:\n</p>\n<ul>\n<li> A JGrafchart or a StateChart need to potentially access\n variables in a step that are defined in\n higher hierarchical levels of a model. Therefore, mostly <strong>global\n variables</strong> are used in the whole network, even if the\n network is structured hierarchically. In StateGraphs this\n is not necessary, since the physical systems outside\n of a StateGraph might access the step or transition state\n via a hierarchical name. This means that <strong>no global variables</strong>\n are needed, because the local variables in the StateGraph\n are accessed from local variables outside of the StateGraph.\n </li>\n<li> It is simpler for a user to understand the information that\n is provided in the non-graphical definition, since every\n variable is defined at exactly one place. In the other\n methodologies, the setting and re-setting of the same\n variable is cluttered within the whole network.\n </li>\n</ul>\n<p>\nTo emphasize this important difference between these methodologies,\nconsider the case that a state machine has the following\nhierarchy:\n</p>\n<pre>\n stateMachine.superstate1.superstate2.step1\n</pre>\n<p>\nWithin \"step1\" a StateChart would, e.g., access variable\n\"stateMachine.openValve\", say as \"entry action: openValve = true\".\nThis typical usage has the severe drawback that it is not possible\nto use the hierarchical state \"superstate1\" as component in another\ncontext, because \"step1\" references a particular name outside of this\ncomponent.\n</p>\n<p>\nIn a StateGraph, there would be typically a \"SetBoolean\" component\nin the \"stateMachine\" component stating:\n</p>\n<pre>\n openValve = superstate1.superstate2.step1.active;\n</pre>\n<p>\nAs a result, the \"superstate1\" component can be used in\nanother context, because it does not depend on the environment\nwhere it is used.\n</p>\n<h4>Execution Model</h4>\n<p>\nThe execution model of a StateGraph follows from its\nModelica implementation: Given the states of all steps, i.e.,\nwhether a step is active or not active, the equations of all\nsteps, transitions, transition conditions, actions etc. are\nsorted resulting in an execution sequence to compute\nessentially the new values of the steps. If conflicts occur,\ne.g., if there are more equations as variables, of if there\nare algebraic loops between Boolean variables, an exception\nis raised. Once all equations have been processed, the\n<strong>active</strong> variable of all steps are updated to the newly\ncalculated values. Afterwards, the equations are again\nevaluated. The iteration stops, once no step changes\nits state anymore, i.e., once no transition fires anymore.\nThen, simulation continuous until a new event is triggered,\n(when a relation changes its value).\n</p>\n<p>\nWith the Modelica \"sampled(..)\" operator, a StateGraph might also\nbe executed within a discrete controller that is called\nat regular time instants. In a future version of the StateGraph\nlibrary, this might be more directly supported.\n</p>\n<h4>Parallel and Alternative Execution</h4>\n<p>\nParallel activities can be defined by\ncomponent <strong>Parallel</strong> and alternative activities\ncan be defined by component <strong>Alternative</strong>.\nAn example for both components is given in the next figure.\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/StateGraph/UsersGuide/Parallel1.png\">\n</p>\n\n<p>\nHere, the branch from \"step2\" to \"step5\" is executed in parallel\nto \"step1\". A transition connected to the output of a parallel\nbranch component can only fire if the final steps\nin all parallel branches are active simultaneously.\nThe figure above is a screen-shot from the animation of the\nStateGraph: Whenever a step is active or a transition can fire,\nthe corresponding component is marked in <strong>green</strong> color.\n</p>\n<p>\nThe three branches within \"step2\" to \"step5\" are\nexecuted alternatively, depending which transition condition\nof \"transition3\", \"transition4\", \"transition4a\" fires first.\nSince all three transitions fire after 1 second, they are all\ncandidates for the active branch. If two or more transitions\nwould fire at the same time instant, a priority selection\nis made: The alternative and parallel components have a\nvector of connectors. Every branch has to be connected to\nexactly one entry of the connector vector. The entry with\nthe lowest number has the highest priority.\n</p>\n<p>\nParallel, Alternative and Step components have vectors of\nconnectors. The dimensions of these vectors are set in the\ncorresponding parameter menu. E.g. in a \"Parallel\" component:\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/StateGraph/UsersGuide/Parallel2.png\">\n</p>\n\n<p>\nCurrently in Dymola the following menu pops up, when a branch\nis connected to a vector of components in order to define\nthe vector index to which the component shall be connected:\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/StateGraph/UsersGuide/Parallel3.png\">\n</p>\n\n<h4>CompositeSteps, Suspend and Resume Port</h4>\n<p>\nA StateGraph can be hierarchically structured by using a <strong>CompositeStep</strong>.\nThis is a component that inherits from <strong>PartialCompositeStep</strong>.\nAn example is given in the next figure (from Examples.ControlledTanks):\n</p>\n\n<p>\n<img src=\"modelica://Modelica/Resources/Images/StateGraph/UsersGuide/CompositeStep1.png\">\n</p>\n\n<p>\nThe CompositeStep component contains a local StateGraph that is\nentered by one or more input transitions and that is left\nby one or more output transitions. Also, other needed signals\nmay enter a CompositeStep. The CompositeStep has similar properties\nas a \"usual\" step: The CompositeStep is <strong>active</strong> once at least\none step within the CompositeStep is active. Variable <strong>active</strong>\ndefines the state of the CompositeStep.\n</p>\n<p>\nAdditionally, a CompositeStep has a <strong>suspend</strong> port. Whenever the\ntransition connected to this port fires, the CompositeStep is left\nat once. When leaving the CompositeStep via the suspend port, the internal\nstate of the CompositeStep is saved, i.e., the active flags of all\nsteps within the CompositeStep. The CompositeStep might be entered via\nits <strong>resume</strong> port. In this case the internal state from the\nsuspend transition is reconstructed and the CompositeStep continues\nthe execution that it had before the suspend transition fired\n(this corresponds to the history ports of StateCharts or JGrafcharts).\n</p>\n<p>\nA CompositeStep may contain other CompositeSteps. At every level,\na CompositeStep and all of its content can be left via its suspend ports\n(actually, there\nis a vector of suspend connectors, i.e., a CompositeStep might\nbe aborted due to different transitions).\n</p>\n</html>"));
end OverView;