The mcPolymer command-line interface

The mcPolymer program is used in a terminal environment. In the Windows operating system this is the Command Prompt (cmd.exe or cmd) and at Linux any command shell (e.g. tcsh, bash). The following examples assume that the mcPolymer program (Windows: mcPolymer.exe, Linux: mcPolymer) and the model file "Styrene.mcPolymer" are in the current directory.

Calling the program with the --help option you can see all the features of the command line interface and a basic example of their application.

c:\tmp\mcPolymer\mcPolymer --help
  mcPolymer -m Styrene.mcPolymer --time=3600 --dt=60 --temperature=70.0 --molecules=10000000000
  mcPolymer -m modelFile [OPTION...]

  -m, --model modelFILE         Model
        --help                           Print help
        --license                        Print license
        --time double                 reaction time / s
        --dt double                    time interval for output concentrations / s
        --dtCLD double              time interval for output cld | mmd / s
        --temperature double      temperature / centigrade
        --pressure double           pressure / bar
        --molecules unsigned int  num molecules

The option --license provides mcPolymer license status information. The mcPolymer simulator is published as open source software under the GNU general public license. On the web page the source code of the program is available for download. The following external software components are integrated in mcPolymer and are part of the distribution:

  • File cxxopts.hpp contains one C++ option parser library, supporting the standard GNU style syntax for options. This is a header only library and was developed by Jarryd Beck. Source: GitHub.
  • File MersenneTwister.h implements the Mersenne Twister random number generator, developed by Makoto Matsumoto, Takuji Nishimura, Shawn Cokus and Richard J. Wagner. Source: GitHub.

Running a simulation requires a kinetic model. This is provided in a file which name is entered in the command line with the option -m filename or --model filename. In the example shown with the --help option, the model file Styrene.mcPolymer is used for the simulation (-m Styrene.mcPolymer).

The --time option determines the reaction time in seconds running the kinetic model. This time can optionally also be specified in the model file (e.g. time=3600). The entry on the command line overrules the value in the model file. The reaction time is required for the simulation has to be specified on at least one of those two places (command line: --time=value; model file: time=value). Otherwise mcPolymer terminates with an error message: "reaction time undefined". Generally for the pattern --option=value no spaces are allowed in front of or behind the "=", otherwise the interpretation on the command line will fail.

Equally essential is the input of the reaction temperature in degrees Celsius, which can also be done in the model file (temperature=value) or on the command line (--temperature=value). The same rules as for the reaction time will also be applied here. The entry of --pressure=value is optional; 1 bar is the default pressure.

For the kinetic Monte Carlo (kMC) simulation, the definition of the sample size is required. This is done by entering the statement --molecules=value on the command line. In our example --molecules=10000000000, the 1e10 molecules are distributed to the educts according to the concentrations specified in the model file ([styrene]0 = 8.725 mol·L-1 ⇒ 9977129788 molecules, [AIBN]0 = 0.02 mol·L-1 ⇒ 22870212molecules).  This corresponds to a control volume of 1.9e-15 L. It is clear that the sample size in the kMC has a significant impact on the precision of the simulation but also on computation time and memory requirements. In this example (-m Styrene.mcPolymer --time=3600 --temperature=70.0 --molecules=10000000000 ) the simulation takes about 3 minutes on an Intel Core i7-6700, 3.4 GHz CPU and requires a maximum of 530 MB of RAM.

The command line options --dt=value and --dtCLD =value control the logging of results. Both parameters have default values (dt=1/60·reaction time; dtCLD=reaction time), which are used if these options are not set. After starting the program with the options mentioned in the example, the current parameters are displayed. In addition, an interval of dt (--dt=60) seconds is used to output the current reaction time in the running kMC simulation:

c:\tmp\mcPolymer -m Styrene.mcPolymer --dt=60 --temperature=70 --molecules=10000000000
model file: Styrene.mcPolymer
model dimension: 10000000000 ( 1.000000e+10 ) molecules
reaction time 3600, defined in model file
concentration output dt 60 s
cld | mmd output dtCLD 3600 s, set to reaction time by default
reaction temperature 70 degree Celsius
pressure 1 bar, set by default
time: 60
time: 120
time: 180

