CASM
AClustersApproachtoStatisticalMechanics
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules
format.cc
Go to the documentation of this file.
1 #include <cstring>
2 
3 #include "casm/CASM_global_definitions.hh"
4 #include "casm/app/casm_functions.hh"
5 #include "casm/completer/Handlers.hh"
6 
7 namespace CASM {
8 
9 
10  namespace Completer {
11  FormatOption::FormatOption(): OptionHandlerBase("format") {}
12 
13  void FormatOption::initialize() {
14  add_help_suboption();
15 
16  m_desc.add_options()
17  ("dir,d", "CASM project directory structure summary")
18  ("project_settings", "Description and location of 'project_settings' file")
19  ("prim", "Description and location of 'prim.json' and 'PRIM' files")
20  ("config_list", "Description and location of 'config_list.json' file")
21  ("sym", "Description and location of 'lattice_point_group.json', 'factor_group.json' and 'crystal_point_group.json' files")
22  ("vasp", "Description and location of VASP settings files")
23  ("properties", "Description and location of properties.calc.json files")
24  ("qe", "Description and location of Quantum Espresso settings files")
25  ("comp", "Description and location of 'composition_axes.json' file")
26  ("bspecs", "Description and location of 'bspecs.json' file")
27  ("clust", "Description and location of 'clust.json' file")
28  ("basis", "Description and location of 'basis.json' file")
29  ("clex", "Description and location of '$TITLE_Clexulator.*' files")
30  ("ref", "Description and location of 'chemical_reference.json' files")
31  ("scel", "Description and location of 'SCEL' file")
32  ("lat", "Description and location of 'LAT' files")
33  ("pos", "Description and location of 'POS' files")
34  ("eci", "Description and location of 'eci.json' file")
35  ("monte", "Description and location of the Monte Carlo input file");
36  return;
37  }
38  }
39 
40  // ///////////////////////////////////////
41  // 'format' function for casm
42  // (add an 'if-else' statement in casm.cpp to call this)
43 
44  int format_command(const CommandArgs &args) {
45 
46  po::variables_map vm;
47 
48  Completer::FormatOption format_opt;
49 
50  try {
51  po::store(po::parse_command_line(args.argc, args.argv, format_opt.desc()), vm);
52 
55  if(vm.count("help") || vm.size() == 0) {
56  args.log << std::endl;
57  args.log << format_opt.desc() << std::endl;
58 
59  return 0;
60  }
61 
62  if(vm.count("desc")) {
63  args.log << "\n";
64  args.log << format_opt.desc() << std::endl;
65 
66  args.log << "DESCRIPTION" << std::endl;
67  args.log << " This option describes the files contained within a CASM project \n";
68  args.log << " and where to find them. For a summary of the directory structure\n";
69  args.log << " of a CASM project using VASP for calculating configuration use \n";
70  args.log << " the --dir option. Not all files are always present. \n";
71 
72  return 0;
73  }
74 
75  po::notify(vm);
76 
77  }
78  catch(po::error &e) {
79  args.err_log << "ERROR: " << e.what() << std::endl << std::endl;
80  args.err_log << format_opt.desc() << std::endl;
81  return 1;
82  }
83  catch(std::exception &e) {
84  args.err_log << "Unhandled Exception reached the top of main: "
85  << e.what() << ", application will now exit" << std::endl;
86  return 1;
87 
88  }
89 
90  if(vm.count("dir")) {
91  args.log << "\n### dir ##################\n\n";
92 
93  args.log << " The expected CASM project directory structure with VASP settings \n";
94  args.log << " files: \n";
95  args.log << " \n";
96  args.log << " $ROOT/ \n";
97  args.log << " prim.json \n";
98  args.log << " (PRIM) \n";
99  args.log << " LOG \n";
100  args.log << " $ROOT/.casm \n";
101  args.log << " project_settings.json \n";
102  args.log << " config_list.json \n";
103  args.log << " composition_axes.json \n";
104  args.log << " $ROOT/symmetry/ \n";
105  args.log << " lattice_point_group.json \n";
106  args.log << " factor_group.json \n";
107  args.log << " crystal_point_group.json \n";
108  args.log << " $ROOT/basis_sets/$CURR_BSET/ \n";
109  args.log << " bspecs.json \n";
110  args.log << " basis.json \n";
111  args.log << " clust.json \n";
112  args.log << " $TITLE_Clexulator.* \n";
113  args.log << " $ROOT/training_data/ \n";
114  args.log << " SCEL \n";
115  args.log << " $ROOT/training_data/settings/$CURR_CALCTYPE/ \n";
116  args.log << " relax.json \n";
117  args.log << " INCAR \n";
118  args.log << " SPECIES \n";
119  args.log << " KPOINTS \n";
120  args.log << " POSCAR \n";
121  args.log << " $ROOT/training_data/settings/$CURR_CALCTYPE/$CURR_REF/ \n";
122  args.log << " chemical_reference.json \n";
123  args.log << " $ROOT/training_data/$SCELNAME/ \n";
124  args.log << " LAT \n";
125  args.log << " $ROOT/training_data/$SCELNAME/$CONFIGID \n";
126  args.log << " POS \n";
127  args.log << " $ROOT/training_data/$SCELNAME/$CONFIGID/$CURR_CALCTYPE \n";
128  args.log << " (VASP/QE results) \n";
129  args.log << " properties.calc.json \n";
130  args.log << " $ROOT/cluster_expansions/clex.formation_energy/$CURR_BSET/$CURR_CALCTYPE/$CURR_REF/$CURR_ECI\n";
131  args.log << " eci.json \n";
132  args.log << " \n";
133  args.log << " \n";
134  args.log << " Variable descriptions: \n";
135  args.log << " \n";
136  args.log << " $ROOT: root directory of the CASM project \n";
137  args.log << " \n";
138  args.log << " $CURR_BSET: Current basis set, by default this is 'bset.default'.\n";
139  args.log << " The current value can be inspected via 'casm settings -l'. \n";
140  args.log << " \n";
141  args.log << " $CURR_CALCTYPE: Current calctype, by default this is 'calctype.default'.\n";
142  args.log << " The current value can be inspected via 'casm settings -l'. \n";
143  args.log << " \n";
144  args.log << " $CURR_REF: Current composition axes and reference states, by \n";
145  args.log << " default this is 'ref.default'. The current value can be inspected\n";
146  args.log << " via 'casm settings -l'. \n";
147  args.log << " \n";
148  args.log << " $SCELNAME: Supercell name, in the form SCELV_A_B_C_D_E_F. 'V' is\n";
149  args.log << " volume of the supercell in terms of the primitive cell, and \n";
150  args.log << " 'A'-'F' are the values of the hermite normal form of the \n";
151  args.log << " transformation matrix. \n";
152  args.log << " \n";
153  args.log << " $CONFIGID: Configuration id, a unique integer. \n";
154  args.log << " \n";
155  args.log << " $TITLE: Title of the CASM project \n";
156  args.log << "\n";
157  args.log << " Note: The 'settings' heirarchy can be located at the project \n";
158  args.log << " level as shown above, or at the supercell or configuration level\n";
159  args.log << " in order to override calculation, composition, or reference \n";
160  args.log << " state settings at the supercell or configuration level. The \n";
161  args.log << " most local settings are always used for a configuration. \n";
162  args.log << " \n";
163 
164  }
165 
166  if(vm.count("project_settings")) {
167  args.log << "\n### project_settings.json ##################\n\n";
168 
169  args.log << "LOCATION WHEN GENERATED:\n";
170  args.log << "$ROOT/.casm/project_settings.json\n\n\n";
171 
172  args.log << "DESCRIPTION:\n";
173  args.log << "Current CASM project settings.\n\n\n";
174 
175  args.log << "EXAMPLE:\n";
176  args.log << "-------\n";
177  args.log <<
178  "{\n \"cluster_expansions\" : {\n \"formation_energy\" : {\n \"bset\" : \"default\",\n \"calctype\" : \"default\",\n \"eci\" : \"default\",\n \"name\" : \"formation_energy\",\n \"property\" : \"formation_energy\",\n \"ref\" : \"default\"\n }\n },\n \"crystallography_tol\" : 1.000000000000000082e-05,\n \"curr_properties\" : [ \"relaxed_energy\" ],\n \"default_clex\" : \"formation_energy\",\n \"lin_alg_tol\" : 1.000000000000000036e-10,\n \"name\" : \"ZrO\",\n \"nlist_sublat_indices\" : [ 2, 3 ],\n \"nlist_weight_matrix\" : [\n [ 2, -1, 0 ],\n [ -1, 2, 0 ],\n [ 0, 0, 5 ]\n ],\n \"query_alias\" : {\n },\n \"view_command\" : \"casm.view \\\"open -a /Applications/VESTA/VESTA.app\\\"\"\n}" << std::endl;
179  args.log << "-------\n";
180  args.log << std::endl << std::endl;
181  }
182 
183  if(vm.count("prim")) {
184  args.log << "\n### prim.json ##################\n\n";
185 
186  args.log << "LOCATION WHEN GENERATED:\n";
187  args.log << "$ROOT/prim.json\n";
188  args.log << "$ROOT/PRIM (legacy)\n\n\n";
189 
190  args.log << "DESCRIPTION:\n";
191  args.log << "'prim.json' describes the primitive cell structure. It includes the lattice \n";
192  args.log << "vectors, crystal basis sites and a list of possible occupant molecules on each\n";
193  args.log << "basis site.\n\n";
194 
195  args.log << "'prim.json' parameters: \n\n"
196 
197  "\"title\" (string): \n"
198  " A title for the project. Must consist of alphanumeric characters \n"
199  " and underscores only. The first character may not be a number. \n\n"
200 
201  "\"lattice_vectors\" (JSON array of 3 JSON arrays of 3 numbers): \n"
202  " Lattice vectors for the primitive structure, in Angstroms. \n\n"
203 
204  "\"coordinate_mode\" (string): \n"
205  " Coordinate mode for basis sites. One of: \n"
206  " \"Fractional\" or \"Direct\", \n"
207  " \"Cartesian\" \n\n"
208 
209  "\"basis\" (JSON array of JSON objects): \n\n"
210 
211  " /\"coordinate\" (JSON array of 3 numbers): \n"
212  " Coordinate of the basis site with units as specified by the \n"
213  " the \"coordinate_mode\" parameter. The default tolerance for \n"
214  " checking symmetry is 1e-5, so basis site coordinates should \n"
215  " include 6 significant digits or more. \n"
216 
217  " /\"occupant_dof\" (JSON array of string): \n"
218  " A list of the possible occupant atoms (and in future versions \n"
219  " CASM, molecules) that on each site. The names are case \n"
220  " sensitive, and \"Va\" is reserved for vacancies. \n\n\n";
221 
222 
223  args.log << "EXAMPLE 1: An FCC ternary alloy of elements A, B, and C\n";
224  args.log << "-------\n";
225  args.log <<
226  "{\n \"basis\" : [\n {\n \"coordinate\" : [ 0.000000000000, 0.000000000000, 0.000000000000 ],\n \"occupant_dof\" : [ \"A\", \"B\", \"C\" ]\n }\n ],\n \"coordinate_mode\" : \"Fractional\",\n \"description\" : \"Face-centered Cubic (FCC, cF)\",\n \"lattice_vectors\" : [\n [ 2.000000000000, 2.000000000000, 0.000000000000 ],\n [ 0.000000000000, 2.000000000000, 2.000000000000 ],\n [ 2.000000000000, 0.000000000000, 2.000000000000 ]\n ],\n \"title\" : \"ABC\"\n}\n";
227  args.log << "-------\n\n";
228 
229  args.log << "EXAMPLE 2: HCP Zr with O in octahedral interstitial positions\n";
230  args.log << "-------\n";
231  args.log <<
232  "\n{\n \"basis\" : [\n {\n \"coordinate\" : [ 0.0, 0.0, 0.0 ],\n \"occupant_dof\" : [ \"Zr\" ]\n },\n {\n \"coordinate\" : [ 0.666666, 0.333333, 0.5 ],\n \"occupant_dof\" : [ \"Zr\" ]\n },\n {\n \"coordinate\" : [ 0.333333, 0.666666, 0.25 ],\n \"occupant_dof\" : [ \"Va\", \"O\" ]\n },\n {\n \"coordinate\" : [ 0.333333, 0.666666, 0.75 ],\n \"occupant_dof\" : [ \"Va\", \"O\" ]\n }\n ],\n \"coordinate_mode\" : \"Fractional\",\n \"description\" : \"hcp Zr with oct (O) \",\n \"lattice_vectors\" : [\n [ 3.233986860000, 0.000000000000, 0.000000000000 ],\n [ -1.616993430000, 2.800714770000, 0.000000000000 ],\n [ -0.000000000000, 0.000000000000, 5.168678340000 ]\n ],\n \"title\" : \"ZrO\"\n}\n";
233  args.log << "-------\n\n";
234 
235  args.log << "\n### PRIM ##################\n\n";
236 
237  args.log << "DESCRIPTION:\n";
238  args.log << "PRIM is the input file used by previous version of casm. It can be read and \n";
239  args.log << "converted to 'prim.json'. The format of PRIM is very similar to the VASP POSCAR \n";
240  args.log << "except a list of possible occupant molecules is included with each basis site. \n\n";
241 
242  args.log << "- Molecule names are case sensitive.\n";
243  args.log << "- 'Va' is reserved for vacancies.\n";
244  args.log << "- The default tolerance for checking symmetry is 1e-5, so basis site coordinates\n";
245  args.log << " should include 6 significant digits or more.\n\n\n";
246 
247  args.log << "EXAMPLE 1: An FCC ternary alloy of elements A, B, and C\n";
248  args.log << "-------\n";
249  args.log <<
250  "Face-centered Cubic (FCC, cF)\n\
251 1.0\n\
252 0 2.0 2.0\n\
253 2.0 0 2.0\n\
254 2.0 2.0 0\n\
255 1\n\
256 D\n\
257 0.00 0.00 0.00 A B C\n";
258  args.log << "-------\n\n";
259  args.log << "EXAMPLE 2: A structure with some alloying sites and some non-alloying sites\n";
260  args.log << "-------\n";
261  args.log <<
262  "LiTiO2 - Bronze\n\
263  1.00000000\n\
264  1.91357600 0.00000000 -6.23799200\n\
265  6.08935000 -1.87060000 0.00000000\n\
266  0.00000000 -3.74120000 0.00000000\n\
267  5 4 8\n\
268 Direct\n\
269  0.0000000 0.0000000 0.0000000 Li Va\n\
270  0.3800000 0.9000000 0.5500000 Li Va\n\
271  0.6200000 0.1000000 0.4500000 Li Va\n\
272  0.0000000 0.2600000 0.3700000 Li Va\n\
273  0.0000000 0.7400000 0.6300000 Li Va\n\
274  0.7080000 0.3940000 0.8030000 Ti\n\
275  0.2920000 0.6060000 0.1970000 Ti\n\
276  0.2950000 0.1980000 0.9010000 Ti\n\
277  0.7050000 0.8020000 0.0990000 Ti\n\
278  0.9960000 0.2640000 0.8680000 O\n\
279  0.0040000 0.7360000 0.1320000 O\n\
280  0.3470000 0.5280000 0.7360000 O\n\
281  0.6530000 0.4720000 0.2640000 O\n\
282  0.6290000 0.1200000 0.9400000 O\n\
283  0.3710000 0.8800000 0.0600000 O\n\
284  0.7070000 0.7240000 0.6380000 O\n\
285  0.2930000 0.2760000 0.3620000 O\n";
286  args.log << "-------\n";
287  args.log << std::endl << std::endl;
288  }
289 
290  if(vm.count("config_list")) {
291  args.log << "\n### config_list.json ##################\n\n";
292 
293  args.log << "LOCATION WHEN GENERATED:\n";
294  args.log << "$ROOT/.casm/config_list.json\n\n\n";
295 
296  args.log << "DESCRIPTION:\n";
297  args.log << "A list of generated configurations. This file is generated at the \n";
298  args.log << "project level once 'casm enum' has been used to generate \n";
299  args.log << "configurations. \n";
300  args.log << " \n";
301  args.log << "Contains basic information describing the configuration: \n\n" <<
302 
303  "supercells:supercell_name:configid: \n" <<
304  " Configurations are organized in the JSON file first by the SCELNAME \n" <<
305  " and then listed by the configuration's CONFIGID. \n\n" <<
306 
307  "source: \n" <<
308  " Describes the possibly mutiple ways in which this configuration \n" <<
309  " was generated. Possibilities are \"enumerated\": the configuration\n" <<
310  " was generated when all symmetrically unique configurations of the \n" <<
311  " supercell were enumerated, or \"perturbation\": the configuration \n" <<
312  " was generated as a perturbation with respect to some other \n" <<
313  " configuration. \n\n" <<
314 
315  "occupation: \n" <<
316  " An array of int that describes the decoration for a particular \n" <<
317  " configuration in a given supercell. The length of the array is the\n" <<
318  " same length as your basis, with each value corresponding to a \n" <<
319  " particular basis site on the supercell. The value for a particular\n" <<
320  " site determines what type of molecule is occupying said site, with\n" <<
321  " values going from zero to the number of allowed occupants for that\n" <<
322  " particular site. The array is ordered in blocks of basis sites of \n" <<
323  " your primitive structure. \n\n" <<
324 
325  " For example, for an \"occupation\" corresponding to a volume 5 \n" <<
326  " supercell of a PRIM with 2 basis sites, the first 5 values in the \n" <<
327  " array represent basis sites for the first site in the PRIM, and \n" <<
328  " the next 5 represent basis sites for the second site in the PRIM. \n" <<
329  " The occupation values can also be read from the \'config\' column \n" <<
330  " of the config_list file. \n\n" <<
331 
332  "... other degrees of freedom will also be included in this file ... \n\n" <<
333 
334  "properties:calc: \n" <<
335  " This contains the values of properties calculated using a \n" <<
336  " particular calctype. Properties are normalized per unit cell where\n" <<
337  " appropriate (relaxed_energy, volume). \n\n" <<
338 
339  "properties:ref: \n" <<
340  " This contains the reference values of properties based on the \n" <<
341  " values of those properties in the current reference states for \n" <<
342  " this configuration. The reference values are determined by a \n" <<
343  " linear interpolation of their values in the reference states to \n" <<
344  " the composition of this configuration. The most local reference \n" <<
345  " states are used; see 'casm format --ref' for details. \n\n" <<
346 
347  "properties:delta: \n" <<
348  " This contains the difference between the properties listed in \n" <<
349  " \'properties:calc\' from those in \'properties:ref\'. These are \n" <<
350  " the values to be cluster expanded. \n\n";
351  args.log << "\n\n\n";
352 
353  args.log << "EXAMPLE:\n";
354  args.log << "-------\n";
355  args.log <<
356  "{\n \"supercells\" : {\n \"SCEL1_1_1_1_0_0_0\" : {\n \"0\" : {\n \"calctype.default\" : {\n \"ref.default\" : {\n \"properties\" : {\n \"calc\" : {\n \"basis_deformation\" : 0.000000000000,\n \"data_timestamp\" : 1441172550,\n \"lattice_deformation\" : 0.000000676576,\n \"relaxation_strain\" : [ 0.001443293898, 0.001443293305, 0.002332246990, 0.000000000000, 0.000000000000, -0.000000001264 ],\n \"relaxed_energy\" : -17.093958770000,\n \"rms_force\" : 0.000000000000,\n \"relaxed_magmom\" : -4.125372200000,\n \"volume_relaxation\" : 1.005222845232\n },\n \"delta\" : {\n \"relaxed_energy\" : 0.000000000000\n },\n \"ref\" : {\n \"relaxed_energy\" : -17.093958770000\n }\n }\n }\n },\n \"dof\" : {\n \"occupation\" : [ 0, 0, 0, 0 ]\n },\n \"selected\" : false,\n \"source\" : [ \"occupation_enumeration\" ]\n },\n\
357  ... other configurations ...\n\
358  },\n\
359  ... other supercells ... \n\
360  }\n\
361 }\n";
362  args.log << "-------\n";
363  args.log << std::endl << std::endl;
364  }
365 
366  if(vm.count("sym")) {
367  args.log << "\n### sym ##################\n\n";
368 
369  args.log << "LOCATION WHEN GENERATED:\n";
370  args.log << "$ROOT/symmetry/lattice_point_group.json\n";
371  args.log << "$ROOT/symmetry/factor_group.json\n";
372  args.log << "$ROOT/symmetry/crystal_point_group.json\n\n\n";
373 
374 
375 
376  args.log << "DESCRIPTION:\n" <<
377  "Symgroup files report each element of a group as representative \n" <<
378  "linear transformations of 3-dimensional space (i.e., the symmetry \n" <<
379  "operation). The symmetery operation transforms a spatial coordinate \n" <<
380  "'x' according to x' = A*x+b, where 'A' is the 3x3 'operation matrix'\n" <<
381  "and 'b' is the 'shift' vector. Operations are printed either in \n" <<
382  "direct (fractional) coordinates or Cartesian coordinates, depending \n" <<
383  "on command-line execution options.\n\n" <<
384 
385  "For a crystal or PRIM file, CASM reports the following groups: \n\n" <<
386 
387  "lattice_point_group.json: \n" <<
388  " This is the point group of the Bravais lattice, and is the list of\n" <<
389  " operations that map the lattice vectors onto themselves. The \n" <<
390  " 'shift' vectors will always be zero. \n\n" <<
391 
392  "factor_group.json: \n" <<
393  " This is a finite description of the crystal spacegroup, in which \n" <<
394  " all redundant operations that differ only by a 'shift' are \n" <<
395  " represented by a single operation, whose 'shift' lies within the \n" <<
396  " primitive cell. Formally, this is a group formed by the cosets of \n" <<
397  " 'T' in 'S', where 'T' is the translation group of the Bravais \n" <<
398  " lattice and 'S' is the crystal space group. \n\n" <<
399 
400  "crystal_point_group.json: \n" <<
401  " This is a group of point operations formed by taking the \n" <<
402  " factor group operations and setting their 'shifts' to zero. \n" <<
403  " Macroscopic properties of the crystal must exhibit the symmetries \n" <<
404  " of the crystal point group. It is, by definition a subgroup of \n" <<
405  " the lattice point group.\n";
406 
407  args.log << "\n\n";
408  }
409 
410  if(vm.count("vasp")) {
411  args.log << "\n### vasp ##################\n\n";
412 
413  args.log << "LOCATION WHEN GENERATED:\n\n";
414 
415  args.log << "INPUT SETTINGS:\n";
416  args.log << "$CALC_SETTINGS/relax.json\n";
417  args.log << "$CALC_SETTINGS/INCAR\n";
418  args.log << "$CALC_SETTINGS/SPECIES\n";
419  args.log << "$CALC_SETTINGS/KPOINTS\n";
420  args.log << "$CALC_SETTINGS/POSCAR\n\n";
421 
422  args.log << "For global settings:\n";
423  args.log << " CALC_SETTINGS = $ROOT/training_data/settings/$CURR_CALCTYPE\n";
424  args.log << "For supercell specific settings:\n";
425  args.log << " CALC_SETTINGS = $ROOT/training_data/$SCELNAME/settings/$CURR_CALCTYPE\n";
426  args.log << "For configuration specific settings:\n";
427  args.log << " CALC_SETTINGS = $ROOT/training_data/$SCELNAME/$CONFIGID/settings/$CURR_CALCTYPE\n\n";
428 
429  args.log << "RESULTS:\n";
430  args.log << "$ROOT/training_data/$SCELNAME/$CONFIGID/$CURR_CALCTYPE/(VASP results)\n";
431  args.log << "$ROOT/training_data/$SCELNAME/$CONFIGID/$CURR_CALCTYPE/properties.calc.json (read)\n";
432 
433  args.log << "\n\n";
434 
435  args.log << "DESCRIPTION:\n";
436  args.log << "CASM comes with wrappers for using VASP to calculate the properties \n" <<
437  "of configurations, but is designed so that any type of calculation \n" <<
438  "software or method could be used if an appropriate set of wrapper \n" <<
439  "scripts are available. By convention, input settings for software \n" <<
440  "used to calculate the properties of a particular configuration \n" <<
441  "should be checked for in the following directories: \n" <<
442  " 1) $ROOT/training_data/$SCELNAME/$CONFIGID/settings/$CURR_CALCTYPE\n" <<
443  " 2) $ROOT/training_data/$SCELNAME/settings/$CURR_CALCTYPE \n" <<
444  " 3) $ROOT/training_data/settings/$CURR_CALCTYPE \n\n" <<
445 
446  "The VASP wrappers included with CASM check for input settings files \n" <<
447  "in the above directories, using the most local settings for a \n" <<
448  "particular configuration. In most cases, the global settings files \n" <<
449  "are stored in $ROOT/training_data/settings/$CURR_CALCTYPE and used \n" <<
450  "for all configurations. Settings files are searched for on a file-by-file\n" <<
451  "basis, so to set supercell or configuration specific settings it is \n" <<
452  "sufficient to only include the particular files necessary in the \n" <<
453  "supercell or configuration level settings folder. \n\n" <<
454 
455  "PBS job submission using the VASP wrappers depends on using the pbs \n" <<
456  "python module available here: https://github.com/prisms-center/pbs \n\n" <<
457 
458  "Included with CASM, the 'vasp.relax' script can be executed by the \n" <<
459  "'casm run' command to submit a batch of VASP jobs that for selected \n" <<
460  "configurations. For each selected configuration, VASP is re-run \n" <<
461  "using the output of the previous calculation until full convergence \n" <<
462  "is achieved. The convergence criteria is: if the cell shape and \n" <<
463  "volume remain constant (ISIF=0, 1, or 2) then a single calculation \n" <<
464  "is performed; else the calculation is converged if at least 2 jobs \n" <<
465  "are complete, and: 1) the last job completed with <= 3 ionic steps \n" <<
466  " or, if \"nrg_convergence\" is set in the 'relax.json' file, 2) the \n" <<
467  "last two calculations had final E0 differ by less than the value of \n" <<
468  " \"nrg_convergence\". Once converged, a final constant volume \n" <<
469  "calculation is performed with the following INCAR settings: (ISIF=2,\n" <<
470  "ISMEAR=-5, NSW=0, IBRION=-1). \n\n" <<
471 
472  "relax.json: \n" <<
473  " This JSON file contains a single JSON object which contains \n" <<
474  " parameters used to control PBS job submission settings. \n" <<
475  " Required keys are: \n" <<
476  " \"queue\": queue to submit job in \n" <<
477  " \"ppn\": processors (cores) per node to request \n" <<
478  " \"atom_per_proc\": max number of atoms per processor (core) \n" <<
479  " \"walltime\": walltime to request (ex. \"48:00:00\") \n\n" <<
480 
481  " Optional keys are: \n" <<
482  " \"account\": account to submit job under (default None) \n" <<
483  " \"pmem\": string for requested memory (default None) \n" <<
484  " \"priority\": requested job priority (default \"0\") \n" <<
485  " \"message\": when to send messages about jobs (ex. \"abe\", \n" <<
486  " default \"a\") \n" <<
487  " \"email\": where to send messages (ex. \"me@fake.com\", default \n" <<
488  " None) \n" <<
489  " \"qos\": quality of service, 'qos' option (ex. \"fluxoe\") \n" <<
490  " \"npar\": vasp incar setting (default None) \n" <<
491  " \"ncore\": vasp incar setting (default None) \n" <<
492  " \"kpar\": vasp incar setting (default None) \n" <<
493  " \"vasp_cmd\": vasp execution command (default is \"vasp\" if \n" <<
494  " ncpus=1, else \"mpirun -np {NCPUS} vasp\" \n" <<
495  " \"ncpus\": number of cpus (cores) to run on (default $PBS_NP) \n" <<
496  " \"run_limit\": number of vasp runs until \"not_converging\" \n" <<
497  " (default 10) \n" <<
498  " \"nrg_convergence\": converged if last two runs complete and \n" <<
499  " differ in energy by less than this amount \n" <<
500  " (default None) \n" <<
501  " \"move\": files to move at the end of a run (ex. \"POTCAR\", \n" <<
502  " \"WAVECAR\"], default [\"POTCAR\"]) \n" <<
503  " \"copy\": files to copy from run to run (ex. [\"INCAR\", \n" <<
504  " \"KPOINTS\"], default [\"INCAR, KPOINTS\"]) \n" <<
505  " \"remove\": files to remove at the end of a run (ex. [\"IBZKPT\",\n" <<
506  " \"CHGCAR\"], default [\"IBKZPT\", \"CHG\", \"CHGCAR\",\n" <<
507  " \"WAVECAR\", \"TMPCAR\", \"EIGENVAL\", \"DOSCAR\", \n" <<
508  " \"PROCAR\", \"PCDAT\", \"XDATCAR\", \"LOCPOT\", \"ELFCAR\",\n" <<
509  " \"PROOUT\"] \n" <<
510  " \"compress\": files to compress at the end of a run (ex. \n" <<
511  " [\"OUTCAR\", \"vasprun.xml\"], default []) \n" <<
512  " \"backup\": files to compress to backups at the end of a run, \n" <<
513  " used in conjunction with move (ex. [\"WAVECAR\"]) \n" <<
514  " \"encut\": [START, STOP, STEP] values for converging ENCUT to \n" <<
515  " within nrg_convergence (ex. [\"450\", \"Auto\", \n" <<
516  " \"10\"], default [\"Auto\", \"Auto\", \"10\"] where \n" <<
517  " \"Auto\" is either the largest ENMAX in all POTCARS \n" <<
518  " called in SPECIES for START, or 2.0 * largest ENMAX \n" <<
519  " for STOP) \n" <<
520  " \"kpoints\": [start, stop, step] values for converging KPOINTS \n" <<
521  " to within nrg_convergence (ex. [\"5\", \"50\", \"1\"],\n" <<
522  " default [\"5\", \"Auto\", \"1\"] where \"Auto\" can \n" <<
523  " only be used for STOP and means to keep increasing \n" <<
524  " the KPOINTS length by STEP until either \n" <<
525  " nrg_convergence or walltime is reached). For meaning \n" <<
526  " of the KPOINTS length parameter see the VASP \n" <<
527  " documentation at http://cms.mpi.univie.ac.at/vasp/ \n" <<
528  " vasp/Automatic_k_mesh_generation.html \n" <<
529  " \"extra_input_files\": extra input files to be copied from the \n" <<
530  " settings directory, e.g., a vdW kernel \n" <<
531  " file. \n" <<
532  " \"initial\": location of INCAR with tags for the initial run, \n" <<
533  " if desired (e.g. to generate a PBE WAVECAR for use \n" <<
534  " with M06-L) \n" <<
535  " \"final\": location of INCAR with tags for the final run, if \n" <<
536  " desired (e.g. \"ISMEAR = -5\", etc). Otherwise, the \n" <<
537  " settings enforced are (\"ISMEAR = -5\", \"NSW = 0\", \n" <<
538  " \"IBRION = -1\", \"ISIF = 2\") \n" <<
539  " \"err_types\": list of errors to check for. Allowed entries are \n" <<
540  " \"IbzkptError\" and \"SubSpaceMatrixError\". \n" <<
541  " Default: [\"SubSpaceMatrixError\"] \n" <<
542  "\n";
543 
544  args.log << "EXAMPLE: relax.json \n";
545  args.log << "-------\n";
546  args.log <<
547  "{\n\
548  \"account\":\"prismsprojectdebug_flux\",\n\
549  \"queue\":\"flux\",\n\
550  \"priority\":\"-200\",\n\
551  \"walltime\":\"1:00:00\",\n\
552  \"pmem\":\"3800mb\",\n\
553  \"email\":\"username@univ.edu\",\n\
554  \"ppn\":\"16\",\n\
555  \"atom_per_proc\":\"2\",\n\
556  \"run_limit\":10,\n\
557  \"nrg_convergence\":0.002\n\
558 }\n";
559  args.log << "-------\n\n\n";
560 
561 
562  args.log << "SPECIES: \n" <<
563  " This file contains information for selecting POTCARs and specifing\n" <<
564  " parameters that must be set on an atom-by-atom basis in the INCAR,\n" <<
565  " such as MAGMOM. The first line in the file specifies the value of \n" <<
566  " 'POTCAR_DIR_PATH', which is the base path used to find POTCAR \n" <<
567  " files. The second line contains column headings (at least 4), and \n" <<
568  " then there are lines for each distinct species. The first column \n" <<
569  " specifies the 'SPECIES' and must match a species names in the PRIM\n" <<
570  " file. The second column gives an 'ALIAS' name for the species which\n" <<
571  " is used for ordering like atoms in the generated POSCAR files. The\n" <<
572  " third column should be either '0' or '1', such that only one \n" <<
573  " species with a given ALIAS has a '1'. For that species the fourth \n" <<
574  " column must contain the path that should be appended to the \n" <<
575  " POTCAR_DIR_PATH to specify the POTCAR file for that species. \n\n" <<
576 
577  " Additional columns, such as 'MAGMOM' in the example below are \n\n" <<
578  " and used to specify the value used for a particular species in the\n" <<
579  " INCAR. The column heading must match a valid VASP INCAR setting. \n\n";
580 
581  args.log << "EXAMPLE: SPECIES \n";
582  args.log << "-------\n" <<
583  "POTCAR_DIR_PATH = /absolute/path/to/vasp_potentials\n" <<
584  "SPECIES ALIAS POTCAR POTCAR_location MAGMOM\n" <<
585  "Mn3 Mn 0 - 3\n" <<
586  "Mn4 Mn 1 PAW_PBE/Mn 4\n";
587  args.log << "-------\n\n\n";
588 
589  args.log << "INCAR: \n" <<
590  " This is a template INCAR used for VASP calculations. The settings \n" <<
591  " are generally used as given though some may be automatically set \n" <<
592  " based on settings in the 'relax.json' or 'SPECIES' files. Also, \n" <<
593  " some settings might be added or changed if certain errors are \n" <<
594  " during calculation. The actual INCAR used for each calculation is \n" <<
595  " saved. \n\n";
596 
597  args.log << "EXAMPLE: INCAR \n";
598  args.log << "-------\n" <<
599  "System = Test of VASP submission\n\
600 ISPIN = 1 # non-spin polarized\n\
601 PREC = Accurate \n\
602 IBRION = 2 # conjugate gradient ionic minimization\n\
603 NSW = 61\n\
604 ISIF= 3 # relax ions and volume\n\
605 ENMAX = 400 \n\
606 ISMEAR = 1 # for metals\n\
607 SIGMA = 0.2 \n\
608 LWAVE = .FALSE.\n\
609 LCHARG = .FALSE.\n";
610  args.log << "-------\n\n\n";
611 
612  args.log << "KPOINTS, POSCAR: \n" <<
613  " This is a template KPOINTS file used for VASP calculations. If the\n" <<
614  " mode (third line) is set to 'Auto', this file is used as is for all\n" <<
615  " VASP calculations. Otherwise, if the mode is 'Gamma' or 'M', a \n" <<
616  " reference POSCAR must also exist and a scaling method is used to \n" <<
617  " calculate the kpoint mesh for a supercell, such that it has an \n" <<
618  " equal or greater kpoint density than in the reference POSCAR. \n\n";
619 
620  args.log << "-------\n";
621 
622  }
623 
624  if(vm.count("qe")) {
625  args.log << "\n### quantum espresso ##################\n\n";
626 
627  args.log << "LOCATION WHEN GENERATED:\n\n";
628 
629  args.log << "INPUT SETTINGS:\n";
630  args.log << "$CALC_SETTINGS/relax.json\n";
631  args.log << "$CALC_SETTINGS/$CUSTOM_INFILE_NAME\n";
632  args.log << "$CALC_SETTINGS/SPECIES\n";
633 
634  args.log << "For global settings:\n";
635  args.log << " CALC_SETTINGS = $ROOT/training_data/settings/$CURR_CALCTYPE\n";
636  args.log << "For supercell specific settings:\n";
637  args.log << " CALC_SETTINGS = $ROOT/training_data/$SCELNAME/settings/$CURR_CALCTYPE\n";
638  args.log << "For configuration specific settings:\n";
639  args.log << " CALC_SETTINGS = $ROOT/training_data/$SCELNAME/$CONFIGID/settings/$CURR_CALCTYPE\n\n";
640 
641  args.log << "RESULTS:\n";
642  args.log << "$ROOT/training_data/$SCELNAME/$CONFIGID/$CURR_CALCTYPE/(quantum espresso results)\n";
643  args.log << "$ROOT/training_data/$SCELNAME/$CONFIGID/$CURR_CALCTYPE/properties.calc.json (read)\n";
644 
645  args.log << "\n\n";
646 
647  args.log << "DESCRIPTION:\n";
648  args.log << "CASM comes with wrappers for using Quantum Espresso to calculate the properties \n" <<
649  "of configurations, but is designed so that any type of calculation \n" <<
650  "software or method could be used if an appropriate set of wrapper \n" <<
651  "scripts are available. By convention, input settings for software \n" <<
652  "used to calculate the properties of a particular configuration \n" <<
653  "should be checked for in the following directories: \n" <<
654  " 1) $ROOT/training_data/$SCELNAME/$CONFIGID/settings/$CURR_CALCTYPE\n" <<
655  " 2) $ROOT/training_data/$SCELNAME/settings/$CURR_CALCTYPE \n" <<
656  " 3) $ROOT/training_data/settings/$CURR_CALCTYPE \n\n" <<
657 
658  "The Quantum Espresso wrappers included with CASM check for input settings files \n" <<
659  "in the above directories, using the most local settings for a \n" <<
660  "particular configuration. In most cases, the global settings files \n" <<
661  "are stored in $ROOT/training_data/settings/$CURR_CALCTYPE and used \n" <<
662  "for all configurations. Settings files are searched for on a file-by-file\n" <<
663  "basis, so to set supercell or configuration specific settings it is \n" <<
664  "sufficient to only include the particular files necessary in the \n" <<
665  "supercell or configuration level settings folder. \n\n" <<
666 
667  "PBS job submission using the Quantum Espresso wrappers depends on using the pbs \n" <<
668  "python module available here: https://github.com/prisms-center/pbs \n\n" <<
669 
670  "Included with CASM, the 'qe.relax' script can be executed by the \n" <<
671  "'casm run' command to submit a batch of Quantum Espresso jobs that for selected \n" <<
672  "configurations. For each selected configuration, Quantum Espresso is re-run\n" <<
673  "using the output of the previous calculation until full convergence \n" <<
674  "is achieved. The convergence criteria is: if the cell shape and \n" <<
675  "volume remain constant (calculation != vc-relax) then a single calculation \n" <<
676  "is performed; else the calculation is converged if at least 2 jobs \n" <<
677  "are complete, and: 1) the last job completed with <= 3 ionic steps \n" <<
678  " or, if \"nrg_convergence\" is set in the 'relax.json' file, 2) the \n" <<
679  "last two calculations had final energy differ by less than the value of \n" <<
680  " \"nrg_convergence\". Once converged, a final constant volume \n" <<
681  "calculation is performed with the following setting: (calculation = 'relax')\n" <<
682 
683  "relax.json: \n" <<
684  " This JSON file contains a single JSON object which contains \n" <<
685  " parameters used to control PBS job submission settings. \n" <<
686  " Required keys are: \n" <<
687  " \"queue\": queue to submit job in \n" <<
688  " \"ppn\": processors (cores) per node to request \n" <<
689  " \"atom_per_proc\": max number of atoms per processor (core) \n" <<
690  " \"walltime\": walltime to request (ex. \"48:00:00\") \n\n" <<
691  " \"software\": needs to be quantumespresso for quantum espresso to be used\n\n" <<
692 
693  " Optional keys are: \n" <<
694  " \"account\": account to submit job under (default None) \n" <<
695  " \"pmem\": string for requested memory (default None) \n" <<
696  " \"priority\": requested job priority (default \"0\") \n" <<
697  " \"message\": when to send messages about jobs (ex. \"abe\", \n" <<
698  " default \"a\") \n" <<
699  " \"email\": where to send messages (ex. \"me@fake.com\", default \n" <<
700  " None) \n" <<
701  " \"qos\": quality of service, 'qos' option (ex. \"fluxoe\") \n" <<
702  " \"qe_cmd\": quantum espresso execution command (default is \"pw.x < {INFILE} > {OUTFILE}\" if \n" <<
703  " ncpus=1, else \"mpirun -np {NCPUS} pw.x < {INFILE} > {OUTFILE}\" \n" <<
704  " \"infile\": quantum espresso input file name (default is \"std.in\"\n" <<
705  " \"outfile\": quantum espresso output file name (default is \"std.out\"\n" <<
706  " \"ncpus\": number of cpus (cores) to run on (default $PBS_NP) \n" <<
707  " \"run_limit\": number of vasp runs until \"not_converging\" \n" <<
708  " (default 10) \n" <<
709  " \"nrg_convergence\": converged if last two runs complete and \n" <<
710  " differ in energy by less than this amount \n" <<
711  " (default None) \n" <<
712  " \"move\": files to move at the end of a run (ex. \"\", \n" <<
713  " \".wfc\"], default []) \n" <<
714  " \"copy\": files to copy from run to run default [$infilename]) \n" <<
715  " \"remove\": files to remove at the end of a run \n" <<
716  " default [\".wfc\", \".igk\", \".save\"] \n" <<
717  " \"compress\": files to compress at the end of a run (ex. \n" <<
718  " [$outfilename], default []) \n" <<
719  " \"backup\": files to compress to backups at the end of a run, \n" <<
720  " used in conjunction with move (ex. [\".wfc\"]) \n" <<
721  " \"extra_input_files\": extra input files to be copied from the \n" <<
722  " settings directory, e.g., an OCCUPATIONS \n" <<
723  " file. \n" <<
724  " \"initial\": location of $infile with tags for the initial run, \n" <<
725  " if desired \n" <<
726  " \"final\": location of $infile with tags for the final run, if \n" <<
727  " desired \n" <<
728  " \"err_types\": list of errors to check for. Not Implemented yet \n" <<
729  "\n";
730 
731  args.log << "EXAMPLE: relax.json \n";
732  args.log << "-------\n";
733  args.log <<
734  "{\n\
735  \"account\":\"prismsprojectdebug_flux\",\n\
736  \"queue\":\"flux\",\n\
737  \"priority\":\"-200\",\n\
738  \"walltime\":\"1:00:00\",\n\
739  \"pmem\":\"3800mb\",\n\
740  \"email\":\"username@univ.edu\",\n\
741  \"ppn\":\"16\",\n\
742  \"atom_per_proc\":\"2\",\n\
743  \"run_limit\":10,\n\
744  \"nrg_convergence\":0.002\n\
745  \"calculator\":\"quantumespresso\"\n\
746  \"infilename\":\"LixCoO2.in\"\n\
747  \"outfilename\":\"LixCoO2.out\"\n\
748 }\n";
749  args.log << "-------\n\n\n";
750 
751 
752  args.log << "SPECIES: \n" <<
753  " This file contains information for selecting pseudopotentials and specifing\n" <<
754  " parameters that must be set on an atom-by-atom basis in the infile,\n" <<
755  " such as magnetic moment (non currently implemented).\n" <<
756  " The first line in the file specifies the value of \n" <<
757  " 'PSEUDO_DIR_PATH', which is the base path used to find UPF \n" <<
758  " files. The second line contains column headings (at least 4), and \n" <<
759  " then there are lines for each distinct species. The first column \n" <<
760  " specifies the 'SPECIES' and must match a species names in the PRIM\n" <<
761  " file. The second column gives an 'ALIAS' name for the species which\n" <<
762  " is used for ordering like atoms in the generated input files. The\n" <<
763  " third column should be either '0' or '1', such that only one \n" <<
764  " species with a given ALIAS has a '1'. For that species the fourth \n" <<
765  " column must contain the path that should be appended to the \n" <<
766  " PSEUDO_DIR_PATH to specify the UPF file for that species. \n\n" <<
767  " Additional columns, such as 'if_pos' in the example below are \n\n" <<
768  " and used to specify the value used for a particular species in the\n" <<
769  " infile. The column heading must match a valid quantum espresso input setting.\n"
770  " For now only supported additional tag is if_pos, a way to fixed certain lattice positions.\n\n";
771 
772  args.log << "EXAMPLE: SPECIES \n";
773  args.log << "-------\n" <<
774  "PSEUDO_DIR_PATH = /absolute/path/to/quantumespresso_potentials\n" <<
775  "SPECIES ALIAS UPF UPF_location if_pos\n" <<
776  "Ni Ni 1 PAW_PBE/Ni.UPF 1,1,1\n" <<
777  "Al Al 1 PAW_PBE/Al.UPF 1,1,1\n";
778  args.log << "-------\n\n\n";
779 
780  args.log << "$infilename: \n" <<
781  " This is a template input file used for Quantum Espresso calculations. The settings \n" <<
782  " are generally used as given though some may be automatically set \n" <<
783  " based on settings in the 'relax.json' or 'SPECIES' files. Also, \n" <<
784  " some settings might be added or changed if certain errors are \n" <<
785  " during calculation. The actual input file used for each calculation is \n" <<
786  " saved. \n\n";
787  args.log << "Note: \n" <<
788  " K_POINTS will be adjusted accordingly such that the density is maintained\n" <<
789  " over all configurations in the project for all Quantum Espresso calculations\n" <<
790  " this uses the CELL_PARAMETERS and the K_POINTS cards in the input file to calculate\n" <<
791  " a density and rescale configurations k-point mesh accordingly\n";
792 
793  args.log << "EXAMPLE: Mg2Ti4S8.in \n";
794  args.log << "-------\n" <<
795  "System = Test of Quantum Espresso submission\n\
796 &CONTROL\n\
797  calculation = 'vc-relax',\n\
798  pseudo_dir = '/home/skolli/quantum_espresso/pseudo/',\n\
799  tprnfor = .true.,\n\
800  prefix = 'Mg2Ti4S8',\n\
801  restart_mode = 'from_scratch',\n\
802  tstress = .true.,\n\
803 /\n\
804 &SYSTEM\n\
805  ecutwfc = 45.0,\n\
806  occupations = 'fixed',\n\
807  celldm(1) = 7.3794,\n\
808  ibrav = 0,\n\
809  nat = 14,\n\
810  ntyp = 3,\n\
811  ecutrho = 200.0,\n\
812 /\n\
813 &ELECTRONS\n\
814  diagonalization = 'cg',\n\
815  mixing_mode = 'plain',\n\
816  mixing_beta = 0.7,\n\
817  conv_thr = 1e-08,\n\
818 /\n\
819 &IONS\n\
820  ion_dynamics = 'bfgs',\n\
821 /\n\
822 &CELL\n\
823  press = 0.1,\n\
824  cell_factor = 1.6,\n\
825  cell_dynamics = 'bfgs',\n\
826 /\n\
827 \n\
828 ATOMIC_SPECIES\n\
829  Mg 24.31 Mg.pbe-nsp-bpaw.UPF\n\
830  Ti 47.88 Ti.pbe-sp-hgh.UPF\n\
831  S 32.07 S.pbe-n-kjpaw_psl.0.1.UPF\n\
832 \n\
833 CELL_PARAMETERS angstrom\n\
834  0.0000000000000000 5.1756022947592379 5.1756022947592388\n\
835  5.1756022947592388 0.0000000000000000 5.1756022947592388\n\
836  5.1756022947592388 5.1756022947592379 0.0000000000000000\n\
837 \n\
838 ATOMIC_POSITIONS crystal\n\
839 Mg 0.000000000 0.000000000 0.000000000\n\
840 Mg 0.250000000 0.250000000 0.250000000\n\
841 Ti 0.625000000 0.625000000 0.625000000\n\
842 Ti 0.125000000 0.625000000 0.625000000\n\
843 Ti 0.625000000 0.125000000 0.625000000\n\
844 Ti 0.625000000 0.625000000 0.125000000\n\
845 S 0.3842989149764762 0.3842989149764762 0.3842989149764762\n\
846 S 0.8657010850235238 0.8657010850235238 0.8657010850235238\n\
847 S 0.3842989149764762 0.8471032550705786 0.3842989149764762\n\
848 S 0.3842989149764762 0.3842989149764762 0.8471032550705786\n\
849 S 0.8471032550705786 0.3842989149764762 0.3842989149764762\n\
850 S 0.8657010850235238 0.8657010850235238 0.4028967449294214\n\
851 S 0.8657010850235238 0.4028967449294214 0.8657010850235238\n\
852 S 0.4028967449294214 0.8657010850235238 0.8657010850235238\n\
853 \n\
854 K_POINTS automatic\n\
855  6 6 6 0 0 0\n\
856 \n";
857  args.log << "-------\n\n\n";
858 
859  }
860  if(vm.count("properties")) {
861  args.log << "\n### properties.calc.json ##################\n\n";
862 
863  args.log << "properties.calc.json: \n" <<
864  " Results of calculations for a particular configuration should be \n" <<
865  " stored in the directory \n" <<
866  " $ROOT/training_data/$SCELNAME/$CONFIGID/$CURR_CALCTYPE, \n" <<
867  " and calculated properties summarized in the file \n" <<
868  " $ROOT/training_data/$SCELNAME/$CONFIGID/$CURR_CALCTYPE/properties.calc.json \n" <<
869  " The 'properties.calc.json' file is read by CASM to extract the \n" <<
870  " first-principles calculted properties of interest. If the \n" <<
871  " 'properties.calc.json' file does not exist in the \n" <<
872  " $ROOT/training_data/$SCELNAME/$CONFIGID/$CURR_CALCTYPE directory\n" <<
873  " CASM assumes that no data is available for that configuration. \n" <<
874  " The 'properties.calc.json' uses CASM standard units eV and Angstroms\n\n" ;
875 
876  args.log << "EXAMPLE:\n";
877  args.log << "-------\n";
878  args.log << "{\n\
879  \"atom_type\": [\n\
880  \"A\", \n\
881  \"B\"\n\
882  ], \n\
883  \"atoms_per_type\": [\n\
884  1, \n\
885  2\n\
886  ], \n\
887  \"coord_mode\": \"direct\", \n\
888  \"is_complete\": true, \n\
889  \"relaxed_basis\": [\n\
890  [0.6666667, 0.6666667, 0.6666667],\n\
891  [0.00255632, 0.99488736, 0.00255632],\n\
892  [0.33077698, 0.33844594, 0.33077698]\n\
893  ], \n\
894  \"relaxed_energy\": -16.27773537, \n\
895  \"relaxed_mag_basis\": [\n\
896  -3.93,\n\
897  3.82,\n\
898  1.198\n\
899  ], \n\
900  \"relaxed_magmom\": -1.3086, \n\
901  \"relaxed_forces\": [\n\
902  [0.0, 0.0, 0.0], \n\
903  [0.0, 0.00987362, -0.00987362], \n\
904  [0.0, -0.00987362, 0.00987362]\n\
905  ], \n\
906  \"relaxed_lattice\": [\n\
907  [0.0, 1.9174843, 1.9174843], \n\
908  [1.61158655, -1.88219884, 3.79968315], \n\
909  [3.22317311, 0.0, 0.0]\n\
910  ]\n\
911  }\n";
912  args.log << "-------\n";
913 
914  }
915  if(vm.count("comp")) {
916  args.log << "\n### composition_axes.json ##################\n\n";
917 
918  args.log << "LOCATION WHEN GENERATED:\n";
919  args.log << "$ROOT/.casm/composition_axes.json\n";
920  args.log << "\n\n";
921 
922  args.log << "DESCRIPTION:\n";
923  args.log << "This JSON file contains the currently selected composition axes, and \n" <<
924  "a list of possible standard or custom composition axes. \n\n" <<
925 
926  "standard_axes: \n" <<
927  " A JSON object containing each possible standard composition axes \n" <<
928  " as an attribute with its index as the key. \n\n" <<
929 
930  "custom_axes: \n" <<
931  " A JSON object containing each custom composition axes as an \n" <<
932  " attribute with its index as the key. The keys should not be \n" <<
933  " repeats of any of the standard_axes. \n\n" <<
934 
935  "standard_axes/custom_axes:components \n" <<
936  " A JSON array containing the names of possible species. \n\n" <<
937 
938  "standard_axes/custom_axes:independent_compositions \n" <<
939  " The number of independent composition axes. \n\n" <<
940 
941  "standard_axes/custom_axes:origin \n" <<
942  " The composition of origin the of composition axes in terms of \n" <<
943  " number of each component species per primitive cell, ordered as in\n" <<
944  " the 'components' array. \n\n" <<
945 
946  "standard_axes/custom_axes:a, b, c, ... \n" <<
947  " The composition of end members a, b, c, etc. in terms of number of\n" <<
948  " each component species per primitive cell, ordered as in the \n" <<
949  " 'components' array. \n\n" <<
950 
951  "standard_axes/custom_axes:param_formula: \n" <<
952  " The formula that converts 'comp_n' (# of each component per \n" <<
953  " primitive cell) to 'comp' (composition relative the selected \n" <<
954  " composition axes). \n\n" <<
955 
956  "standard_axes/custom_axes:mol_formula: \n" <<
957  " The formula that converts 'comp' (composition relative the \n" <<
958  " selected composition axes) to 'comp_n' (# of each component per \n" <<
959  " primitive cell). \n\n\n";
960 
961 
962  args.log << "EXAMPLE:\n";
963  args.log << "-------\n";
964  args.log <<
965  "{\n \"current_axes\" : \"0\",\n \"standard_axes\" : {\n \"0\" : {\n \"a\" : [\n [ 2.000000000000 ],\n [ 0.000000000000 ],\n [ 2.000000000000 ]\n ],\n \"components\" : [ \"Zr\", \"Va\", \"O\" ],\n \"independent_compositions\" : 1,\n \"mol_formula\" : \"Zr(2)Va(2-2a)O(2a)\",\n \"origin\" : [\n [ 2.000000000000 ],\n [ 2.000000000000 ],\n [ 0.000000000000 ]\n ],\n \"param_formula\" : \"a(0.5-0.25Va+0.25O)\"\n },\n \"1\" : {\n \"a\" : [\n [ 2.000000000000 ],\n [ 2.000000000000 ],\n [ 0.000000000000 ]\n ],\n \"components\" : [ \"Zr\", \"Va\", \"O\" ],\n \"independent_compositions\" : 1,\n \"mol_formula\" : \"Zr(2)Va(2a)O(2-2a)\",\n \"origin\" : [\n [ 2.000000000000 ],\n [ 0.000000000000 ],\n [ 2.000000000000 ]\n ],\n \"param_formula\" : \"a(0.5+0.25Va-0.25O)\"\n }\n }\n}\n";
966 
967  args.log << "-------\n";
968 
969  }
970 
971  if(vm.count("bspecs")) {
972  args.log << "\n### bspecs.json ##################\n\n";
973 
974  args.log << "LOCATION:\n";
975  args.log << "$ROOT/basis_sets/$CURR_BSET/bspecs.json\n";
976  args.log << "\n\n";
977 
978  args.log << "DESCRIPTION:\n";
979  args.log << "This JSON file contains specifications for generating the cluster\n" <<
980  "basis functions. \n\n";
981 
982  std::cout << "'site_basis_functions' may specify a string, which can be either 'occupation' or \n"
983  << "'chebychev'. Otherwise, specifies a JSON object containing a composition vector or\n"
984  << "a JSON array containing multiple composition vectors. A single composition vector\n"
985  << "is formatted as, e.g.\n"
986  << " \"composition\" : {\"Au\" : 0.25, \"Cu\" : 0.75} \n"
987  << "The site basis functions will then be constructed as to be optimized for that composition.\n\n"
988 
989  << "To specify different compositions on multiple sublattices, an array can be used. \n"
990  << "As an example, the following specifies a different composition on sublattice 0 than\n"
991  << "on sublattices 1 and 3: \n\n"
992 
993  << " \"site_basis_functions\" : [\n"
994  << " {\n"
995  << " \"composition\" : {\"Ga\" : 0.3, \"In\" : 0.7},\n"
996  << " \"sublat_indices\" : [0]\n"
997  << " },\n"
998  << " {\n"
999  << " \"composition\" : {\"Ga\" : 1.0, \"In\" : 0.0},\n"
1000  << " \"sublat_indices\" : [1,2]\n"
1001  << " }\n"
1002  << " ]\n\n"
1003 
1004  << "Sublattices are specified in the same order as in prim.json. Sublattice compositions\n"
1005  << "are not allowed to break the symmetry of the crystal. If equivalent sublattices are\n"
1006  << "assigned inequivalent compositions, one will be chosen arbitrarily and propagated to\n"
1007  << "all equivalent sublattices. The resulting site basis functions can be reviewed using\n"
1008  << "'casm bset --functions'\n\n";
1009 
1010 
1011  args.log << "The JSON object 'orbit_branch_specs' specifies the maximum size of pair, \n" <<
1012  "triplet, quadruplet, etc. clusters in terms of the maximum distance \n" <<
1013  "between any two sites in the cluster.\n\n";
1014 
1015  args.log << "The JSON array 'orbit_specs' allows specifying particular custom orbits \n" <<
1016  "by providing the prototype cluster coordinates. The 'include_subclusters' \n" <<
1017  "option allows including all orbits of subclusters of the specified cluster.\n" <<
1018  "The cluster coordinates may be in \"Direct\"/\"Fractional\" coordinates, \n"
1019  "\"Cartesian\" coordinates, or \"Integral\" coordinates. \"Integral\" \n"
1020  "coordinates are 4-element integer arrays indicating sublattice index, b, \n"
1021  "followed by unit cell indices, i, j, k. \n\n\n";
1022 
1023 
1024  args.log << "EXAMPLE:\n";
1025  args.log << "-------\n";
1026  args.log <<
1027  "{\n \"basis_functions\" : {\n \"site_basis_functions\" : \"occupation\"\n },\n \"orbit_branch_specs\" : {\n \"2\" : {\"max_length\" : 4.01},\n \"3\" : {\"max_length\" : 3.01}\n },\n \"orbit_specs\" : [\n {\n \"coordinate_mode\" : \"Direct\",\n \"prototype\" : [\n [ 0.000000000000, 0.000000000000, 0.000000000000 ],\n [ 1.000000000000, 0.000000000000, 0.000000000000 ],\n [ 2.000000000000, 0.000000000000, 0.000000000000 ],\n [ 3.000000000000, 0.000000000000, 0.000000000000 ]\n ],\n \"include_subclusters\" : true \n },\n {\n \"coordinate_mode\" : \"Integral\",\n \"prototype\" : [\n [ 0, 0, 0, 0 ],\n [ 1, 0, 0, 0 ],\n [ 0, 0, 0, 3 ]\n ],\n \"include_subclusters\" : true\n }\n ]\n}\n";
1028  args.log << "-------\n";
1029 
1030  }
1031 
1032  if(vm.count("clust")) {
1033  args.log << "\n### clust.json ##################\n\n";
1034 
1035  args.log << "LOCATION:\n";
1036  args.log << "$ROOT/basis_sets/$CURR_BSET/clust.json\n";
1037  args.log << "\n\n";
1038 
1039  args.log << "DESCRIPTION:\n";
1040  args.log << "This JSON file contains the coordinates of sites in the prototype \n" <<
1041  "clusters generated using the 'bspecs.json' specifications. \n\n";
1042 
1043 
1044  args.log << "Prototype clusters can be accessed via: \n"
1045  " [\"branches\"][branch_index][\"orbits\"][orbit_index][\"prototype\"]\n\n"
1046 
1047  "\"prototype\": (JSON object) \n"
1048 
1049  " /\"max_length\": (number) \n"
1050  " Maximum pair distance between sites in the cluster \n\n"
1051 
1052  " /\"min_length\": (number) \n"
1053  " Minimum pair distance between sites in the cluster \n\n"
1054 
1055  " /\"sites\": (JSON array of Integral coordinates) \n"
1056  " An array listing sites in the prototype cluster using Integral\n"
1057  " coordinates. Integral coordinates are 4-element integer arrays\n"
1058  " indicating sublattice index, b, followed by unit cell indices,\n"
1059  " i, j, k. \n\n"
1060 
1061  "\"bspecs\": (JSON object) \n"
1062  " For reference, the contents of the 'bspecs.json' file used to \n"
1063  " generate these clusters is reproduced here. \n\n"
1064 
1065  "\"lattice\": (JSON object) \n"
1066  " For reference, so that the Integral coordinates can be converted \n"
1067  " into Fractional or Cartesian coordinates, the lattice vectors \n"
1068  " of the primitive structure are reproduced here. \n\n" << std::endl;
1069  }
1070 
1071  if(vm.count("basis")) {
1072  args.log << "\n### basis.json ##################\n\n";
1073 
1074  args.log << "LOCATION:\n";
1075  args.log << "$ROOT/basis_sets/$CURR_BSET/basis.json\n";
1076  args.log << "\n\n";
1077 
1078  args.log << "DESCRIPTION:\n";
1079  args.log << "This JSON file contains the basis functions generated using the \n"
1080  "'bspecs.json' specifications. \n\n";
1081 
1082 
1083  args.log << "\"site_functions\": (JSON array of JSON object) \n"
1084  " Gives the site basis functions. One JSON object for each basis \n"
1085  " site. \n\n"
1086 
1087  " /\"sublat\": (int) \n"
1088  " Basis site index. \n\n"
1089 
1090  " /\"asym_unit\": (int) \n"
1091  " Index of the asymmetric unit this basis site belongs to. \n\n"
1092 
1093  " /\"basis\": (JSON object) \n"
1094  " Gives the value of each site basis function for each possible \n"
1095  " occupant. Of the form: \n\n"
1096  " { \n"
1097  " \"\\\\phi_b_i\": { \n"
1098  " \"A\": val, \n"
1099  " \"B\": val, \n"
1100  " ... \n"
1101  " }, \n"
1102  " ... \n"
1103  " } \n"
1104 
1105  "\"cluster_functions\": (JSON array of JSON object) \n"
1106  " Gives the cluster basis functions. One JSON object for each \n"
1107  " cluster basis function. \n\n"
1108 
1109  " /\"linear_function_index\": (int) \n"
1110  " Linear function index. This corresponds to ECI indices. \n\n"
1111 
1112  " /\"mult\": (int) \n"
1113  " Multiplicity of symmetrically equivalent cluter functions. \n\n"
1114 
1115  " /\"orbit\": (JSON array of 3 int) \n"
1116  " Gives the cluster branch index, cluster orbit index, and index\n"
1117  " of this basis function in the cluster basis. \n\n"
1118 
1119  " /\"prototype\": (JSON object) \n"
1120  " Specifies the prototype cluster, as in the 'clust.json' file. \n\n"
1121 
1122  " /\"prototype_function\": (string) \n"
1123  " Latex-style function for the prototype cluster. \n\n" << std::endl;
1124  }
1125 
1126  if(vm.count("clex")) {
1127  args.log << "\n### $TITLE_Clexulator.* ##################\n\n";
1128 
1129  args.log << "LOCATION:\n";
1130  args.log << "$ROOT/basis_sets/$CURR_BSET/$TITLE_Clexulator.*\n";
1131  args.log << "\n\n";
1132 
1133  args.log << "DESCRIPTION:\n";
1134  args.log << "$TITLE_Clexulator.cc contains C++ code generated by CASM for \n"
1135  "the cluster basis functions. It is automatically compiled into \n"
1136  "$TITLE_Clexulator.o and $TITLE_Clexulator.so for use by CASM. \n\n" << std::endl;
1137  }
1138 
1139  if(vm.count("ref")) {
1140  args.log << "\n### ref ##################\n\n";
1141 
1142  args.log << "LOCATION WHEN GENERATED:\n\n";
1143  args.log << "$ROOT/training_data/settings/$CURR_CALCTYPE/$CURR_REF/chemical_reference.json\n";
1144  args.log << "\n\n";
1145 
1146  args.log << "DESCRIPTION:\n";
1147  args.log << " The chemical reference determines the value of the formation energy \n"
1148  " and chemical potentials calculated by CASM. \n\n"
1149 
1150  " Chemical references states are set by specifying a hyperplane in \n"
1151  " energy/atom - composition (as atom_frac) space. This may be done by \n"
1152  " specifying the hyperplane explicitly, or by specifying several \n"
1153  " reference states with energy/atom and composition (as atom_frac) for \n"
1154  " enough states to span the composition space of the allowed occupants \n"
1155  " specified in the prim. For consistency with other CASM projects, \n"
1156  " additional reference states extending to other compositional \n"
1157  " dimensions may be included also. The pure Va reference is always 0. \n\n";
1158 
1159  args.log << " The reference states are stored in the 'chemical_reference.json' file\n"
1160  " in one of two formats: \n\n"
1161 
1162  " 1) Reference state composition and energy_per_species. \n"
1163  " In this format each reference state is represented by a JSON \n"
1164  " object storing the number of each species present in the reference\n"
1165  " state and the energy_per_species for that reference state. Species\n"
1166  " that are not in the primitive structure may also be included in \n"
1167  " the reference states as long as the composition space of the \n"
1168  " primitive structure is spanned by the hyperplane connecting the \n"
1169  " provided reference states. \n"
1170  R"( '[)" << "\n" <<
1171  R"( {"A": 3.4, "C": 2.0, "energy_per_species": 2.0},)" << "\n" <<
1172  R"( {"B": 2.0, "energy_per_species": 4.0}, )" << "\n" <<
1173  R"( {"C": 1.0, "energy_per_species": 3.0} )" << "\n" <<
1174  R"( ]')" << "\n\n" <<
1175 
1176  " 2) Input an array of energy_per_species, for each species in prim, \n"
1177  " including 0.0 for vacancy: \n"
1178  " '[X, X, X]' \n\n";
1179 
1180  args.log << " When using '--set' it is also possible to specialize the chemical \n"
1181  " reference at the supercell or configuration level by adding the \n"
1182  " --scelname or --configname option. \n\n";
1183 
1184 
1185  args.log << "EXAMPLE: chemical_reference.json\n";
1186  args.log << "-------\n";
1187  args.log <<
1188  R"({
1189 "chemical_reference" : {
1190 "config" : {
1191 "SCEL4_2_2_1_1_1_0 / 0" : [
1192 {
1193 "A" : 1.000000000000,
1194 "energy_per_species" : -1.500000000000
1195 },
1196 {
1197 "B" : 1.000000000000,
1198 "energy_per_species" : -2.000100000000
1199 },
1200 {
1201 "C" : 1.000000000000,
1202 "energy_per_species" : -8.030000000000
1203 }
1204 ],
1205 "SCEL4_2_2_1_1_1_0 / 2" : [ -1.520000000000, -2.000100000000, -8.030000000000 ]
1206 },
1207 "global" : [
1208 {
1209 "A" : 0.500000000000,
1210 "B" : 0.500000000000,
1211 "energy_per_species" : -1.500000000000
1212 },
1213 {
1214 "B" : 1.000000000000,
1215 "energy_per_species" : -2.000000000000
1216 },
1217 {
1218 "C" : 1.000000000000,
1219 "energy_per_species" : -8.000000000000
1220 },
1221 {
1222 "D" : 1.000000000000,
1223 "energy_per_species" : -4.000000000000
1224 }
1225 ],
1226 "species_order" : [ "A", "B", "C" ],
1227 "supercell" : {
1228 "SCEL3_1_3_1_1_0_0" : [
1229 {
1230 "A" : 1.000000000000,
1231 "energy_per_species" : -1.500000000000
1232 },
1233 {
1234 "B" : 1.000000000000,
1235 "energy_per_species" : -2.000000000000
1236 },
1237 {
1238 "C" : 1.000000000000,
1239 "energy_per_species" : -8.001000000000
1240 }
1241 ],
1242 "SCEL4_2_2_1_1_1_0" : [
1243 {
1244 "A" : 1.000000000000,
1245 "energy_per_species" : -1.500000000000
1246 },
1247 {
1248 "B" : 1.000000000000,
1249 "energy_per_species" : -2.000000000000
1250 },
1251 {
1252 "C" : 1.000000000000,
1253 "energy_per_species" : -8.030000000000
1254 }
1255 ]
1256 }
1257 }
1258 })";
1259  args.log << "-------\n";
1260 
1261  }
1262 
1263  if(vm.count("scel")) {
1264  args.log << "\n### scel ##################\n\n";
1265 
1266  args.log << "LOCATION WHEN GENERATED:\n";
1267  args.log << "$ROOT/training_data/SCEL\n\n\n";
1268 
1269  args.log << "DESCRIPTION:\n";
1270  args.log << "Contains a list of all the generated and imported supercells. Each \n" <<
1271  "entry gives the name of a supercell, its volume in number of \n" <<
1272  "primitive volumes, and the transformation matrix to go from the \n" <<
1273  "primitive cell to the supercell. The convention is \n" <<
1274  " LAT.scel = LAT.prim*transf_matrix, \n" <<
1275  "where the columns of the LAT matrices are the lattice vectors. \n\n\n";
1276 
1277  args.log << "EXAMPLE:\n";
1278  args.log << "-------\n";
1279  args.log <<
1280  "Supercell Name: 'SCEL1_1_1_1_0_0_0' Number: 0 Volume: 1\n\
1281 Supercell Transformation Matrix: \n\
1282 1 0 0\n\
1283 0 1 0\n\
1284 0 0 1\n\
1285 \n\
1286 Supercell Name: 'SCEL2_1_1_2_0_0_0' Number: 1 Volume: 2\n\
1287 Supercell Transformation Matrix: \n\
1288 1 0 -1\n\
1289 0 1 0\n\
1290 0 0 2\n\
1291 \n\
1292 Supercell Name: 'SCEL2_1_2_1_0_0_1' Number: 2 Volume: 2\n\
1293 Supercell Transformation Matrix: \n\
1294 1 -1 0\n\
1295 0 1 -1\n\
1296 0 1 1\n\
1297 ...\n";
1298  args.log << "-------\n";
1299  }
1300 
1301  if(vm.count("lat")) {
1302  args.log << "\n### lat ##################\n\n";
1303 
1304  args.log << "LOCATION WHEN GENERATED:\n";
1305  args.log << "$ROOT/training_data/$SCELNAME/LAT\n\n\n";
1306 
1307  args.log << "DESCRIPTION:\n";
1308  args.log << "Contains the lattice vectors of a particular supercell of your CASM \n" <<
1309  "project. The format is the same as the first lines in a standard \n" <<
1310  "vasp POSCAR file, excluding the title (scaling followed by the three\n" <<
1311  "lattice vectors as rows).\n\n\n";
1312 
1313  args.log << "EXAMPLE:\n";
1314  args.log << "-------\n";
1315  args.log <<
1316  " 1.00000000\n\
1317  10.52850134 0.00000000 0.00000000\n\
1318  0.00000000 10.52850134 0.00000000\n\
1319  0.00000000 0.00000000 10.52850134\n";
1320  args.log << "-------\n";
1321 
1322  }
1323 
1324  if(vm.count("pos")) {
1325  args.log << "\n### pos ##################\n\n";
1326 
1327  args.log << "LOCATION WHEN GENERATED:\n";
1328  args.log << "$ROOT/training_data/$SCELNAME/$CONFIGID/POS\n\n\n";
1329 
1330  args.log << "DESCRIPTION:\n";
1331  args.log << "This file is generated using the '--write-pos' option for 'casm run'.\n";
1332  args.log << "Decorated configuration for a particular supercell. It is a \n" <<
1333  "supercell of your primitive structure after the enumeration on the \n" <<
1334  "alloying sites. The format is standard vasp 5.x format, and the \n" <<
1335  "coordinates of the sites for the configuration are the ideal sites \n" <<
1336  "specified in the PRIM file.\n\n\n";
1337 
1338  args.log << "EXAMPLE:\n";
1339  args.log << "-------\n";
1340  args.log <<
1341  "SCEL3_1_1_3_0_0_0\n\
1342 1.00000000\n\
1343  0.00000000 1.75475022 1.75475022\n\
1344  1.75475022 0.00000000 1.75475022\n\
1345  3.50950045 3.50950045 -3.50950045\n\
1346 Al Ni\n\
1347 2 1\n\
1348 Direct\n\
1349  0.3333333 0.3333333 0.3333333\n\
1350  0.6666667 0.6666667 0.6666667\n\
1351  0.0000000 0.0000000 0.0000000\n\
1352 \n";
1353  args.log << "-------\n";
1354 
1355  }
1356 
1357  if(vm.count("eci")) {
1358  args.log << "\n### eci.json ##################\n\n";
1359 
1360  args.log << "LOCATION:\n";
1361  args.log << "$ROOT/cluster_expansions/clex.formation_energy/$CURR_BSET/$CURR_CALCTYPE/$CURR_REF/$CURR_ECI/eci.json\n";
1362  args.log << "\n\n";
1363 
1364  args.log << "DESCRIPTION:\n";
1365  args.log << "This is a copy of the $ROOT/basis_sets/$CURR_BSET/'basis.json' file \n"
1366  "with the following additions: \n\n"
1367 
1368  "\"cluster_functions\": (JSON array of JSON object) \n\n"
1369 
1370  " /\"eci\": (number, optional, default=0.0) \n"
1371  " The value of the ECI for the cluster basis function. If not \n"
1372  " given, use 0.0. \n\n"
1373 
1374  "\"fit\": (JSON object) \n"
1375  " Data from 'casm-learn' specifying how the ECI where generated and\n"
1376  " some goodness of fit measures. \n\n" << std::endl;
1377 
1378  }
1379 
1380  if(vm.count("monte")) {
1381  args.log << "\n### monte ##################\n\n";
1382 
1383  args.log << "LOCATION WHEN GENERATED:\n";
1384  args.log << " User determined\n\n\n";
1385 
1386  args.log << "DESCRIPTION:\n";
1387  args.log << " The Monte Carlo input file does not need to be in any particular \n" <<
1388  " location, as long as it is somewhere inside the CASM project \n" <<
1389  " directory or subdirectories. The input file contains a JSON \n" <<
1390  " object with \"ensemble\", \"method\", \"model\", \"supercell\", \n" <<
1391  " \"data\", and \"driver\" attributes, as described below. An \n" <<
1392  " optional attribute \"debug\" may also be included to print \n" <<
1393  " information that may be useful for debugging an input file. \n\n" <<
1394 
1395  "Input file parameters: \n\n" <<
1396 
1397  "\"ensemble\" (string): \n\n" <<
1398 
1399  " Possible options for \"ensemble\" are: \n\n" <<
1400 
1401  " \"GrandCanonical\" or \"grand_canonical\": Semi-grand canonical\n" <<
1402  " Monte Carlo calculation in which the total number of sites is \n" <<
1403  " fixed, but the occupants on each site may vary. One occupant \n" <<
1404  " change at a time is attempted. \n\n" <<
1405 
1406  " \"Canonical\" or \"canonical\": Canonical Monte Carlo \n" <<
1407  " calculation in which the total number of each type of occupant \n"
1408  " is fixed. Each Monte Carlo step attempts to swap a pair of \n"
1409  " occupants. \n\n\n" <<
1410 
1411 
1412  "\"method\" (string): \n\n" <<
1413 
1414  " Possible options for \"method\" are: \n\n" <<
1415 
1416  " \"Metropolis\" or \"metropolis\": Run Monte Carlo calculations \n" <<
1417  " using the Metropolis algorithm. \n\n" <<
1418 
1419  " \"LTE1\" or \"lte1\": Single spin flip low temperature \n" <<
1420  " expansion calculations. \n\n\n" <<
1421 
1422 
1423  "\"model\": (JSON object) \n\n" <<
1424 
1425  " /\"formation_energy\": (string, optional, default=\"formation_energy\")\n" <<
1426  " Specifies the cluster expansion to use to calculated formation \n"
1427  " energy. Should be one of the ones listed by 'casm settings -l'.\n\n\n" <<
1428 
1429 
1430  "\"supercell\": (3x3 JSON arrays of integers) \n" <<
1431  " The supercell transformation matrix. \n\n" <<
1432 
1433 
1434  "\"data\": (JSON object) \n\n" <<
1435 
1436  " /\"sample_by\": (string) \n" <<
1437  " Specify unit for the period between samples. May be either \n" <<
1438  " \"step\" (sample after every \"sample_period\" proposed Monte \n" <<
1439  " Carlo events), or \"pass\" (sample after the \"sample_period\" \n" <<
1440  " number of passes), where 1 pass is a number of steps equal to \n" <<
1441  " the number of sites in the supercell that have variable \n" <<
1442  " occupation). \n\n" <<
1443 
1444  " /\"sample_period\": (integer) \n" <<
1445  " Specify how many steps or passes to wait between data samples. \n\n" <<
1446 
1447  " /\"measurements\": (JSON array containing JSON objects) \n" <<
1448  " Specifies which properties to sample. Each JSON object should \n" <<
1449  " include \"quantity\" (string) specifying a property to be \n" <<
1450  " sampled. Optionally, it may also include \"precision\" (number),\n" <<
1451  " indicating the required (absolute) precision in the average of \n" <<
1452  " the quantity for the calculation to be considered converged. If\n" <<
1453  " a precision is given for any quantity, then the Monte Carlo \n" <<
1454  " calculations run in automatic convergence mode and continue \n" <<
1455  " until all quantities with a specified precision are converged \n" <<
1456  " to level requested. \n\n" <<
1457 
1458  " Possible options for \"quantity\" are: \n" <<
1459  " \"comp\": composition, relative the composition axes \n" <<
1460  " \"comp_n\": composition, number of atoms per unit cell \n" <<
1461  " \"site_frac\": composition, normalized per basis site \n" <<
1462  " \"atom_frac\": composition, normalized per total number of atoms\n" <<
1463  " \"formation_energy\": formation energy (per unit cell) \n" <<
1464  " \"potential_energy\": potential energy (per unit cell), \n" <<
1465  " (= formation_energy - sum_i(mu_i*comp_i)) \n" <<
1466  " \"non_zero_eci_correlations\": correlations (per unit cell) \n" <<
1467  " which have non-zero eci values. \n" <<
1468  " \"all_correlations\": correlations (per unit cell) \n" <<
1469  " \"<anything else>\": is interpreted as a 'casm query' query \n\n" <<
1470 
1471  " /\"confidence\": (number, range (0.0, 1.0), default 0.95) \n" <<
1472  " The confidence level used for calculating the precision in the \n" <<
1473  " average value of sampled quantities. \n\n" <<
1474 
1475  " /\"min_pass\", /\"min_step\", /\"min_sample\": (integer) \n" <<
1476  " If in automatic convergence mode, prevents the calculation from\n" <<
1477  " a minimum number of passes, steps, or samples have occurred. \n\n" <<
1478 
1479  " /\"max_pass\", /\"max_step\", /\"max_sample\": (integer) \n" <<
1480  " If in automatic convergence mode, stops the calculation if the \n" <<
1481  " specified number of passes, steps, or samples have occurred. \n\n" <<
1482 
1483  " /\"N_pass\", /\"N_step\", /\"N_sample\": (integer) \n" <<
1484  " When not in automatic convergence mode (no precision has been \n" <<
1485  " specified for any quantities being sampled), stops the \n" <<
1486  " calculation when the specified number of passes, steps, or \n" <<
1487  " samples have occurred. \n\n" <<
1488 
1489  " /\"equilibration_passes_first_run\": (integer) \n" <<
1490  " If included, the requested number of passes will be performed \n" <<
1491  " at the initial conditions as a preliminary step before the \n" <<
1492  " actual run begins. This may be useful when not running in \n" <<
1493  " automatic convergence mode. \n\n" <<
1494 
1495  " /\"equilibration_passes_each_run\": (integer) \n" <<
1496  " If included, the requested number of passes will be performed \n" <<
1497  " at each condition as a preliminary step before the actual run \n" <<
1498  " begins. This may be useful when not running in automatic \n" <<
1499  " convergence mode. \n\n" <<
1500 
1501  " /\"storage\": (JSON object) Options for writing results. \n\n" <<
1502 
1503  " /\"output_format\": (string or JSON array of string) \n" <<
1504  " Specifies the type or types of output files. Current options \n" <<
1505  " are \"csv\" or \"json\". Type names with either all lower \n" <<
1506  " case or all upper case are accepted. \n\n" <<
1507 
1508  " /\"write_observations\": (boolean, default false) \n" <<
1509  " If true, all individual observations of the quantities \n" <<
1510  " requested to be sampled will be written to compressed files: \n" <<
1511  " \"output_directory\"/conditions.i/observations.ext.gz \n" <<
1512  " where 'i' is the condition index and 'ext' is the output \n" <<
1513  " format. \n\n" <<
1514 
1515  " /\"write_trajectory\": (boolean, default false) \n" <<
1516  " If true, the value of all degrees of freedom at the time of \n" <<
1517  " each sample will be written to compressed files: \n" <<
1518  " \"output_directory\"/conditions.i/trajectory.ext.gz \n" <<
1519  " where 'i' is the condition index and 'ext' is the output \n" <<
1520  " format. \n\n" <<
1521 
1522  " /\"enumeration\": (JSON object, optional) \n" <<
1523  " If included, save configurations encountered during Monte \n" <<
1524  " Carlo calculations by keeping a 'hall of fame' of best scoring \n" <<
1525  " configurations. After the calculation at a particular set of \n" <<
1526  " thermodynamic conditions completes, the configurations in the \n" <<
1527  " hall of fame are saved to the project configuration list. \n\n" <<
1528 
1529  " /\"check\": (string, default=\"eq(1,1)\") \n" <<
1530  " A 'casm query'-like string that returns a boolean value \n" <<
1531  " indicating if (true) a configuration should be considered for\n" <<
1532  " for the enumeration hall of fame. The default always returns \n" <<
1533  " true. \n\n" <<
1534 
1535  " /\"metric\": (string, default=\"clex_hull_dist(ALL)\") \n" <<
1536  " A 'casm query'-like string that provides a metric for ranking\n" <<
1537  " ranking configurations as they are encountered during a Monte\n" <<
1538  " Carlo calculation. The resulting value is used to create a \n" <<
1539  " hall of fame of 'best' configurations encountered during the \n" <<
1540  " calculation. When the calculation is complete configurations \n" <<
1541  " in the hall of fame are added to the CASM project config \n" <<
1542  " list. The 'casm query'-like command should evaluate to a \n" <<
1543  " number. \n\n" <<
1544 
1545  " Besides the properties listed via 'casm query -h properties',\n" <<
1546  " and 'casm query -h operators', both \"check\" and \"metric\" \n" <<
1547  " can also use the property \"potential_energy\". \n\n" <<
1548 
1549  " /\"sample_mode\": (string, optional, default=\"on_sample\") \n" <<
1550  " Indicate when to attempt to insert configurations into the \n" <<
1551  " enumeration hall of fame. Options are: \n" <<
1552  " \"on_accept\": after each accepted Monte Carlo event \n" <<
1553  " \"on_sample\": after each data sample \n\n" <<
1554 
1555  " /\"check_existence\": (bool, optional, default=true) \n" <<
1556  " If true, only configurations that do not already exist in the\n" <<
1557  " config list are inserted into the enumeration hall of fame. \n\n" <<
1558 
1559  " /\"insert_canonical\": (bool, optional, default=true) \n" <<
1560  " If true, configurations are inserted into the enumeration \n" <<
1561  " hall of fame in their canonical form. If 'check_existence' is\n" <<
1562  " true, this must be set to true. \n\n" <<
1563 
1564  " /\"N_halloffame\": (integer, optional, default=100) \n" <<
1565  " The number of configurations that are allowed in the \n" <<
1566  " enumeration hall of fame. \n\n" <<
1567 
1568  " /\"tolerance\": (number, optional, default=1e-8) \n" <<
1569  " Tolerance used for floating point comparison of configuration\n" <<
1570  " scores in the enumeration hall of fame. \n\n\n" <<
1571 
1572 
1573  "\"driver\": (JSON object) \n\n" <<
1574 
1575  " /\"motif\": (JSON object) \n" <<
1576  " Specifies the initial occupation of the supercell. \n\n" <<
1577 
1578  " For canonical ensemble Monte Carlo calculations an additional\n" <<
1579  " step changes the occupants on random sites to make the actual\n" <<
1580  " composition as close as possible to the requested composition.\n\n" <<
1581 
1582  " /\"configname\": (string, optional) \n" <<
1583  " A configuration name, \"auto\", \"restricted_auto\", or \n" <<
1584  " \"default\". \n\n" <<
1585 
1586  " Specifies the configuration that is tiled to fill the \n" <<
1587  " supercell. If necessary, symmetry operations may be applied \n" <<
1588  " An error is thrown if the specified configuration can not be \n" <<
1589  " used to fill the \"supercell\". \n\n" <<
1590 
1591  " Possible options for \"configname\" are: \n" <<
1592  " A configuration name (ex. \"SCEL3_3_1_1_0_2_2/0\") \n" <<
1593  " \"auto\": (\"grand_canonical\" ensemble only) Enumerated \n" <<
1594  " configurations will be searched for the configuration with \n" <<
1595  " the lowest potential energy to use as the motif. \n" <<
1596  " \"default\": If the value \"default\" is used, the initial \n" <<
1597  " motif occupation is determined from the occupation order in\n" <<
1598  " the PRIM. \n" <<
1599  " \"restricted_auto\": (\"grand_canonical\" ensemble only) \n" <<
1600  " Same as \"auto\", but only configurations that can tile the\n" <<
1601  " supercell are considered. As a last resort, \"default\" is \n" <<
1602  " used. \n\n" <<
1603 
1604  " /\"configdof\": (string, optional) \n" <<
1605  " Specifies the path to a configdof JSON file, such as \n" <<
1606  " \"initial_state.json\" or \"final_state.json\", containing \n" <<
1607  " the degrees of freedom to initialize the supercell with \n\n" <<
1608 
1609  " /\"mode\": (string) \n" <<
1610  " Specify the drive mode. \n\n" <<
1611 
1612  " Possible options for \"mode\" are: \n" <<
1613  " \"incremental\": perform one or more calculations, starting \n" <<
1614  " at the initial conditions and incrementing by the \n" <<
1615  " incremental conditions up to (and including) the final \n" <<
1616  " conditions. \n\n" <<
1617  " \"custom\": perform one or more calculations, as specified by\n" <<
1618  " the \"custom_conditions\". \n\n" <<
1619 
1620  " /\"dependent_runs\": (boolean, default true) \n\n" <<
1621 
1622  " If true, begin the next calculation with the final DoF from the\n" <<
1623  " previous calculation. If false, begin each calculation with the\n" <<
1624  " DoF specified for the \"motif\".\n\n" <<
1625 
1626 
1627  " /\"initial_conditions\",\n" <<
1628  " /\"incremental_conditions\", \n" <<
1629  " /\"final_conditions\": (JSON object, optional) \n" <<
1630  " Specifies the applied conditions for the calculation. For \n" <<
1631  " \"incremental_conditions\", specifies the change in conditions \n" <<
1632  " between individual calculations. Each JSON object should \n" <<
1633  " include: \n\n" <<
1634 
1635  " /\"temperature\": (number) \n" <<
1636  " The temperature in K. \n\n" <<
1637 
1638  " /\"param_chem_pot\" (JSON object, \"grand_canonical\" ensemble only)\n" <<
1639  " The parametric chemical potential(s) \n\n" <<
1640 
1641  " /\"a\", /\"b\", ...: (number) \n" <<
1642  " The parametric chemical potentials conjugate to the parametric\n" <<
1643  " compositions. The number of parametric chemical potentials \n" <<
1644  " provided must match the number of independent compositions. \n\n" <<
1645 
1646  " /\"comp\" (JSON object, \"canonical\" ensemble only, option 1)\n" <<
1647  " The parametric composition(s) \n\n" <<
1648 
1649  " /\"a\", /\"b\", ...: (number) \n" <<
1650  " The parametric composition. The number of entries provided \n" <<
1651  " must match the number of independent compositions. \n\n" <<
1652 
1653  " /\"comp\" (JSON array, \"canonical\" ensemble only, option 2)\n" <<
1654  " The parametric composition(s) \n\n" <<
1655 
1656  " [number, ...] \n" <<
1657  " An array containing the parametric composition. The number of \n" <<
1658  " entries provided must match the number of independent \n" <<
1659  " compositions. \n\n" <<
1660 
1661  " /\"comp_n\" (JSON object, \"canonical\" ensemble only, option 3)\n" <<
1662  " The mol composition per unitcell \n\n" <<
1663 
1664  " /\"A\", /\"B\", ...: (number) \n" <<
1665  " The mol composition per unitcell. The entries provided must \n" <<
1666  " match occupant names in the 'prim.json' file. The values are \n" <<
1667  " summed, normalized, and then converted to parametric composition.\n\n" <<
1668 
1669  " /\"comp_n\" (JSON array, \"canonical\" ensemble only, option 4)\n" <<
1670  " The mol composition per unitcell \n\n" <<
1671 
1672  " [number, ...] \n" <<
1673  " An array containing the mol composition per unitcell. The \n" <<
1674  " number of entries provided must match the number components. \n" <<
1675  " The values are summed, normalized, and converted to parametric\n" <<
1676  " composition. \n\n" <<
1677 
1678  " /\"tolerance\": (number) \n" <<
1679  " Specifies a numerical tolerance for comparing conditions. \n\n" <<
1680 
1681  " /\"custom_conditions\":\n" <<
1682  " (JSON array of JSON objects) An array specifying a custom \n" <<
1683  " path of conditions. \n\n" <<
1684 
1685  " Restarts: Metropolis Monte Carlo calculations that are stopped \n" <<
1686  " before the entire path has been calculated can be restarted as \n" <<
1687  " long as the conditions of the existing calculations agree with \n" <<
1688  " the conditions specified in the input settings. This means that \n" <<
1689  " the \"final_conditions\" might be changed to increase the length \n" <<
1690  " of a path, or additional \"custom_conditions\" might be added, \n" <<
1691  " but the \"incremental_conditions\" may not be changed. Upon \n" <<
1692  " restart, the results summary file is checked for the last \n" <<
1693  " finished conditions. Then the path is resumed from the next set \n" <<
1694  " of conditions. It is the responsibility of the user to ensure \n" <<
1695  " that other important settings, such as the \"model\" are not \n" <<
1696  " changed inappropriately. \n\n\n" <<
1697 
1698 
1699  "\"debug\" (bool, default false): \n\n" <<
1700 
1701  " If true, will print as much information as possible to assist in \n" <<
1702  " debugging input file settings. \n\n\n";
1703 
1704 
1705  args.log << "EXAMPLE: Settings for an incremental Metropolis calculation \n" <<
1706  "with increasing temperature in automatic convergence mode.\n";
1707  args.log << "-------\n";
1708  args.log << "{\n \"comment\" : \"This is a sample input file. Unrecognized attributes (like the ones prepended with '_' are ignored.\",\n \"debug\" : false,\n \"ensemble\" : \"grand_canonical\",\n \"method\" : \"metropolis\",\n \"model\" : {\n \"formation_energy\" : \"formation_energy\"\n },\n \"supercell\" : [\n [10, 0, 0],\n [0, 10, 0],\n [0, 0, 10]\n ],\n \"data\" : {\n \"sample_by\" : \"pass\",\n \"sample_period\" : 1,\n \"_N_sample\" : 1000, \n \"_N_pass\" : 1000,\n \"_N_step\" : 1000,\n \"_max_pass\" : 10000,\n \"min_pass\" : 1000,\n \"_max_step\" : 10000,\n \"_max_sample\" : 500,\n \"_min_sample\" : 100,\n \"confidence\" : 0.95,\n \"measurements\" : [ \n { \n \"quantity\" : \"formation_energy\"\n },\n { \n \"quantity\" : \"potential_energy\"\n },\n { \n \"quantity\" : \"atom_frac\"\n },\n { \n \"quantity\" : \"site_frac\"\n },\n { \n \"quantity\" : \"comp\",\n \"precision\" : 1e-3\n },\n { \n \"quantity\" : \"comp_n\"\n }\n ],\n \"storage\" : {\n \"write_observations\" : false,\n \"write_trajectory\" : false,\n \"output_format\" : [\"csv\", \"json\"]\n }\n },\n \"driver\" : {\n \"mode\" : \"incremental\", \n \"motif\" : {\n \"configname\" : \"auto\",\n \"_configname\" : \"SCEL3_3_1_1_0_2_2/0\",\n \"_configdof\" : \"path/to/final_state.json\"\n },\n \"initial_conditions\" : {\n \"param_chem_pot\" : {\n \"a\" : -1.75\n },\n \"temperature\" : 100.0,\n \"tolerance\" : 0.001\n },\n \"final_conditions\" : {\n \"param_chem_pot\" : {\n \"a\" : -1.75\n },\n \"temperature\" : 1000.0,\n \"tolerance\" : 0.001\n },\n \"incremental_conditions\" : {\n \"param_chem_pot\" : {\n \"a\" : 0.0\n },\n \"temperature\" : 10.0,\n \"tolerance\" : 0.001\n }\n }\n}\n";
1709  args.log << "-------\n\n";
1710 
1711  args.log << "EXAMPLE: Settings for an custom drive mode LTE1 calculation with\n" <<
1712  "increasing temperature.\n";
1713  args.log << "-------\n";
1714  args.log << "{\n \"comment\" : \"This is a sample input file. Unrecognized attributes (like the ones prepended with '_' are ignored.\",\n \"debug\" : false,\n \"ensemble\" : \"grand_canonical\",\n \"method\" : \"lte1\",\n \"model\" : {\n \"formation_energy\" : \"formation_energy\"\n },\n \"supercell\" : [\n [9, 0, 0],\n [0, 9, 0],\n [0, 0, 9]\n ],\n \"data\" : {\n \"storage\" : {\n \"write_observations\" : false,\n \"write_trajectory\" : false,\n \"output_format\" : [\"csv\", \"json\"]\n }\n },\n \"driver\" : {\n \"mode\" : \"incremental\", \n \"motif\" : {\n \"configname\" : \"auto\",\n \"_configname\" : \"SCEL3_3_1_1_0_2_2/0\",\n \"_configdof\" : \"path/to/final_state.json\"\n },\n \"custom_conditions\" : [\n {\n \"param_chem_pot\" : {\n \"a\" : 0.0\n },\n \"temperature\" : 100.0,\n \"tolerance\" : 0.001\n },\n {\n \"param_chem_pot\" : {\n \"a\" : 0.0\n },\n \"temperature\" : 200.0,\n \"tolerance\" : 0.001\n },\n {\n \"param_chem_pot\" : {\n \"a\" : 0.0\n },\n \"temperature\" : 400.0,\n \"tolerance\" : 0.001\n },\n {\n \"param_chem_pot\" : {\n \"a\" : 0.0\n },\n \"temperature\" : 800.0,\n \"tolerance\" : 0.001\n }\n ]\n }\n}\n";
1715  args.log << "-------\n";
1716 
1717  }
1718 
1719  return 0;
1720  }
1721 
1722 }
CASM::CommandArgs
Data structure holding basic CASM command info.
Definition: casm_functions.hh:70
CASM::Completer::OptionHandlerBase::add_help_suboption
void add_help_suboption()
Add a plain –help suboption.
Definition: Handlers.cc:276
CASM::Completer::FormatOption::initialize
void initialize() override
Fill in the options descriptions accordingly.
Definition: format.cc:13
CASM
Main CASM namespace.
Definition: complete.cpp:8
CASM::Completer::OptionHandlerBase::desc
const po::options_description & desc()
Get the program options, filled with the initialized values.
Definition: Handlers.cc:160
CASM_global_definitions.hh
Handlers.hh
CASM::Completer::OptionHandlerBase::m_desc
po::options_description m_desc
Boost program options. All the derived classes have them, but will fill them up themselves.
Definition: Handlers.hh:126
casm_functions.hh
CASM::format_command
int format_command(const CommandArgs &args)
Definition: format.cc:44