CIF_MOLECULE(1)

📦
version 3.12.0 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 CIF_MOLECULE 💖

okay so bestie, welcome to cif_molecule from the General Commands Manual — this is the girl who restores molecules from a CIF file and she is SO good at her job. no cap. let's get into it 🧚✨

✨ NAME ✨

cif_molecule — restore molecules from a CIF file. that's it, that's the whole vibe 🫶

🌸 SYNOPSIS 🌸

cif_molecule --options input1.cif input*.cif

like. you hand her some CIFs, she gives you molecules back. iconic behaviour honestly 💅

🦋 DESCRIPTION 🦋

Restore molecules from a CIF file. literally the whole point. she takes your crystallographic info and rebuilds the actual molecules out of it. main character energy fr fr.

👑 OPTIONS 👑

okay this is the long part, stay with me bestie, every single one is here, no skips, we don't do that 🙈

  • --use-optimised-spacegroup-builder — use the space group builder algorithm that's been optimised for speed, as implemented in the COD::Spacegroups::Builder module. this one is the default ✨
  • --use-simple-spacegroup-builder — use the simpler and slower space group builder algorithm, as implemented in the COD::Spacegroups::SimpleBuilder module. slower but cuter, whatever 💜
  • -1, --one-datablock-output — output all moieties into a single output data block.
okay but heads up: if --split-disorder-groups is enabled, all the generated alternative conformations get put into separate data blocks — starting with the most likely one (disorder group occupancy wise) and ending with the least likely one. so if you only want the most likely one, you gotta pair --largest-molecule-only with --one-datablock-output. iykyk 🌸
  • -1-, --multiple-datablocks-output — separate each molecule and each example of an alternative conformation into its own separate data block. default 💫
  • -c, --covalent-sensitivity — set a new covalent sensitivity value. Default: 0.35.

this value is the tolerance parameter when she's evaluating if a chemical bond exists between two atoms. atoms a_1 and a_2 are considered bonded if:

dist(a_1, a_2) < r_cov(a_1) + r_cov(a_2) + tolerance

math but make it bonding 🎀

  • -g, --geom-bond-output — output _geom_bond_... data items (bond lengths, valencies, etc.). the receipts, basically 💅
  • -g-, --no-geom-bond-output — do not output _geom_bond_... information. default.
  • -h, --add-cif-header input_header.txt — prepend comments from the beginning of the given file to the output. little header moment 🌈
  • -i, --ignore-bumps — detect and warn about close atom "bumps" but do not stop processing. she'll tell you, but she won't block you 🫶
  • --no-ignore-bumps, --dont-ignore-bumps — stop processing immediately if bumps are detected. default.
  • -s, --sort-molecules — sort molecules in descending order by their atom count and overall occupancy before outputting them. atom count takes precedence over overall occupancy. default. order, bestie, we love order ✨
  • --no-sort-molecules, --dont-sort-molecules — do not sort molecules, print them out in the order they are detected. chaos mode, respect 🦋
  • --expand-to-P1, --P1-expand, --p1-expand — expand all atoms to the P1 unit cell, so that the translation operations can be used to restore the whole crystal. she's expanding, she's growing, she's thriving 💖
  • --no-expand-to-P1, --no-P1-expand, --no-p1-expand, --dont-expand-to-P1, --dont-P1-expand — do not expand to P1, output only the minimal molecule list. default.
  • --uniquify-atoms — make atom labels unique. default. ✨
  • --no-uniquify-atoms, --dont-uniquify-atoms — do not make atom labels unique, exclude duplicates.
  • --use-morgan-fingerprints — use Morgan fingerprints to identify and skip duplicated moieties. fancy chemistry detective work 🔥
  • --no-use-morgan-fingerprints, --dont-use-morgan-fingerprints — use atom labels to identify and skip duplicated moieties. this method is the default, however under certain circumstances it leaves duplicate moieties, as the asymmetric unit can initially contain more than one copy of a single moiety. default.
  • --use-atom-classes — use COD atom classes, generated by the AtomClassifier module from the 'atomclasses' repository, for the generation of Morgan fingerprints. requires the external AtomClassifier module. default.
  • --no-use-atom-classes, --dont-use-atom-classes — use atom chemical types for generation of Morgan fingerprints instead of COD atom classes.
  • --bump-distance-factor 0.75 — a fraction of covalent bond radii sum used to determine when atoms are too close and are considered a bump. Default: 0.75.
  • --vdw-distance-factor 1.2 — a factor for the vdW radii sum used to determine when atoms are too close and are considered a vdW clash. Default: 1.2.
  • --continue-on-errors — do not stop if errors such as unrecognised atoms are encountered.