The concentration time and molecule number-time profiles are written in two files, which are updated at intervals of dt. The file names are derived from the name of the model file:

  • modelfilename.Concentrations.dat (e.g. Styrene.mcPolymer.Concentrations.dat)
  • modelfilename.numMolecules.dat (e.g. Styrene.mcPolymer.numMolecules.dat).

Both files are ASCII files in which the columns are separated by a tab character. This makes a data analysis or visualization in other programs easily possible. For each reaction time, the concentration (mol·L-1) or the number of molecules of each reactant contained in the kinetic model is available:


Additionally, chain length distributions and molar mass distributions of all macromolecular species defined in the kinetic model are available as output files written at intervals specified by --dtCLD. The file name contains the name of the species and the reaction time. At the end of the simulation, two ASCII files are written e.g. for the dead polymer D defined in the model Styrene.mcPolymer: chain length distribution ⇒ D.3600.000000.CLD.dat and molar mass distribution ⇒ D.3600.000000.CLD.dat.WlogM.dat. The molar mass distribution is stored in equidistant X-axis steps (log (M)) and normalized to area 1. The file with the chain length distribution has the following structure:


In the file header, the mean values and the number of polymer molecules are summarized. The chain length distribution begins in this example at line 6 and is located in columns A (chain length) and B (number of chains). In addition, each chain length is assigned the number of short chain branches (column C, numSCB) and long chain branches (column D, numLCB). In this simple example Styrol.mcPolymer, no branching reactions occur. In column E, the number of monomer units in the chains of the corresponding chain length is given. In the styrene homopolymerization, only column E is occupied. In a copolymerization, the number of these monomers is located in additional columns, starting with F.

Tutorial: model file Styrene.mcPolymer

Model file Styrene.mcPolymer, displayed with line numbers.

The molecular weight 104.15 g·mol-1 is assigned to the monomer styrene. This statement implicitly defines the species styrene as a monomer.

This line is a comment. Comments are initiated with the string "//".

The styrene concentration is set to 8.725 mol·L-1.

Blank lines in the command file improve readability and are not interpreted.

It implicitly defines a species called "AIBN". The concentration is set to 0.02 mol·L-1 for the beginning of the reaction.

This statement implicitly defines the low molecular weight species AIBN as initiator.  The initiator efficiency is 0.64 and can be chosen in the range of 0 to 1.

It defines a reaction rate coefficient with the pre-exponential factor 4.31e15 s-1 and the activation energy 131.7 kJ·mol-1.

It defines a reaction rate coefficient with the pre-exponential factor 1.341e10 L·mol-1·s-1 and the activation energy 14.34 kJ·mol-1. The spaces (e.g., before and after "*") generally do not affect the interpretation of the instruction.

The temperature is set to 70 °C. If such an instruction is included in the model file, the temperature at the start of the program need not be entered on the command line. With an optional input on the command line (e.g., --Temperature = 60.0), this value is overruled and the simulation runs at 60 °C.

The initiator decomposition of AIBN becomes part of the kinetic model. The reaction is derived from the reaction template "initiator --k --> I + I" (see Table Reaction Templates). AIBN stands for the initiator, I for the primary radicals and kiAIBN for the reaction rate coefficient. The reaction template "initiator --k --> I + I" is only recognized correctly if the initiator has been assigned an initiator efficiency (see line 6). The primary radicals I are implicitly defined as low molecular weight species when used in a reaction. A separate definition (e.g., [I] = 0.0) is not necessary.

This reaction describes the initiation of a macro radical from the primary radical I with the monomer styrene. The concrete reaction was derived from Template "I + M --k--> P(1)" (see Table Reaction Templates). This template expects a monomer at position "M". Therefore, it is essential that the species styrene is assigned a molecular weight (see line 1). Only with this assignment the species styrene does get the property "monomer" and can be used in this reaction. The result is a macro radical P(n) with the current chain length n = 1. In formulating the reaction, the macroradical must be labeled as a macromolecule. In this initiation reaction, this is done by the name suffix (1).

