SUPERCELL(1)

📦 version 2.1.1+~0.0~git20221028.d8eeb73, in ubuntu stonking

✨ hey bestie, welcome to supercell(1) ✨

You're in the Scientific Tools part of the manual, and this is the page about supercell. Buckle in, it's a long one (we're splitting it into parts, so don't worry, more is coming 💖).

🌸 NAME 🌸

supercell is a tool that takes a crystallographic structure with partial occupancy and/or vacancies and converts it into a normal, ordinary supercell structure that's actually suitable for calculations. That's the whole vibe. 🦋

✨ SYNOPSIS ✨

 supercell
       -h, --help

 supercell
       [OPTIONS] -i input-file

 supercell
       [OPTIONS] --input=input-file

💅 DESCRIPTION 💅

Okay so, disordered compounds are super important right now, both for fundamental science and for industrial applications. The problem? Most methods for exploring solid state material properties need ideal periodicity. 😭

And the way lots of reported research handles this is by just... implying periodicity into disordered systems ``by hand'' and ad-hoc. Not it. The program supercell lets you apply that approximation systematically, because it has all-in-one algorithms implemented for:

  • structure manipulation
  • supercell generation
  • permutations of atoms and vacancies
  • charge-balancing
  • detecting symmetry equivalent structures
  • Coulomb energy calculations
  • sampling output data

The advantages of the program are fast-algorithms implementation and availability under GPL license. 👑

🎀 OPTIONS 🎀

  • [-h], [--help] — Prints the help message and exits the program. That's it, that's the option.
  • [-v level], [--verbose=level] — Changes the verbosity level from the default 1.
    • Level 0 — quiet mode, only error output.
    • Level 1 is suggested for regular users.
    • Higher levels are suggested for developers, bug tracking and long program execution times.
  • -i input-file, --input=input-file — Required option. Input file in CIF format. Only one file can be specified.
  • [-d], [--dry-run] — This option is highly recommended for the first run of the program with new input specified. 💯 With the option the program will do everything except write the files. Be careful if you switched -m, --merge-symmetric option: the program will go through all crystal structures, so even the dry-run mode can take time.
  • [-s cell-size], [--cell-size=cell-size] — Specifies the size of the supercell. The format is AxBxC, where A, B, C are positive integer multipliers of a, b and c unit cell vectors of the input system. Default is "1x1x1".
  • [-c balance-type], [--charge-balance=balance-type] — This option helps balance charges of the structure. ⚡ Be careful: charge balancing with wrong input charges will make the output system composition far from desired, or it can even freeze the program. 😭 Charges (i.e. oxydation states) may be specified with the -p, --labels-properties option (see below) or directly in the CIF file ("_atom_type_oxidation_number"). The possible arguments are:
    • no — No charge balancing. The option will set all charges to zero.
    • try — Default. Try to charge balance system, if initial system is not charged.
    • yes — Charge balance the system.
  • [-p labels-properties], [--property=labels-properties] — This one lets you manually specify some properties of atoms with specific labels. Your custom era. You may use the simple or the extended syntax:
    • Simple: <label>:<property_name>[=<property_value>].
    • Extended: "<OPT>(<labels>):{<properties>}" (do not forget to put extended syntax in quotes!).

where <label> is the label of the crystallographic site whose properties you want to change. <labels> is a set of space-separated labels. <OPT> is the type of string processing which is used to set the labels. The possible values of <OPT> are:

  • p — Treat the labels in parenthesis like a plain string.
  • w, "" — Default for simple syntax. Treat the labels in parenthesis like a wild card. For example, N* means all labels starting with N: N1, N12, but also Na3. You can use *'' (any numbers of any symbol) and ?'' (any symbol: exactly one).
  • r — Treat the labels in parenthesis like a Perl Regex. Syntax description can be found at http://en.wikipedia.org/wiki/Regular_expression.

The <property_name> is the name of the property you want to set for all specified crystallographic sites. Some properties can have values, which should be set by using an equal symbol. The properties can be:

  • c[harge] — Set the charge of atoms with specified label(s). Floating-point value in elementary charge units.
  • p[opulation] — Number of atoms with specific label(s) in output supercell structure.
  • [not]fixed — Exclude crystallographic sites from the combinatorial analysis. The output supercell file will contain partial occupancies for the corresponding sites (if there were partial occupancies in the original structures).

