You need to have a JRE 7+ installed on your machine. To launch the .sh files, you have to run them on a Unix-based system with a BASH shell. No installation procedure is required. This version has been tested on both a Ubuntu Linux (16.04) and a Mac OS X (Snow Leopard) machine.

The easiest way to launch MINERful is to make use of the .sh files.

• To launch the miner: run-MINERful.sh
• To create synthetic logs: run-MINERfulTracesMaker.sh
• To run tests (as we did for the evaluation sections of our papers): test-launchers/*.sh

Each of those launchers can be invoked with the -h parameter. An explanation of all possible parameters that can be passed is written there (beware, they are quite an amount so take your time). Depending on the case, some parameters are specified in the .sh files, whereas others are left free. In case, feel free to modify the constants declared at the beginning of the script, so as to customise them.

The scripts that end with the -unstable.sh suffix do not launch MINERful via its JAR, but with bytecode files. In this way, we can immediately try the modified source code without overwriting the JAR version.

Some usage examples follow.

• Mine an XES log file located in /home/user/file.xes:

  run-MINERful.sh -iLF '/home/user/file.xes' 
  

• Display the help screen:

  run-MINERful.sh -h
  

Mine an XES log file located in /home/user/file.xes and export the discovered model in an XML file located in /home/user/model-condec.xml, formatted as Declare/ConDec. Set a support threshold of 0.95, a confidence level threshold of 0.25, and an interest factor threshold of 0.125 (if you have no idea what these parameters are about, check this paper paper out):

  run-MINERful.sh -iLF '/home/user/file.xes' -condec '/home/user/model-condec.xml' 
-s 0.95 -c 0.25 -i 0.125

• Mine an XES log file located in /home/user/file.xes, with comprehensive debug lines

  run-MINERful.sh -d all -iLF '/home/user/file.xes' 
  

• Mine an XES log file located in /home/user/file.xes, with comprehensive debug lines. Let results be exported in a CSV file located in /home/user/output.csv:

  run-MINERful.sh -d all -iLF '/home/user/file.xes' -CSV '/home/user/output.csv'
  

• Mine an XES log file located in /home/user/file.xes, with comprehensive debug lines. Set a support threshold of 0.95, a confidence level threshold of 0.25, and an interest factor threshold of 0.125 (if you have no idea what these parameters are about, check this paper out). Let results be exported in a CSV file located in /home/user/output.csv:

  run-MINERful.sh -d all -iLF '/home/user/file.xes' -CSV '/home/user/output.csv' 

  -s 0.95 -c 0.25 -i 0.125
  

This is a little bit trickier, but necessary, in case you have a Microsoft Windows system. From your prompt, type:

  java -jar MINERful.jar minerful.<LAUNCHER_CLASS> -h

where the LAUNCHER_CLASS can be either MinerFulMinerStarter to launch the miner, or MinerFulTracesMakerStarter to launch the builder of synthetic logs.

The -h parameter appended at the end of the prompt shows and explains the parameters you can pass. They are exactly the same as the Linux/MacOS version.

For advanced users: You can use MINERful as a Java package and integrate it with your software! Check out the minerful.examples.api source code to see some examples. In particular:

• discovery.MinerFulObserverInvokerOnXesFile demonstrates how to invoke the MINERful miner as an API, and subsequently observe the changes that are applied to the process model in a publish/subscribe fashion. Lastly, the model is saved as a Declare Map file.
• discovery.MinerFulCallerOnStringFile demonstrates how to call MINERful to discover a process model out of strings saved on a file.
• logmaking.FromCharactersProcessModelToLog demonstrates how to generate XES logs starting from the definitions of new constraints. It can be interesting also because it shows how to create a process model on the fly.
• logmaking.FromStringsProcessModelToLog demonstrates how to generate XES logs starting from the definitions of constraints exerted on activities identified by single characters (more or less the same as above).
• logmaking.FromDeclareMapToLog demonstrates how to generate XES logs from an existing Declare map XML file. It is worth to see how to convert process models from the Declare Maps Miner format, for those who used that tool in ProM.
• logmaking.FromJsonProcessModelToLog demonstrates how to generate XES logs starting with the definitions of constraints specified with JSON objects.
• simplification.MinerFulSimplificationInvokerOnDeclareMapFile demonstrates how to load a Declare Map file as a process model, then run the simplification engine of MINERful to remove the redundant constraints.

A ProM package of MINERful exists, although it is in beta version and with limited functionalities: It is available in the ProM Nightly Build SVN repository. More information is available in this paper:

• Claudio Di Ciccio, Mitchel H. M. Schouten, Massimiliano de Leoni, Jan Mendling: Declarative Process Discovery with MINERful in ProM. BPM (Demos) 2015: 60-64. URL: http://ceur-ws.org/Vol-1418/paper13.pdf

A GUI-equipped log generator is also in its beta version, based on the Declare Designer tool: It is available for download on the Synthetic log generator GitHub page. More information is available in this paper:

• Claudio Di Ciccio, Mario Luca Bernardi, Marta Cimitile, Fabrizio Maria Maggi: Generating Event Logs Through the Simulation of Declare Models. EOMAS@CAiSE 2015: 20-36. DOI: 10.1007/978-3-319-24626-0_2

Please read the LICENSE file.