Readme for the Petri Net Cube/ Petri Net Hyper Cube tool, that can be used with the Petri Net Kernel since v2.2: Table of Contents ----------------- * Short Explanation - What is the Petri Net Cube? * How to use the Petri Net Cube? * The standard net types of the PNCube * Properties and features of the standard net types + BlackToken nets + ColoredToken nets * Using variables and functions in ColoredToken nets * The Petri Net Hyper Cube + The 3rd dimension: Arc types + The 4th dimension: Step structure + The 5th dimension: Step verification + The 6th dimension: Step selection + Simulation with the PNHC firing rule * PNCube Package listing Short Explanation - What is the Petri Net Cube? ----------------------------------------------- The Petri Net Cube is a tool that makes use of the new ability of the Petri Net Kernel (since version 2.1) to create parametric nets. That means that the net type specification for a PNCube net will be dynamicly created depending on certain special parameters, which will be passed when loading a net or creating a new PNCube net. This ability allows the PNCube to provide an interface to deal with all standard petri net types, only by specifying a few parameters. In addition it is quite simple to extend the abilities of the Petri Net cube to use more special net types. How to use the Petri Net Cube? ------------------------------ It is quite easy to use the PNCube. You have two things to do before you can start. At first you must write a NetTypeFactory configuration file or you use the default config file (config/PNCubeConfig.xml) which comes with the PNCube tool. This is an xml-file which descibes all parameters, the possible choices for every parameter and the effect of every choice. The second thing to do is to write a special net type specification to make use of parametric nets. Here is the default net type specification for PNCube nets: You have to specify an executable, that can handle parameters and you must specify the config file you have described before to enable the executable to evaluate the parameters. Every executable must inherit from MetaNetType. As executable for the PNCube net type we use the NetTypeFactory. The NetTypeFactory displays a dialog, if you create a new PNCube net, where you can choose the parameters for your net. If you save the Net the chosen parameters will be saved with it, coded in the net type name E.g. a PNCube net with two parameters Param1 and Param2 will be saved as: ... ... If you have specified the new net type in your tool specification, you are able to use the Petri Net Cube. Simply create a new PNCube net, choose the parameters for your net and you can edit and simulate or run applications on the net as usual. For special properties of the standard net types, that are already implemented, see the next chapter. The standard net types of the PNCube ------------------------------------- The current version of the Petri Net Cube has two dimensions. That means every PNCube net has two parameters, that specify the concrete net type. The first dimension (parameter) specifies the token type that is used in the net. Those two token types are already implemented: * BlackTokens : One BlackToken can not be distinguished from another. BlackTokens are represented by a star (*) * ColoredTokens: Two ColoredTokens can be different. A colored token can have any representation. The second dimension is the marking type. The marking type is a kind of rule, that describes how multiple tokens are combined to one marking and some operations on markings. The following marking types are already implemented: * Set marking: Allows only one token with the same representation. * MultiSet: Allows multiple token with the same representation. * Sequence: Allows multiple token with the same representation. Uses FIFO concept to add and subtract tokens to/from the marking. This two dimensions are enough to describe all standard net types. In the following table you can find the net types that can be used with the pre-implemented parameters: token type/ marking type | Set MultiSet Sequence -------------------------+-------------------------------------- BlackToken | C/E-Net P/T-Net (P/T-Net) ColoredToken | Pr./Tr.-Net CPN FIFO-Net Properties and features of the standard net types ------------------------------------------------- * BlackToken nets: Nets with black tokens are quite simple. The only symbol that is allowed in place markings is a star, which represents one black token. A whitespace is used to separate two tokens, if you want to have more than one token on a place. Arc inscriptions are treated just as place markings. There is only one difference: Inscriptions can also keep constants, which represent multiple black tokens (E.g. the number 5 is equal with five black token [* * * * *]). Remark: You can also use constants on place markings, but they will be replaced immediately by the correct number of stars. * ColoredToken nets: These nets offer a bit more possibilities than BlackToken nets. Place markings: Every colored token can be represented by any string. The only character, that such a string can not contain is a whitespace, since this sign is reserved for separation of multiple tokens (equal to black token markings). Inscriptions: Besides simple colored tokens (like place markings) inscriptions can also contain variables and functions. Variables look like any other colored tokens. The only difference is that variables must be declared before (see next chapter). Funtions must be declared, too. The declaration of functions is also described in the next chapter. However, function calls must also follow a special syntax. The following regulary expression shows the syntax of function calls in inscriptions: Function_Name'('[parameter{','parameter}]')' The function name is immediately followed by an opening parenthesis. The following parameter list is separated by commas (no whitespaces!). The closing parenthesis terminates the parameter list. Using variables and functions in ColoredToken nets -------------------------------------------------- Before you are able to use functions or variables in an inscription you have to register them. The registration of variables is quite easy. Every variable is local to one transition, that means it belongs to this transition and you can only use the variable in inscriptions on arcs, which are connected with this transition, where you declared the variable. The concept allows you to use different variables with the same name on two different transitions. To register a variable you have to edit a special extension, called "Variables", of the desired transition. Simply enter the name of the variable, you want to register - that's all. If you want to register more than one variable, you can also enter a list of variables separated by one or more of the following characters: [ ,\n\t]. To use a function you have to attend to the following four steps: 1. Write a static java function: The signature of java functions you can use with the PNCube is quite restricted: Every parameter of your function must have the type java.util.Vector, because the PNCube passes the arguments as a Vector of tokens. You decide, whether you evaluate only the first token of every parameter, or the whole vector (if it makes sense; e.g. for the section of two sets). The return value of your function must also be a vector of tokens. You can easily produce new tokens, if you use the getNewToken method of one of the passed tokens (see api documentation for more information). A valid signature could look like this: public static Vector example1(Vector param1, Vector param2) The java class exampleFunctions, that comes with the PNCube contains some more examples. 2. Register your function in a function table: A function table is an XML file, that contains an abstract signature for every function and the class name of the class where the function can be found. For example a function table could look like this: The parameters "token" and "marking" in the signature are special key words. The key word "token" means that only one token will be passed to the corresponding parameter. If you declare a parameter as "marking" parameter, zero or more tokens can be passed. (In this case the function should evaluate the whole Vector of this parameter!!) The attribute class must contain the whole (relative) path to the class where the function can be found. 3. Edit your PNCube net. 4. Register your function in the net: Every colored token net has an extension called "Functions". There you can enter the functions, that you want to register. At first you have to specify the location of your function table. Therefor use the key word "path". E.g.: path=myPath/myFunctionTable.xml In the next line you can load/register the desired function from this function table using the key word "functions". E.g.: functions=fct1(token,token), fct2(token,marking) You must enter exactly the same signature, you have entered in the function table. If you enter a list of functions, you can separate the single signatures with one or more of the following characters: [ ,;\t]. In the next line you could use the "path" key word again to specify another function table or you use "functions" to register other functions from the current function table, and so on. Now you can use your function in any arc inscription of the net. The Petri Net Hyper Cube ------------------------ The Petri Net Hyper Cube is an extended version of the Petri Net Cube. It supports much more (special) net types. The biggest difference is the new step firing rule, that allows the user to fire multiple transitions at once. Therefore new dimensions are nessecary. All together the PNHCube now consists of six dimenesions: * The first two dimensions (token structure and marking structure), that you already know from the PNCube have not been changed. * The 3rd dimension offers the possibility to use more special arc types, that support many different operations. See the chapter "The 3rd dimension: Arc types" for more detailed information. * The 4th dimension determines the structure of steps. That means it descibes, how multiple transition(-mode)s can be combined. For more information about this parameter see chapter "The 4th dimension: Step structure". * The 5th dimension is used to restrict the number of possible steps for special simulation purposes. More about that in the chapter "The 5th dimension: Step verification". * The 6th dimension is also used to restrict the number of possible steps. For differences between the 5th and the 6th dimension see the chapter "The 6th dimension: Step selection". What do you have to do to use the Petri Net Hyper Cube? Simply write a new net type specification (e.g. PNHCube.xml) as seen above and use the file "PNHCubeConfig.xml" (it comes with the PNC/PNHC tool) instead of "PNCubeConfig.xml". The configuration file contains the description of all PNHC parameters. The 3rd dimension: Arc types ---------------------------- In addition to the two standard dimensions the PNHC has a third dimension that allows the user to deal with more special arc types, that support many different operations. If you create a new PNHC net, you must select one of the two possible values for the third parameter: + Choosing "default" arc types you will recognize no difference to the standard Petri Net Cube arc types. * The "extended" choice will make the new features of the PNHC available. Now every arc has a new extension called "type". The value of this extension defines the operation of the corresponding arc. If you create a new arc, the "type" extension has the standard value "default". It means, that the behavior of this arc is equal to the known behavior of a standard PNC arc ((POT.IN,SUB) on incomming edges and (POT.OUT,ADD) on outgoing edges). If you don't want this arc to be "default", you must specify its behavior editing the type extension. The behavior must be descibed by two parameters: 1. test condition 2. event (= action of the arc) The syntax of valid arc type expressions is simply: (condition, event) where condition and event can have one of the following values: * possible conditions and their meaning: - POT.OUT : Can the inscription be added to the place marking? - POT.IN : Can the inscription be subtracted from the place marking? - NO : No test condition! - EQUAL : Is the inscription equal to the place marking? - ZERO : Is the place marking empty (contains no token)? - PUT-INHIB: Can the inscription NOT! be added to the place marking? (= NOT POT.OUT) - INHIB : Can the inscription NOT! be subtracted from the place marking? (= NOT POT.IN) * possible events: - TEST : No effect! - ADD : Add the inscription to the place marking! - SUB : Subtract the inscription from the place marking! - RESERVE: Reserve a part of the place marking, which is equal to the inscription value! - SET : Set the place marking to the inscription value! - CLEAR : Clear the place marking! - REFRESH: Refresh the place marking! Valid extension values are e.g. (EQUAL,TEST) = test wether the place marking is equal to the inscription of the arc (no action) (POT.IN,SUB) = default action of incomming edges (POT.OUT,ADD) = default action of outgoing edges ATTENTION! Not every combination of conditions and events will make sense. E.g. (PUT-INHIB, ADD) will cause the transition to be never active, because either the test condition will be false or the effect will not be defined. (see "The effect of arc types during simulation" for more information) Remark: If you the edited "type" extension value, using an invalid syntax it will be immediately replaced by the 'default' value. + The effect of arc types during simulation: A transition can be fired, if every connected arc is active and the cumulative effect of every arc is defined. An arc is active, if the test condition of the arc (enable signal) is true. What means, the cumulative effect must be defined? This means, that the effect of every arc must be defined with respect to the effect of all other arcs connected with the same transition. E.g. two arcs want to subtract a token T from the the same place and are connected with the same transition. In this case the transition can only be concessioned, if the place marking contains at least two tokens T. (after subtraction of the first token T by the first arc there must be at least one T-token left to provide the second arc). The 4th dimension: Step structure --------------------------------- The step structure determines the structure of steps. That is the way how transition modes can be combined to create a valid step. What are transition modes? A transition mode is a pair of one transition and its internal state. The internal state consists of all variables of that transition and their assigned values. Possible step structures are for example: * sets of transition modes (see StepStrucSet.java) * multi set of modes (see StepStrucMulti.java) * single sets of modes (see StepStrucSingle.java). Example: If you have the transition modes {TM1, TM2} following structures could be valid steps: * set : {TM1}, {TM2}, {TM1, TM2} * multi set : {TM1}, {TM2}, {TM1, TM2}, but also {TM1, TM1}, {TM1, TM2, TM2}, ... * single set : {TM1}, {TM2} For more information about the implementation of step structures see one of the following example source files: StepStructSet.java, StepStructMulti.java or StepStructSingle.java. The 5th dimension: Step verification ------------------------------------ The step verification parameter is a kind of filter for valid steps. It can be used to permit only steps with a special property. To create a user-defined "filter", you must write your own step verification predicate, but it is quite simple. There are already some example implementations, that come with the PNC package (they are registered in the PNHC config file, so you can choose one of them, when you create a new PNHC net): * StepVeriDefault.java: is a very simple filter, which does not restrict the valid steps at all (It's a really short and easy to read file. That's why to read this file is the best way to get an impression of what you have to do to write your own step verifiction predicate). * StepVeriNoSC.java: only step, which contain no self concurrent transitions are valid steps and can be fired during simulation. It is also a quite short file, but this time with a real "filter" algorithm. Restricting the steps, using a step verification predicate, can enhance the simulation performance. The 6th dimension: Step selection --------------------------------- This dimension also contains filter predicates, the so called step selection predicates. You can write your own step selection predicate. Look at one of the following example implementaions for more information: * StepSelectAll.java: it's analogous to StepVeriDefault.java, but a step selection. The predicate does not restrict the steps and the file is quite easy to read. Take a look at this at first, if you want to write your own selection. * StepSelectMax.java: select only maximal steps (with a maximum number of transition modes. Take a look at this file to get more information about how to implement such an algorithm. The difference between step verification and step selection: So, I think the question, that you have now is: What is the difference between the 5th and the 6th dimension (step verification and step selection)? The question, you should ask to answer the question is: What knowledge do I need to implement my own filter algorithm? If you need knowledge about all steps to decide, whether one step is valid or not, you must implement a step selection predicate. StepSelectMax is a good example for that, because you must know if there are larger steps to decide, whether one step is a maximal step or not. If you don't need knowledge of all the other steps, you should implement a step verification predicate. You could also implement a step selection predicate (because it's more general), but to implement a step verification is a bit easier and faster. Simulation with the PNHC firing rule ------------------------------------ To simulate PNC/PNHC nets with the PNHCRule you can use the standard simulator of the Petri Net Kernel. When you start the simulator all concessioned transitions will be emphasized as usual. The only difference, that you will notice, is the extended dialog box, that is displayed during simulation. Now click on one concessioned transition to selected it. If necessary you will be prompted to select a transition mode (assign a value to every variable) from a list. In distinction from other firing rules the selected transition will not be fired immediately. You only add the transition to the step, that you want to fire. Dependant from the net type, the concessioned transitions after your selection will be displayed and you can add another transition mode and so on (e.g. If your step structure is a single set, you can only choose one transition mode. So there will be no transition concessioned after your first choice). You can reset your choice, using the reset button of the dialog box. If your current choice is a valid step the fire button of the dialog will be active and you can press it to fire your selected step. You can also directly choose a step from a list using the steps button, but it can be quite irritating, especially if there are many larger steps listed. The listed "steps" represent only the missing transition modes, after the current selection, that are needed to complete a valid step. So the list will get smaller, every time you select a new transition mode. The cancel button of the dialog box can be used to aboard the simulation. Another element of the dialog is the auto-fire check box. If it is checked, your current selection will be fired as soon as it is a valid step. It makes the firing action a bit more comfortable, especially for single sets of transition modes, because you don't have to press the fire button every time after your selection. The simulation process ends, if there are no concessioned transitions, or if you aboard it manually pressing the cancel button. PNCube Package listing ---------------------- + ArcType.java : the arc type extension of the Petri Net Hyper Cube + BlackToken.java : implementation of the token type BlackToken + ColoredToken.java : implementation of the token type ColoredToken + EmptyToken.java : implementation of the token type EmptyToken (only for internal use) + FireDialog.java : this dialog is used by the PNHCRue + FunctionTable.xml : the function table for exampleFunctions.java + Functions.java : the "Functions" extension of ColoredToken nets + PNCMarkingInterface.java : super class for all marking types + PNCMultiSet.java : implementation of the marking type MultiSet + PNCSequence.java : implementation of the marking type Sequence + PNCSet.java : implementation of the marking type: Set + PNCTokenInterface.java : super class for all token types + PNHCRule.java : a universal firing rule for all PNCube/ PNHCube net types + SelectMode.java : another dialog used by the PNHCRule + StepSelectAll.java : an example implementation for a step selection predicate + StepSelectMax.java : an example implementation for a step selection predicate + StepSelection.java : the super class for all step selection predicates + StepStruct.java : the super class for all step structures + StepStructMulti.java : an example for a step structure (multi set of transition modes) + StepStructSet.java : an example for a step structure (set of transition modes) + StepStructSingle.java : an example for a step structure (single set transition modes) + StepVeriDefault.java : an example implementation for a step verification predicate + StepVeriNoSC.java : an example implementation for a step verification predicate + StepVerification.java : the super class for all step verification predicates + TMode.java : all transition modes must have that type + Variables.java : the "Variables" extension of transitions in ColoredToken nets + exampleFunctions.java : some example functions for ColoredToken nets + readme.txt : this readme file