Some fancy examples can be found below. 👇

  • [-t tolerance], [--tolerance=tolerance] — The argument specifies the maximum distance (in Angstroms) between sites that should be contained within the same group (meaning that the corresponding positions in the supercell cannot be occupied simultaneously). Check carefully the minimal distance between 2 atoms assigned to different groups, which is written in the output of supercell before changing this parameter. Default tolerance=0.75 A.
  • [-m], [--merge-symmetric] — Enables the symmetry check algorithm on output structures. Structures that can be transformed to each other using crystallographic symmetry operations will be merged and stored as one structure. For cases with more than 10^4 total combinations it is recommended to use verbosity level 2 or higher to trace program execution. 🔍
  • [-n selection], [--store-structures=selection] — Lets you generate subsets of structures (rather than all of them) according to certain criteria (listed below). Super useful to both save disk space and facilitate navigation among files for large numbers of combinations (typically more than 10^5). The argument has the special structure <sampling type><count>. The <count> is a positive integer value or zero. <sampling type> is a letter which sets the sampling (selection) mode:
    • r : select <count> random structures.
    • f : select <count> first structures.
    • a : select <count> last structures.
    • l : select <count> low energy structures (--coulomb-energy option required).
    • h : select <count> high energy structures (--coulomb-energy option required).

Example: l100 will store first 100 structures with low Coulomb energy.

Another extra option available to find symmetric structures:

  • w : selects all structures with multiplicity (weight) less or equal <multiplicity>.

Example: w32 will store all structures with multiplicity, for example 32, 24, 16, 8, 1, but skip structures with multiplicity 48.

Multiple declaration of the option is allowed. If the option is enabled, an extra prefix (the letter <sampling type>) will be added to the output file name. ⚠️ Be careful, enabling the option requires extra memory, proportionally to the number of structures to store. This is specially important for the ``w'' option.

  • [-q], [--coulomb-energy] — Enables Coulomb energy calculations. The result energies for each structure are stored in file <output-prefix>_coulomb_energy.txt. The energies can help to consider the relevant regular structures for following calculations. Ewald summation algorithm is used for the calculations. ⚠️ Be careful, in case of charged cell the energy values can be meanless. See also --charge-balance option.
  • [-g], [--coulomb-store] — Use this option to create a file with electrostatic energy for all processed structures.
  • [-o output-prefix], [--output-prefix=output-prefix] — Specifies the output file name prefix. The prefix can contain a folder name, but the folder should be created before you run the program. For example, --output-prefix=myfolder/myfiles. The output files will be created according to templates:
    • For a non merging run the template will be <output-prefix>_i<sampling type><index>.cif.
    • For a merging run the template will be <output-prefix>_i<sampling type><index>_w<weight>.cif, where <weight> is the number of structures merged into the structure.

⚠️ Be careful, all existing files with mask "<output-prefix>*.cif" will be deleted during a non dry-run. The <output-prefix>_coulomb_energy.txt file will be overwritten only in case of --coulomb-energy option enabled. 💀

  • [--random-seed=number] — Specifies a random seed for structures random sampling. 🎲
  • [-a archive-file], [--archive=archive-file] — Specifies a target archive file name for the output files, except the energy file for all permuted configurations. If archive-file string is empty (default) no packing will be performed and all files will be stored directly to disk. If the file with the already name exists it will be overwritten. This optional feature requires libarchive http://www.libarchive.org/ to be available in the system. Otherwise the option will be disabled — check the status by the -h option. The extension of the file should be set according to the desired archive type: .zip'', .tar'', .tgz'', .tar.gz'', .tar.bz2'', .tar.xz''.

🌈 FILES 🌈

