Overview

This tool expects a set of paths to PNML files or to directories as arguments, where to find the PNML files. It will recursively scan directories and their sub-directories, looking for PNML files.

You may provide a mix of paths to PNML files and directories containing them.

Important note

Since version 3.0.0, pnml2nupn runs on Java 11+. Consequently, versions 3.x.x of pnml2nupn will not run on Java below 11.

Basic command-line invocation

The basic command-line invocation is the following (update the name of the jar file with the version you are using):

java -jar pnml2nupn-latest-version.jar pathToPNMLFile [pathToFolder pathToAnotherPNMLFile ...]

Advanced command-line invocation

Advanced invocation includes arguments for the JVM:

java -server -Xmx2g -Xmn128m -XX:NewSize=2g -XX:MaxNewSize=2g -XX:+UseNUMA -jar pnml2nupn-latest-version.jar pathToFile [pathToFolder pathToAnotherFile ...]

In particular, increase the value of -Xmx argument which allocates max memory to the heap, when you are dealing with very large input files. In the above invocation, it is set to 2 GB.

Invocation using a Shell script

We provide a Shell script to help you increase productivity in using the PNML to NuPN Converter. Feel free to use it and adapt it to your environment.

Before you use this script, you must first set in the script the path to the Java executable (i.e., java or java.exe) in your OS.

The above set of advanced arguments for the Java VM is included in the script, so that you can start with and modify them to your system's settings. However, they are not included in the invocation of java by default. Please, set them as you see fit for your environment.

For instance, the -Xmx argument allocates some max amount of memory to the heap. If you mostly deal with small PNML documents (a few hundreds KB), we advise you decrease it (current setting is 2 GB). If you use large documents, (a few hundreds MB to GB), then you should increase it in order to avoid out-of-memory errors.

The Shell script also contains some properties and a debug environment variable for pnml2nupn, that you can enable or disable. See below.

Output since version 3.0.0

Upon successful execution, this tool will output a single file:

  • A *.nupn file that contains the Nested Unit Petri Net obtained from the PNML P/T translation. Mappings between PNML places ids and their NUPN counterparts are included in the NUPN file. The same holds for mappings between PNML transition ids and their NUPN counterparts.

Output before version 3.0.0

Upon successful execution, this tool will output 3 files:

  • A *.nupn file that contains the Nested Unit Petri Net obtained from the PNML P/T translation;
  • A *.places file that contains the mapping between the places ids from PNML and their counterparts in NUPN;
  • A *.trans file that contains the mapping between the transitions ids from PNML and their counterparts in NUPN.

Optional Output

  • A *.unsafe.arcs file is optionally generated, that contains the list of unsafe arcs (one per line) in the original Petri Net (from PNML) and their respective inscriptions, in the form:

    sourceNodeId arcId targetNodeId #inscription.

    The ids come from the PNML file. This file will be created only if:

    • Option has.unsafe.arcs is activated. In this case, only the *.unsafe.arcs file will be output;
    • options generate.unsafe AND remove.unsafe.trans are activated (see below) and at least an unsafe transition was removed. This behaviour is supported up to v1.2.2 of this tool.

Note: All the output files will be located near the input PNML one.

Debug information

In case of error, you may want the program to print the stack trace, to provide the tool author with useful information for debugging. To enable debug information, set the PNML2NUPN_DEBUG environment variable to true before invoking this tool.

Supporting versions

Since v1.3.0.

Up to v1.2.2, use the PNML2BPN_DEBUG environment variable instead.

Options

This tool supports some options (technically speaking: properties) that you might activate to change its behaviour.

First place number

This option makes the translator use an arbitrary starting number for providing Ids to NUPN places, instead of the default 0..N-1.

To enable this property, proceed like so (replace 1 with the starting number you want):

java -Dfirst.place.number=1 ...

The default value for this option is 0.

  • Supporting versions

    Since v3.1.0.

First transition number

This option makes the translator use an arbitrary starting number for providing Ids to NUPN transitions, instead of the default 0..N-1.

To enable this property, proceed like so (replace 1 with the starting number you want):

java -Dfirst.transition.number=1 ...

The default value for this option is 0.

  • Supporting versions

    Since v3.1.0.

Use place names

This option makes the translator use place names instead of their ids for the mappings PNML id / NUPN id in the labels section of the NUPN file. When there is a NUPN toolspecific section in the PNML the extraction of the NUPN ignores this option (since the grammar of that section requires the list of places to be IDREFs - references to IDs).

To enable this property, proceed like so:

java -Duse.place.names=true ...

The default value for this option is false.

  • Supporting versions

    Since v3.0.2.

Use transition names

This option makes the translator use place names instead of their ids for the mappings PNML id / NUPN id in the labels section of the NUPN file. When there is a NUPN tool specific section in the PNML the extraction of the NUPN ignores this option (since the grammar of that section requires the list of places to be IDREFs - references to IDs).