The propagation reaction formulated on this line is derived from Template P(n) + M --k--> P(n+1). Again, a monomer is expected at position "M". While the name of the macroradical is selectable by the user (e.g., P or MR), the extensions (n) in the educt and (n + 1) in the product should be used exactly as shown.

In this transfer reaction with the monomer styrene, a dead polymer D(n) and a new macroradical P with chain length 1 are formed. The associated reaction template is: P(n) + M --k--> D(n) + Q(1). It must be ensured that at the position "M" is a monomer and the macromolecular species with (n), (n) and (1) are marked exactly at the position shown.

In this termination by combination, a dead polymer D with the chain length n + m is formed. The rate coefficient kt is applied according to the IUPAC conventions. The label of the macromolecular species must be used as given in the reaction template "P(n) + P(m) --k--> D(n+m)".

The simulation ends with a reaction time of 3600 seconds. This default can be changed by an input on the command line at the start of the program, e.g. --time=7200. 

Reaction templates in mcPolymer

Table reaction templates: M, M1, M2 – monomer, P(n), Q(m) – macromolecular species, X , A, B – low molecular species, st – monomer styrene, SCB – short chain branch, TDB – terminal double bond, k – reaction rate coefficient

1initiator --k--> I + Iinitiator decomposition
2I + M --k--> P(1)initiation
3st + st + st --k--> P(1) + P(1) thermal initiation (styrene)

P(n) + M --k--> P(n+1)

P(n) + M --k--> Q(n+1)

propagation (homo- or copolymerization)
5P(n) + M --k--> Q(n+1,SCBpropagation + SCB

P(n) + P(m) --k--> D(n+m)

P(n) + Q(m) --k--> D(n+m)

termination by combination

P(n) + P(m) --k--> D(n) + D(m,TDB)

P(n) + Q(m) --k--> D(n) + D(m,TDB)

termination by disproportionation

P(n) --k--> Q(n)

P(n) + X --k--> Q(n)

P(n) --k--> Q(n) + X

9P(n) + M --k--> D(n) + Q(1)transfer to monomer
10P(n) + D(m, M1) --k--> D(n) + MCRL(m, M2)transfer to polymer
11P(n) --k--> Q(n-s) + D(s)fragmentation
12A --k--> B + Celementary reaction
13A + B --k--> Celementary reaction

Application examples for the reaction templates:

Examplemodel file
1AIBN --kiAIBN--> I + IStyrene.mcPolymer
2I + styrene --kp--> P(n)Styrene.mcPolymer
3styrene + styrene + styrene --kth--> P(1) + P(1)ATRP.mcPolymer

P(n) + styrene --kp--> P(n+1)

P(n) + M --k--> Q(n+1)



5MCR(n) + BA --kpt--> SPR(n,SCB)BA.mcPolymer

P(n) + P(m) --kt--> D(n+m)

SPR(n) + MCR(m) --ktsm--> D(n+m)




PM1M1(n) + PM1M1(m) --ktd11--> D(n) + D(m,TDB)

PM1M1(n) + PM2M2(m) --ktd12--> D(n) + D(m,TDB)


SPR(n) --kbb--> MCR(n)

P(n) + N --kc--> PN(n)

N(n) --kd--> P(n) + N




9P(n) + styrene --km--> D(n) + P(1)Styrene.mcPolymer
10SPR(n) + D(m,BA) --kmp--> D(n) + MCRL(m,BAX)BA.mcPolymer
11PSCSP(n) --kfrac--> P(n-m) + PSCS(m)RAFT.mcPolymer
12RN --kd--> R + NNMP.mcPolymer
13R + N --kc--> RNNMP.mcPolymer

Kontakt  Suche  Sitemap  Datenschutz  Impressum  Verantwortlich: Marco Drache
© TU Clausthal 2020