Home

1. Introduction

Eris is an on-lattice Monte Carlo code used to simulate thermodynamic substitutional disorder between Cu and Zn in Cu₂ZnSnS₄ (CZTS). This page provides a guide for setting up the simulations (mainly through editing flags in the file 'eris.cfg').

We currently freeze in Sn ions in our simulations so that we can study Cu-Zn disorder alone (although this feature can be changed using the freezeSn flag in eris.cfg). There is also the option to study disorder in the Cu-Zn plane only (i.e. 2D disorder) as well as 3D Cu-Zn disorder where Zn is able to substitute into Cu-Sn planes feature currently under construction. The animation below highlights the Cu-Zn and Cu-Sn planes in the CZTS conventional unit cell, where the code with the current default settings simulates disorder in these 2D Cu-Zn planes.

It is worth pointing out at this point that we neglect S anions in our Monte Carlo simulations. This is because S anions can be considered to be stationary during the simulations as any swap between a S anion and metal cation would be energetically infeasible and any substitutions amongst the S anions would result in an energetically equivalent structure - this would of course not be the case if we were simulating the alloy CZTSSe instead! S anions are accounted for in the interaction matrix used to calculate the change in lattice energy when a Monte Carlo move (or rather Cu/ Zn swap) is performed. For the curious, this matrix is called 'E_int' in eris.cfg. The species are also fixed into on-lattice positions and so our model does not allow for strain in the lattice when species with a large difference in ionic radii are substituted. (Conveniently, Cu and Zn have very similar ionic radii, which partly explains why they swap around so much!)

Overview of Eris sub-programs

For most purposes only the file 'eris.cfg', but a brief description of all sub-programs is included for any user who is interested in further developing Eris.

• eris.cfg: This is the file a user will interact with most, it contains the majority of input parameters for the simulations such as initial and final temperatures, whether to start from an ordered or fully disordered (randomized) initial lattice and the number of Monte Carlo steps to be performed in the simulation. Note that the program does not need to be recompiled when changes are made to this file only.
• eris-config.c: Stores simulation parameters, but these are overwritten if they are defined in eris.cfg instead. This subprogram is also where global variables for the whole program are declared.
• eris-main.c: This file contains all of the instructions for what you see on the screen as the simulations run (such as the visuals in the terminal for the lattice configuration and on-site electrostatic potential) and reads in input parameters from 'eris.cfg' and 'eris-config.c'. The program loops over a temperature range and over a number of Monte Carlo steps as defined in 'eris.cfg'. It also calls functions from other sub-programs to perform Monte Carlo moves and to perform analysis of the system and to generate outputs.
• eris-analysis.c: Contains all of the main functions for producing outputs for the user and for analysing data such as: outputting .xyz files for each configuration, calculating the on-site electrostatic potentials of the system and variance in the distribution of the electrostatic potentials and for calculating the radial distribution function for all pairs of species in the system for each configuration.
• eris-kernal.c: Contains the core functions for the Monte Carlo simulations such as functions MC_move() to perform Cu-Zn swaps and site_energy() (and the modified site_energy_stencil) to calculate the change in energy from performing a move.
• eris-lattice.c: Contains functions used to generate various initial lattice configurations for the simulations, such as ordered CZTS or a fully randomized system. Either of these options can be selected in 'eris.cfg'.
• Makefile: Contains instructions for compiling eris.
• mt19937ar-cok.c: External C libraries used in Eris.

2. Running simulations

Basic setup: The 'Makefile' contains all instructions to compile eris, so provided all of the above files are present simply enter make into the terminal and an executable called 'eris' will be created. Then to run a simulation simply enter './eris' into the terminal. Below shows a typical terminal display once the simulation has begun when the flag DisplayDumbTerminal is set to true, just to give an idea of what you should expect to see (note: this is the visual produced from the code version on 14.06.16, current version may differ slightly).

make cleanupdatais a useful way to delete output files from a previous run if you want to start a fresh run in the same directory.

Running simulations in parallel: It is also possible to run the code in parallel if you are performing simulations over a temperature range...and want the set of simulations to finish sooner! In this case you instead enter make parallel into the terminal. The simulation will run automatically after this, but be aware that a notice will be displayed first for some time but the simulation will begin to run after. Note: When running in parallel the simulation temperature range is no longer set in eris.cfg, it is instead set in the Makefile by: seq 0 100 2500 | parallel ./eris {}

In this example, the user has requested a temperature range of 0 to 2500K in steps of 100K.

3. Editing input parameters

Relevant flags in 'eris.cfg'