java -Duse.transition.names=true ...

The default value for this option is false.

  • Supporting versions

    Since v3.0.2.

Preserve NUPN in native mode

With this option, if there is a NUPN toolspecific section in the PNML document, it will be directly considered to extract and produce the NUPN files. This option takes precedences over the preserve.nupn.mix mode (see below). Set this option if you are aware of a NUPN toolspecific section in the PNML document, and you want to extract exactly the NUPN stored in that section.

To enable this property, proceed like so:

java -Dpreserve.nupn.native=true ...

The default value for this option is false.

  • Supporting versions

    Since v2.3.0.

Preserve NUPN in mixed mode

With this option, if there is a NUPN toolspecific section in the PNML document, it will be considered while exporting to NUPN with the default generation strategy, i.e. one place per unit. The default strategy prevails, but it is guided with information from the NUPN toolspecific section to produce the final *.nupn file.

To set this property, proceed like so:

java -Dpreserve.nupn.mix=true ...

The default value for this option is false.

  • Supporting versions

    Since v2.1.0.

Unit Safeness Checking (previously Bounds Checking)

Thanks to the Bounds tool by Emmanuel Paviot-Adet, this tool can first check that the P/T Net model in the PNML you want to translate into NUPN is 1-Safe. If that condition is not satisfied, the translation does not happen, unless you deactivate this option.

Unit safeness checking can be requested, by setting the unit.safeness.checking property set to true. If disabled (which is the default), NUPN generation will be faster since this step, which can take a long time, is skipped. To set this property, proceed like so:

java -Dunit.safeness.checking=true ...

The default value for this option is false.

Supporting versions

Since v1.4.0.

Note Using pnml2nupn does not require the Bounds tool. Just run it with the above property set to false.

Unit Safeness Checking Only

Unit safeness checking can be requested, and also have the tool stop just after that check, whatever the outcome (i.e. 1-safe net or not), by setting the unit.safeness.checking.only property set to true. This option overrides the force.nupn.generation option when both are set. When enabled, it is considered only if the unit.safeness.checking property is also enabled.

If unit.safeness.checking.only is enabled, no NUPN generation will happen, so that part of the process is skipped. To set this property, proceed like so:

java -Dunit.safeness.checking.only=true ...

The default value for this option is false.

Supporting versions

Since v1.4.0.

Force NUPN Generation

You can force the generation of the NuPN file, even if the net is not 1-safe (as checked by the Bounds tool). To trigger that behaviour, invoke the tool with the force.nupn.generation property set to true, like so:

java -Dforce.nupn.generation=true ...

The default value for this option is false. It works in pair with bounds checking (see next section).

Supporting versions

Since v1.1.9.

Up to v1.2.2, use the force.bpn.generation instead.

Disable Bounds Checking

It is also possible to disable bounds checking on the net. Bounds checking enables this tool to determine if the input net is 1-safe or not. If disabled, NUPN generation will be faster since this step, that can take a long time, is skipped. You may set this tool into that mode by invoking it with the bounds.checking property set to false, like so:

java -Dbounds.checking=false ...

The default value for this option is true. If not unset, it has precedence over all the other options.

Supporting versions

Since v1.1.10.

Check for the Presence of Unsafe Arcs in the Net

It is possible to check for the presence of unsafe arcs (i.e inscription > 1) of the input P/T net to this tool. This behaviour is triggered by the has.unsafe.arcs property, that is exclusive of all the others. Therefore, if you set this property to true, the tool will only check for the presence of unsafe arcs, reports them in a *.unsafe.arcs file, and ignore the other properties, whatever their values.

To activate this behaviour, set the has.unsafe.arcs property like so:

java -Dhas.unsafe.arcs=true ...

The default value for this option is false.

Supporting versions

Since v1.2.2.

Force Generation of Unsafe Nets

When it is known that the marking of some initial places or the inscription of some arcs have a valuation greater than 1, the translation is cancelled. If you want it to happen despite this fact, invoke PNML to NUPN Converter with the generate.unsafe property like so:

java -Dgenerate.unsafe=true ...

The default value for this option is false.

This option does not work in pair with the force.bpn.generation option above. Setting the latter does not have any effect on this one. If bounds checking is enabled, setting this one will remain ineffective.

Supporting versions

From v1.2.0 to v1.2.2.

Remove Transitions Connected to Unsafe Arcs

When the inscriptions of some arcs have a valuation greater than 1, you may want to remove the transitions that are connected to them, and those arcs by the same opportunity. In this case, use the remove.unsafe.trans property, like so:

java -Dremove.unsafe.trans=true ...

The default value for this option is false.

Note that if this operation eventually yields dead places, they are not removed. The implementation of removing dead places is not planned in the near future. If you are interested, you may want to create a fork of this project to implement that feature and then share it with all users.

Supporting versions

From v1.2.0 to v1.2.2.

Table of Contents