(empty section — that's literally how it is in the page, bestie. no notes. 💅)

👑 EXAMPLES 👑

The examples are based on file supercell/data/examples/Ca2Al2SiO7. 🍓

  • Dry run. Obtain information about the structure: group assignment, cell size, etc. It is a good practice to start a new structure processing with this command. This run doesn't produce any output files.
supercell -d -i Ca2Al2SiO7.cif
  • Dry run. Obtain information about the structure.
supercell -d -i Ca2Al2SiO7.cif -s 1x1x2
  • Dry run. Obtain information about the structure.
supercell -d -i Ca2Al2SiO7.cif -s 1x1x2

(yes, that last one is literally twins with the one right above it 🫶 — the page has it twice, so we keep it twice.)

Some advanced examples, with supercell embedded into bash scripts, you can find in the supercell/data/examples folder. 🧚

✨ REQUIREMENTS ✨

Okay bestie, real talk: the compiled version of supercell from https://orex.github.io/supercell is a standalone program for both Linux and MacOS systems. It requires neither installation nor third-party libraries to install. That's the whole vibe. If you wanna compile it yourself, please check the supercell/INSTALL file. 💅

💀 BUGS AND LIMITATIONS 💀

🔢 Supercell size limitation.

The maximum number of permutations should not exceed the limit of 10^{16}. If it's more, the program will return an error. That value is far beyond a reasonable limit due to calculation time. The average program performance is about 10^{12}--10^{13} structures per day with an average workstation. Like, she works hard, but she's not a miracle worker. 😭

📁 Filesystem limitation.

Although supercell can produce millions of files, most filesystems can't manage more than one thousand files in one folder with acceptable performance. Be careful if you need to process a lot of combinations: sample them or use the -a option. No cap, your folder will be giving chaos otherwise. 🫶

🧬 Symmetry information handling in input file.

Be careful with low symmetric structures. For example, in monoclinic cells structures often have an inconsistency between symmetry operations, atoms positions and unit cell configuration. The supercell program does the best to solve the problems, but it is always a good idea to verify the CIF file with external tools like enCIFer. The problem can be fully solved by converting the input file to a P1 structure (see non-diagonal supercell expansion). ✨

🌀 Non-diagonal supercell expansion.

The program has its own general algorithm for symmetry search. Input structures are converted internally to P1 structures, and builtin algorithms search for symmetry in P1 structures. It gives a huge freedom for the user, manipulating the input structure. For example, although supercell cannot generate non-diagonal supercells directly, it can use such cells, generated with other software. You need to generate any cell and store it as a P1 cell. supercell is fully compatible with VESTA (highly recommended to use) output CIF files, but it is not compatible with Material studio output for example. So yeah, VESTA stans rise. 🌈

🏷️ VERSION 🏷️

Version: 2.0 of 2019/05/23.

📜 VERSION HISTORY 📜

Version 2.0 (20-05-2021)

A new major release of the program. A performance increase of almost all algorithms: enumerating(x4-x10), electrostatic calculation (x2-x5), symmetry search (x2). Shared memory multithreading in during enumerating of structures. Better support of CIF input files. New command line options: -n w, --random-seed, (see above). OpenBabel dependency removed. The code is upgraded to C++14 standard. She ate and left no crumbs. 👑

Version 1.2 (23-05-2019)

Four times performance increase. Periodt. 🔥

Version 1.1 (24-01-2019)

The version of supercell program can process up to 10^{16} total structures. The value is far beyond a reasonable limit due to calculation time. The average program performance is about 10-100 billion structures per day with standard desktop processor. Iconic behavior. 💖

Version 1.0 (31-03-2016)

Initial release. The origin story. 🎀

All rights to the program belong to authors.

License

This program can be redistributed and/or modified under the terms of the GNU GENERAL PUBLIC LICENSE Version 2.

Misc

The actual version of supercell may be found on my homepage https://orex.github.io/supercell. Please, use github site https://github.com/orex/supercell to download the source code and submit a bug of the program. Iykyk, GitHub is the place. 🦋

👑 AUTHOR 👑

Kirill Okhotnikov e-mail: kirill.okhotnikov@gmail.com

Dr. Sylvian Cadars e-mail: sylvian.cadars@cnrs-imn.fr Institut des Materiaux Jean Rouxel (IMN) - UMR6502 2 rue de la Houssiniere, BP32229 44322 Nantes cdx3, France Tel: +33 (0)2 40 37 39 34 Fax: +33 (0)2 40 37 39 95

This lil masterpiece is from Scientific Tools, dated 2019/05/23, and it's literally the manual for SUPERCELL(1). Slay, bye bestie. 💅✨

📦 where this page comes from