Skip to content

Getting Started

This page helps you get to a first successful MKMCXX 3 run quickly, even if you are new to microkinetic modeling.

You do not need to understand the whole software before you begin. The goal is simply to get one example running in a calm, reliable way and then point you to the best next step.

Prerequisites

  • a downloaded MKMCXX 3 package
  • a terminal
  • a plain text editor such as VS Code, Notepad++, nano, or vim

Learning Outcomes

  • run one bundled example successfully
  • find the output written by MKMCXX
  • know what “success” looks like after a first run
  • know where to go next in the manual

Tip

If you are completely new to this area, that is perfectly fine. Start by running one bundled example first. You can learn the input structure and the scientific details step by step afterwards.

Step 1: Unpack MKMCXX

Download the latest package from the downloads page, then unpack it somewhere convenient.

Inside the extracted folder, you should see:

  • a bin folder containing the executable
  • an examples folder containing ready-to-run simulations

The executable is called:

  • mkmcxx.exe on Windows
  • mkmcxx on Unix, Linux, and macOS

Note

MKMCXX 3 does not need a separate installation step. In most cases, you can unpack the download and run it directly.

Step 2: Run One Example

The easiest and safest way to begin is to run one of the bundled examples before editing your own files.

Pick any example directory you like. At this stage, the goal is not to choose the “best” model, but simply to complete one successful run.

On Windows

  1. Open the folder where you unpacked MKMCXX 3.
  2. Open the examples folder.
  3. Open one of the example directories.
  4. Right-click in that folder and choose Open in Terminal.
  5. Run:
..\..\bin\mkmcxx.exe -i input.mkx

On Unix, Linux, or macOS

  1. Open a terminal.
  2. Move to the unpacked MKMCXX 3 folder.
  3. Enter the examples folder.
  4. Enter one of the example directories.
  5. Run:
../../bin/mkmcxx -i input.mkx

If the executable is not yet marked as runnable, use:

chmod +x ../../bin/mkmcxx

Note

MKMCXX 3 input files use the .mkx extension. This is one of the clearest differences from older MKMCXX 2 workflows.

Step 3: Check That It Worked

After you run the command, MKMCXX reads input.mkx, performs the simulation, and creates a results folder in your current working directory.

In a typical example folder, you will end up with something like:

example-folder/
├── input.mkx
└── results/

If you see a results folder, you have already completed the main goal of this page. Your first MKMCXX 3 run has worked, and the output has been written to disk.

Step 4: Open the Results

MKMCXX 3 always writes its main consolidated output to:

results/results.h5

Depending on your output settings, you may also see .tsv and .xlsx files.

You can inspect the results in several ways:

  • open .tsv files in a text editor or spreadsheet tool
  • open .xlsx files in Excel or another spreadsheet application
  • open results.h5 in HDFView
  • read results.h5 from Python using h5py

Tip

Do not worry if HDF5 is unfamiliar at first. You can start with the text or spreadsheet outputs and move to HDF5 later when you want more structured analysis.

Optional: Save Log Files

By default, warnings and errors are shown in the terminal. If you would like them written to files instead, run:

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

On Windows, use the corresponding environment-variable syntax in the terminal you work in.

What To Do Next

Once you have completed one successful run, these are the most useful next steps:

Common Questions

Do I need to install anything first?

Usually no. In normal use, you only need to unpack the download and run the executable.

Where should I make my first edits?

Start from one of the bundled examples, make a copy, and edit its input.mkx file. That is usually much easier than starting from a blank file.

I am still learning the science behind the model. Is that a problem?

Not at all. Many users first learn the software workflow and the scientific background in parallel. Running small examples is a very good way to build confidence.

I already know MKMCXX 2. What feels different in MKMCXX 3?

The most visible changes are the .mkx input format, the revised syntax, and the newer output workflow centered around HDF5 and spreadsheet export.