Getting Started

This guide walks you through downloading, running, and inspecting the results of your first MKMCXX simulation.

1. Obtaining the Software

To begin using MKMCXX, download the software package and unpack it on your machine. The package contains a single executable file in its bin folder:

Windows: mkmcxx.exe
Unix/Linux/macOS: mkmcxx

Note

No installation is required; you can run the executable directly. The binaries are designed to be portable and self-contained, allowing you to execute them immediately after download, without the need for additional setup, configuration, or dependencies.

In addition to the software, you will need a flat text editor to create and edit MKMCXX input files:

Unix/Linux: vim or nano are usually preinstalled.
Windows: We recommend using Notepad++ or Visual Studio Code.

2. Running the Program

Performing a simulation works somewhat different on Windows as compared to Unix. Please read the respective instructions below.

Windows

To run a built-in example simulation using MKMCXX, follow these steps:

Navigate to the Installation Directory
Go to the folder where you unpacked the MKMCXX software package.
Open the Examples Folder
Inside the main directory, open the examples folder.
This folder contains several subfolders, each with a different simulation example.
Choose an Example
Open one of the subfolders. You should see a file named input.mkx inside.
Open a Terminal in That Folder
Right-click in the folder (not on a file).
Select "Open in Terminal" (or similar option, depending on your system).
Run the Simulation
In the terminal window, enter the following command to start MKMCXX with the provided input file:
```
..\..\bin\mkmcxx.exe -i input.mkx
```
Tip
- Make sure the path to mkmcxx.exe is correct relative to the example folder you are in.
- In contrast to MKMCXX v2, MKMCXX v3 scripts have the .mkx extension.

Once executed, MKMCXX will begin processing the simulation defined in input.mkx. You can explore and modify the input file to experiment with different simulation setups.

Unix/Linux/macOS

To run a built-in example simulation using MKMCXX on Linux, follow these steps:

Open a Terminal
Navigate to the Installation Directory
Change to the directory where you unpacked the MKMCXX software package. For example:
```
cd ~/Downloads/mkmcxx
```
Go to the Examples Folder Navigate into the examples directory:
```
cd examples
```
Choose an Example Each subfolder contains a different simulation. For example:
```
cd basic-reaction
```
Inside, you should see a file named input.mkx.
Run the Simulation From within the example folder, execute MKMCXX using the relative path to the binary:
```
../../bin/mkmcxx -i input.mkx
```
Tip

Ensure that the binary has execute permissions. If needed, run:
```
chmod +x ../../bin/mkmcxx
```

After running the command, MKMCXX will process the simulation defined in input.mkx. You can modify this file to explore different simulation setups.

Tip

By default, all warnings and errors will be printed to the console. If you want to collect these in files, you can run using the following

SUNLOGGER_ERROR_FILENAME=error.log SUNLOGGER_WARNING_FILENAME=warnings.log ../../bin/mkmcxx -i input.mkx

3. Viewing the Results

The results of the simulation are collected in a results folder in the working directory from which you have called the MKMCXX executable. Depending on your settings, output is written to a number of .tsv, .h5 and/or .xlsx files corresponding to tab-delimited flat-text files, the HDF5 file format or Excel files.

The .h5 file will always be located at results/results.h5 and contains all output of the simulation in a single file. You can explore the data items in the .h5 file using HDFView or e.g. a HDF5 library such as HDF5 for Python. The Python post-processing utility shipped with MKMCXX v3 uses the latter.

Alternatively, you can use a flat-text editor or an Excel-file compatible spreadsheet viewer to open the .tsv or .xlsx files.