bestie NO 😭 the output may be incorrect and missing some atoms if this option is used! she's telling you, listen to her!
  • --no-continue-on-errors, --dont-continue-on-errors — stop immediately when an error is encountered.
  • --exclude-zero-occupancies — do not use atoms with 0 occupancies in calculations. default. zero occupancy? not in this house 💅
  • --no-exclude-zero-occupancies, --dont-exclude-zero-occupancies — use atoms with 0 occupancies in calculations.
  • --exclude-dummy-atoms — do not use dummy atoms (marked by the 'dum' calc flag) in calculations. default.
  • --no-exclude-dummy-atoms, --dont-exclude-dummy-atoms — use dummy atoms (marked by the 'dum' calc flag) in calculations.

okay so dummy atoms can be used to mark interesting positions within the unit cell (e.g. geometric centers of coordinated atom rings), but they are not considered a part of the molecule. as a result, the occupancies of all output dummy atoms are set to '.'. and also pls note: dummy atoms with non-numeric coordinates will still be excluded. periodt 🌸

  • --preserve-stoichiometry — apply necessary symmetry operations to preserve molecular stoichiometry (charges, etc.). keeping the balance, she's so responsible 🫶
  • --no-preserve-stoichiometry, --dont-preserve-stoichiometry — do not apply any more symmetry operations than needed to reconstruct covalently connected networks.
she may break stoichiometry of salts and complexes. default. just so you know 💀
  • --force-unit-occupancies — set occupancies of all output atoms to 1.0. unit occupancies are only set when outputting the atoms and do not affect the flow of the algorithm (disorder group processing, molecule sorting, etc.). dummy atoms are excluded from the effects of this option and are always output with the '.' occupancy.

some programs, notably Jumbo converter's cif2ml... okay wait, it's cif2cml — assume unresolved disorder and do not recognize aromatic rings if occupancies are not unities. obviously, this flag only has sense in combination with --split-disorder-groups. iykyk ✨

  • --no-force-unit-occupancies, --dont-force-unit-occupancies, --do-not-force-unit-occupancies — leave occupancies as they are. default.
  • --dump-atoms — dump atoms (including symmetry-equivalent) in CIF format for inspection with some graphics program. go look at them bestie, they're pretty 🦋
  • --no-dump-atoms, --dont-dump-atoms — do not dump atoms. default.
  • --max-polymer-span 0 — a span, in +/- unit cells, in which polymeric molecules (repeating units) will be constructed. when the value is set to '0', polymeric molecules are represented only by the atoms that were included in the determination of the corresponding quotient graphs. Default: 0.
  • --max-polymer-atoms 100 — the maximum allowed count of polymer example atoms. more than this number of symmetry (translational) equivalent atoms, for each atom of the asymmetric unit, will not be written to the output. Default: 100.