Here is an explanation of all flags in the eris.cfg file in order of appearance (as of the version of the code on 14.06.16, some small changes may have occurred since), where 'true' turns the flag on and 'false' turns the flag off. Note that it is not necessary to recompile eris after turning a flag on or off.

• X, Y, Z: Define lattice dimensions for system
• freezeSn: immobilize tin ions in the simulation in order to simulate Cu-Zn disorder only
• TMAX, TMIN, TSTEP: Defines the temperature loop for the simulations, if you want to run at one temperature only simply set TMAX and TMIN to the same value
• EquilibrationChecks: Set this flag to true if you want to perform a run to check for equilibration of the system and to determine an appropriate number of Monte Carlo steps to set for MCEqmSteps. See the later section on 'Checking for Equilibration' for more information.
• DisplayDumbTerminal: shows the 2D slice on the configuration as shown in the above example, this can be turned off to speed up the simulation, especially for larger systems.
• CalculatePotential, CalculateRadialOrderParameter, SaveXYZ, SaveGULP: when set to true on-site electrostatic potentials, radial distribution functions, .xyz files and GULP input files of the system configuration are outputted.
• OrderedInitialLattice: when set to true a perfectly ordered initial lattice is used for the simulation (this can be used to relate to melting), when set to false a randomized, disordered initial lattice is used (this can be used to related to cooling after annealing, such as during the synthesis of CZTS crystals)
• ReinitializeLattice: when set to true the lattice is reinitialized (either to fully ordered or fully randomized) for each temperature
• MCMegaSteps: Corresponds to the number of Monte Carlo steps in the outer loop in eris-main.c. This defines the number of times the electrostatic potentials, radial distribution functions and .xyz configuration files will be outputted.
• MCEqmSteps: This defines the number of MC moves performed before data is outputted to allow for equilibriation.
• MCMoves: Used to determine the number of MC moves performed in the inner loop in eris-main.c. The value is scaled by the lattice dimension. This value is then used as 'MCMinorSteps' in eris-main.c

4. Other options from the makefile & general tips

• make cleanupdata: removes output files from previous runs (especially important for files like potential.dat and variance.dat where the data appends if you don't want a previous run to be included in your statistics)
• make clean: removes old eris executable
• make parallel: see end of section two for information on compiling eris to run in parallel

Preventing a Terminal Session Timing Out

If you're running a simulation for a long time, your work station may go into sleep mode which will kill the simulation. There are two options for preventing this. One really simple option (which I believe only works for a Mac) is to open another terminal window and use the command caffeinate. Alternatively, you can start a tmux session. To do this you only really need to know three commands:

• tmux - initiate session
• (then start your eris runs)
• ctrl b + d - leave your session
• tmux a - reenter your session

Make sure to leave your session before you leave your simulation running. If you want to have separate tmux sessions you can name each of them differently Google using tmux for information on more sophisticated uses than I've outlined here.

5. Output Files

Lattice configurations

As the simulation progresses 2D slices of the first 3 layers (in the z-direction) are shown in the terminal where 'C' is a copper species, 'Z' is zinc, 'T' is tin and '.' is an empty site on the lattice, used just for mapping an FCC lattice onto a simple cubic lattice. Note that empty sites and Sn are fixed during the simulation (if the flag to freeze in Sn was selected in eris.cfg). This output is controlled by the 'DisplayDumbTerminal' flag in eris.cfg. Eris can also output the lattice configurations in .xyz format or GULP input format if the 'SaveXYZ' and 'SaveGulp' flags in eris.cfg are set to true. The initial configuration is outputted to 'czts_initial_lattice.xyz' and then the most recent configuration for each temperature is outputted to 'cztz_lattice_T_TEMPERATURE.xyz'.

Note that S anions are not shown in the terminal visual or outputted xyz files. S anions are reintroduced into the system using the lattice symmetry when writing input files for calculating the full lattice energy with the GULP code. GULP input files are stored in a separate directory (GULP_inputs) when the SaveGULP flag has been set to true in eris.cfg.

Radial distribution functions

Eris calculates on-lattice radial distribution functions (RDFs), which are more commonly referred to as pair correlation functions (PCFs) for solids, for each pair of species in the system for each temperature. For example, 'RDF_C_C_T=0100.dat' corresponds to a Cu-Cu PCF for a configuration with simulation temperature T=100k. Eris will only write a file for the initial configuration (e.g. RDF_C_C_initial.dat) and also for the final simulation configuration at each temperature (RDF_Z_T_T=TEMPERATURE.dat), unless the 'EquilibrationChecks' flag has been set to true in eris.cfg, in which case an PCF will be outputted intermittently after a specified number of MC steps, but will over write the previous output each time (apart from that corresponding to the initial lattice).