Usage¶

Command line¶

Usage:

polcolmc [action] [options]

Actions¶

run: (default) Run a simulation
rdf INPUT_FILE OUTPUT_FILE: Calculate a rdf on a ‘inst’ trajectory with an interval given by –dr option.
convert INPUT_FILES… OUTPUT_FILE: Convert a set of trajectories to a different format. One can use multiple files, this will be interpreted. as multiple simulation boxes. The option –of and –if control the output and input format respectively. The file extension of the first file will be used if these options are omitted. Available formats: xyz, gro, trr (output only), inst, inst-bin.
rescale INPUT_FILE OUTPUT_FILE FACTOR: Rescale a ‘inst’ configuration by FACTOR
extract INPUT_FILE OUTPUT_FILE: Extract the particles around the one of number PART
mktable BIN: Initialize and output potential tables of interval BIN (for Gromacs)
bondorder INPUT_FILE: Compute bond-order parameters and determine the composition of crystal phases. See Bond-order parameters for more details.

Options¶

`-h`	Print this message and quits
`--version`	Print version and quits
`-v`	Increase verbosity
`-l`	Only read parameters and print them
`-i FILE`	Get initial configuration from FILE (default: in.inst). Takes the last frame.
`-d FILE`	Get distribution from file FILE (default: distrib)
`-p FILE`	Get input parameters from file FILE (default: polcolmc.cfg)
`--dr DR`	(rdf) Interval length (default: 0.1)
`--if FORMAT`	(convert) Input format.
`--of FORMAT`	(convert) Output format.
`--box BOX`	(convert) Index of the simulation box to consider (default: 1).
`--particle PART`
	(extract) Index of the selected particle
`--radius FORMAT`
	(extract) Radius around the selected particle
`--bondorder-cfg BOND_ORDER_CONFIG`
	Configuration file for bond-order analysis (default: bondorder.cfg)

Input parameters¶

They are located in the parameter file (default: polcolmc.cfg). In this file, lines beginning by ‘#’ or ‘!’ are comments and thus are not processed. Other lines may be empty lines or have the form:

parameter_name = value

See Input Parameters for a detailed description of input parameters.

Distribution¶

Defined in the distribution file (default: distrib) which format is:

first line : number of families n
n lines of the form : subpopulation, radius, charge

Note

It is well advised, but not mandatory, to sort particles by increasing radius.

Output files¶

Other output file have a prefix prepended to their name, see output_prefix, default is pcmc.

If equilibration_steps is set, the output file for the equilibration run will have the prefix ${output_prefix}_eq_.

These files are listed below, they use the default prefix. $b means a box index, ie there are one file per simulation box.

pcmc_res.out

Moves statistics and several results (average energy, pressure…). Formatted in TOML. Units are kT for energies, Pa for pressures, nm for lengths.

pcmc_out.inst

Final state (positions) of the simulation. It can be copied to in.inst``(default, see option ``-i) so that the next run will use it as its first

Formatted like this:

step = ${step number}
#$config
translation_interval =   5.0105477
... maybe other key = val pairs
boxes = ${number_of_boxes}
#$endconfig
box 1
boxtensor =
   ${a_x}       ${b_x}       ${c_x}
   ${a_y}       ${b_y}       ${c_y}
   ${a_z}       ${b_z}       ${c_z}
number of particles =    ${number_of_particles}
${posX}  ${posY} ${posZ} ${family index} {radius}
...
box 2 # if any
...
endstep

Where a, b, c represents the box vectors.

pcmc_init.inst

Initial state (positions) of the simulation. As the initial positions can be generated by the program, this file is potentially useful.

pcmc_traj.inst

Trajectory. Concatenation of state formatted like above. You can convert to more common formats with polcolmc convert. Example:

polcolmc convert pcmc_traj.inst traj_b1.xyz --box 1 --of XYZ
polcolmc convert pcmc_traj.inst traj_b2.xyz --box 2 --of XYZ

pcmc_box$b_nrg.dat

Energy, pressure, number, volume for each step. Composed of lines of the form:

step

potential energy

virial pressure

hard-core pressure

number of particles

volume

pcmc_pop.dat

Average size distributions for each box. Composed of lines of the form:

radius

number(box #1)

number(box #2)

…

Example¶

Here we will see by an example how to do a simple simulation. The system is composed polydisperse particles interacting through a Yukawa potential, at a volume fraction of 10%. The MC moves are translations in and swaps.

The input files of this example can be retrieved in the examples/simple1 folder.

First, let us set the input parameters in a file named polcolmc.cfg.

We would like to make a simulation of 1000 MC cycle in the NVT ensemble, (1 cycle = N attenpted MC moves). At first an equilibration run is done, because we start from a random configuration, so we set production to no.

# simulation
simulation_type = NVT
number_of_steps = 1000
production = no

The temperature is set to 300 K. We set the volume by specifying the volume fraction (say, 10%) and that we want a cubic box.

temperature = 300.
volume_fraction = 0.1
box_type = cubic

We use a yukawa potential, that requires to set values for the Bjerrum length the Debye length, and the cutoff radius. The charges of the particles will be set later. See cutoff_estimation_tolerance for another way to set a cutoff.

# potential
potential_type = yukawa
Bjerrum_length = 0.7105
Debye_length = 4.06
cutoff_radius = 45.

We need to define a seed to generate (pseudo-)random numbers.

random_seed = 786519

We also need to define the maximum amplitude of translation (in nm), the translation acceptance we want to reach and the period (in MC cycles) at which the translation amplitude is adjusted. This period can be set to -1 if one does not want to adjust the amplitude. Note that this is also the case for production runs.

# translation
translation_interval = 5.
translation_acceptance = 0.35
translation_update_period = 100

To be able to run the program, we need to define a distribution. We will use a distribution with 5 types. The actual radii and charges does not matter for such an example, but for the record they are a simplified model of an HS40 silica dispersion at pH 9. Copy and paste the following block to a file name “distrib”.

5
6. 83.
7. 107.
8. 133.
8. 156.
9. 189.

We now can run polcolmc in the command line, but this take about 23 s on my computer. We can be down to less than 6s on my computer by using a cell decomposition. It is activated by adding the following line to polcolmc.cfg.

energy_algorithm = celldec

We can look at the results in at the end of main output or in pcmc_res.out.

Let us now introduce swaps between particles. For polydisperse systems, these can speed up equilibration and improve configurational sampling.

We have to add the following line to polcolmc.cfg.

swap_probability = 0.3

This means that, at each MC trial, the program will attempt a swap with a probability of 0.3, otherwise a translation is made.

We can now re-run polcolmc.

One of the produced files, pcmc_out.inst is the last configuration. By copying this file to in.inst, we are now able to make a new run with this configuration as the starting point. Note that, in absence of in.inst, the program will generate the initial positions at random. In polcolmc.cfg we can put production to yes to signify we want to make a production run now (in fact this system requires more time to equilibrate, but for the sake of an example we can overlook that).

Then, after re-running polcolmc, we obtain (hopefully) the following results

Box 1
      Mean Number of particles =    1300.0000
                   Mean Volume =    294.05315    ^3
            Volume fraction ϕ =   0.99999949E-01
           Ideal Pressure (Pa) =    211.77282
     Hard Sphere Pressure (Pa) =    77.650032     σ =   0.0000000
          Virial Pressure (Pa) =    17263.860     σ =   0.0000000
                 Pressure (Pa) =    17553.282
Potential Energy p. part. (k_B =    10.330850     σ =  0.63083952E-01
       Energy p. part. (k_B T) =    11.830850

Some analysis can be done during the simulation (more in Analysis). The computation of the radial distribution function can be activated by the adding the following line to polcolmc.cfg:

calculation_period = 5

After re-running the program, more file are generated. Notably, pcmc_box1_rdf.dat contains the RDF. The effective structure factor is also computed and printed in pcmc_box1_seff.dat. See Radial distribution function and Effective structure factor for more details.