this option is considered deprecated and is only retained for backwards compatibility 💀 the current implementation uses the quotient graph approach to find limits of the polymeric molecule. essentially, there is no need to limit the molecule in any way. the '--max-polymer-span' option is only used to specify the desired span of the monomer repetition, but it is not required since the molecule detection is limited by quotient graph.
  • --split-disorder-groups, --dont-merge-disorder-groups — put examples of disorder group conformations into separate data blocks. default. ✨
  • --merge-disorder-groups, --no-split-disorder-groups, --dont-split-disorder-groups — put all disorder groups into one data block.
  • --use-special-disorder-symmetry — generate symmetry equivalents for disorder groups with negative indices. default.
  • --random-seed 123456 — use the provided seed to initialise the random number generator. use "" (empty string) as a seed to revert back to the default seed. 🎲
  • --special-disorder-operator-set 0
  • --special-disorder-operator-set random

— indicates which operator set to apply to atom groups that are disordered around a special position. can be an integer (0, 1, 2, ...) or a special value "random", in which case a random operator is selected for each special position image. 💅

  • --no-use-special-disorder-symmetry, --dont-use-special-disorder-symmetry, --do-not-use-special-disorder-symmetry — do not generate symmetry equivalents for disorder groups with negative indices.
  • --largest, --largest-molecule-only — bestie, this one outputs only the largest molecule 🫶 and the "largest" title is decided by two criteria, in this exact order: atom count, then the overall occupancy of the molecule. And if you've got the combo of --one-datablock-output + --split-disorder-groups going on, you get back the molecule with the most likely disorder conformation (occupancy-wise, obviously 💅).
⚠️ NOTE, and this one matters: if there's more than one disorder assembly and --split-disorder-groups is in effect, the conformation with the highest atom count might not get generated at all. Like, it just won't exist in the output. In that case, a molecule that best fits the previously defined criteria out of the generated conformation subset will be returned instead. No cap, that's just how it goes 😭
  • --all, --all-molecules — output all molecules. This is the default, so if you didn't ask for anything, this is what you're getting, and honestly? slay ✨
  • --use-perl-parser — pick the Perl parser to parse CIF files.
  • --use-c-parser — pick the C parser to parse CIF files. The C parser is the default, so it's already the main character here 👑
  • --print-quotient-graph — output the quotient graph information. This is the default. And heads up: quotient graphs are only output for polymeric molecules unless you also specify the --include-non-polymer-quotient-graph option 🧚
  • --no-print-quotient-graph — do not output the quotient graph information. bye quotient graph 💀
  • --include-non-polymer-quotient-graph — output quotient graph for non-polymer molecules. yes, the little ones get a graph too 🥺
  • --no-include-non-polymer-quotient-graph — do not output quotient graph for non-polymer molecules. This is the default.
  • --symdebug — print debug output for symmetry reconstruction. for when the symmetry is acting up and you need to see everything 🔍
  • --no-symdebug — do not print any symmetry debug output. This is the default.
  • --debug — print some human-readable debug output. cute, readable, informative 💖
  • --no-debug — suppress any debug output. This is the default. silence, bestie 🤫
  • --format "%8.6f" — use the specified format for the output coordinate printout. So you pass it your own format string, like the "%8.6f" shown here, and the coordinates get printed that way. your formatting, your rules 💅
  • --audit — print audit information to the generated CIF file. This is the default.
  • --no-audit — do not print audit information to the generated CIF file.
  • --verbose — print warning messages in long format. get the whole story, not just the headline 📢
  • --no-verbose — print warning messages in concise format. This is the default.
  • --help, --usage — output a short usage message (this message, the one you're reading the vibes of) and exit. classic 🎀
  • --version — output version information and exit. know what you're running, bestie ⭐

🐛 REPORTING BUGS 🐛

Found a bug? Report cif_molecule bugs using e-mail: cod-bugs@ibt.lt — they wanna hear about it fr fr 🙈

and that's the whole page, bestie!! 🌈 this was CIF_MOLECULE(1) from the COD tools era — written and maintained by the lovely people over at the Crystallography Open Database (that's the source, and this page carries the classic COD manual date/version footer, so check the header of your local copy for the exact numbers 🫶). go forth, parse those CIFs, and remember: defaults are your friends until they're not. mwah 💋

📦 where this page comes from