matador.export package

The export module provides interfaces to write matador-created dictionaries/Crystal objects to several file formats.

Currently supported formats:

• CASTEP’s .cell and .param

• the Protein Data Bank’s .pdb

• input files for Quantum Espresso (written as .in)

• XCrysden’s .xsf

• the custom .res file format based on SHELX used first by AIRSS

  (https://www.mtg.msm.cam.ac.uk/Codes/AIRSS)

matador.export.doc2param(doc, path, overwrite=False, hash_dupe=False, spin=False)

Write basic .param file from single doc.

Parameters:

• doc (dict) – the document to write out to file

• path (str) – the desired path to file

Keyword Arguments:

• spin (bool) – enforce breaking of spin symmetry to magic number of 5.

• overwrite (bool) – whether or not to overwrite colliding files.

• hash_dupe (bool) – whether or not to create a unique filename for any colliding files, or just skip writing them.

Returns:

list of strings to write to file, with implicit newlines,

and the required file extension.

Return type:

list, str

matador.export.doc2cell(doc, path, overwrite=False, hash_dupe=False, spin=False)

Write .cell file for single doc.

Parameters:

• doc (dict) – the document to write to file

• path (str) – the desired path to the file

Keyword Arguments:

• overwrite (bool) – whether or not to overwrite colliding files.

• hash_dupe (bool) – whether or not to create a unique filename for any colliding files, or just skip writing them.

• spin (bool) – break spin symmetry with magic number 5 on first atom

Returns:

list of strings to write to file, with implicit newlines,

and the required file extension.

Return type:

list, str

matador.export.doc2pdb(doc, path, info=True, hash_dupe=True)

Write a simple .pdb for single doc.

Parameters:

• doc (dict) – matador document containing structure.

• path (str) – desired path of xsf file.

Keyword Arguments:

• info (bool) – write info string to HEADER.

• hash_dupe (bool) – hash duplicate file names or skip?

matador.export.doc2pwscf(doc, path, template=None, spacing=None)

Write the structural part of QE input file based on the provided matador doc. Will calculate the correct kpoint_mp_grid if spacing is provided.

Parameters:

• doc (dict) – matador document containing structure

• path (str) – desired filename for res file

Keyword Arguments:

• template (str) – filename of template to prepend before structure (with prefix keyword to be replaced),

• spacing (float) – kpoint_mp_spacing to use when calculating grid.

matador.export.doc2res(doc, path, overwrite=False, hash_dupe=False, info=True, spoof_titl=False, sort_atoms=True)

Write .res file for single doc.

Parameters:

• doc (dict) – matador document containing structure

• path (str) – desired filename for res file

Keyword Arguments:

• info (bool) – require info in res file header

• spoof_titl (bool) – make up fake info for file header (for use with e.g. cryan)

• sorted (bool) – if False, atoms are not sorted (this will not be a valid res file)

• overwrite (bool) – whether or not to overwrite colliding files.

• hash_dupe (bool) – whether or not to create a unique filename for any colliding files, or just skip writing them.

matador.export.doc2xsf(doc, path, write_energy=False, write_forces=False, overwrite=False)

Write an .xsf file for a matador document, with positions in Cartesian coordinates. Optionally, write the energy in a comment at the top of the file for use with aenet.

Parameters:

• doc (dict) – matador document containing structure.

• path (str) – desired path of xsf file.

Keyword Arguments:

• write_energy (bool) – whether or not to write total energy in a comment as the first line of the file.

• write_forces (bool) – whether or not to write the forces on each atom.

• overwrite (bool) – overwrite if file exists.

matador.export.query2files(cursor, dirname=None, top=None, prefix=None, cell=None, param=None, res=None, pdb=None, json=None, xsf=None, markdown=True, max_files=None, latex=False, subcmd=None, argstr=None, **kwargs)

Many-to-many convenience function for many structures being written to many file types.

Parameters:

cursor (list of dict/AtomicSwapper) – list of matador dictionaries to write out.

Keyword Arguments:

• dirname (str) – the folder to save the results into. Will be created if non-existent. Will have integer appended to it if already existing.

• **kwargs (dict) – dictionary of {filetype: bool(whether to write)}. Accepted file types are cell, param, res, pdb, json, xsf, markdown and latex.

matador.export.doc2arbitrary(doc, path, overwrite=False, hash_dupe=False)

Write a Python dictionary into a standard CASTEP-style keyword: value file.

Parameters:

• doc (dict) – contains key-value pairs.

• path (str) – filename to write to.

Keyword Arguments:

• hash_dupe (bool) – hash duplicate file names, or skip?

• overwrite (bool) – overwrite if filename exists.

Returns:

list of strs to write to file.

Return type:

list

Submodules

matador.export.export module

This file implements functions that write files from matador documents or Crystal objects.

matador.export.export.query2files(cursor, dirname=None, top=None, prefix=None, cell=None, param=None, res=None, pdb=None, json=None, xsf=None, markdown=True, max_files=None, latex=False, subcmd=None, argstr=None, **kwargs)

Many-to-many convenience function for many structures being written to many file types.

Parameters:

cursor (list of dict/AtomicSwapper) – list of matador dictionaries to write out.

Keyword Arguments:

• dirname (str) – the folder to save the results into. Will be created if non-existent. Will have integer appended to it if already existing.

• **kwargs (dict) – dictionary of {filetype: bool(whether to write)}. Accepted file types are cell, param, res, pdb, json, xsf, markdown and latex.

matador.export.export.doc2param(doc, path, overwrite=False, hash_dupe=False, spin=False)

Write basic .param file from single doc.

Parameters:

• doc (dict) – the document to write out to file

• path (str) – the desired path to file

Keyword Arguments:

• spin (bool) – enforce breaking of spin symmetry to magic number of 5.

• overwrite (bool) – whether or not to overwrite colliding files.

• hash_dupe (bool) – whether or not to create a unique filename for any colliding files, or just skip writing them.

Returns:

list of strings to write to file, with implicit newlines,

and the required file extension.

Return type:

list, str

matador.export.export.doc2cell(doc, path, overwrite=False, hash_dupe=False, spin=False)

Write .cell file for single doc.

Parameters:

• doc (dict) – the document to write to file

• path (str) – the desired path to the file

Keyword Arguments:

• overwrite (bool) – whether or not to overwrite colliding files.

• hash_dupe (bool) – whether or not to create a unique filename for any colliding files, or just skip writing them.

• spin (bool) – break spin symmetry with magic number 5 on first atom

Returns:

list of strings to write to file, with implicit newlines,

and the required file extension.

Return type:

list, str

matador.export.export.doc2pdb(doc, path, info=True, hash_dupe=True)

Write a simple .pdb for single doc.

Parameters:

• doc (dict) – matador document containing structure.

• path (str) – desired path of xsf file.

Keyword Arguments:

• info (bool) – write info string to HEADER.

• hash_dupe (bool) – hash duplicate file names or skip?

matador.export.export.doc2json(doc, path, overwrite=False, hash_dupe=True)

Return raw JSON document as stored in database.

Parameters:

• doc (dict) – matador document containing structure

• path (str) – desired filename for res file

Keyword Arguments:

• hash_dupe (bool) – hash duplicate file names, or skip?

• overwrite (bool) – overwrite if filename exists.

matador.export.export.doc2pwscf(doc, path, template=None, spacing=None)

Write the structural part of QE input file based on the provided matador doc. Will calculate the correct kpoint_mp_grid if spacing is provided.

Parameters:

• doc (dict) – matador document containing structure

• path (str) – desired filename for res file

Keyword Arguments:

• template (str) – filename of template to prepend before structure (with prefix keyword to be replaced),

• spacing (float) – kpoint_mp_spacing to use when calculating grid.

matador.export.export.doc2res(doc, path, overwrite=False, hash_dupe=False, info=True, spoof_titl=False, sort_atoms=True)

Write .res file for single doc.

Parameters:

• doc (dict) – matador document containing structure

• path (str) – desired filename for res file

Keyword Arguments:

• info (bool) – require info in res file header

• spoof_titl (bool) – make up fake info for file header (for use with e.g. cryan)

• sorted (bool) – if False, atoms are not sorted (this will not be a valid res file)

• overwrite (bool) – whether or not to overwrite colliding files.

• hash_dupe (bool) – whether or not to create a unique filename for any colliding files, or just skip writing them.

matador.export.export.doc2xsf(doc, path, write_energy=False, write_forces=False, overwrite=False)

Write an .xsf file for a matador document, with positions in Cartesian coordinates. Optionally, write the energy in a comment at the top of the file for use with aenet.

Parameters:

• doc (dict) – matador document containing structure.

• path (str) – desired path of xsf file.

Keyword Arguments:

• write_energy (bool) – whether or not to write total energy in a comment as the first line of the file.

• write_forces (bool) – whether or not to write the forces on each atom.

• overwrite (bool) – overwrite if file exists.

matador.export.export.doc2arbitrary(doc, path, overwrite=False, hash_dupe=False)

Write a Python dictionary into a standard CASTEP-style keyword: value file.

Parameters:

• doc (dict) – contains key-value pairs.

• path (str) – filename to write to.

Keyword Arguments:

• hash_dupe (bool) – hash duplicate file names, or skip?

• overwrite (bool) – overwrite if filename exists.

Returns:

list of strs to write to file.

Return type:

list

matador.export.utils module

This submodule includes some useful utility functions for exporting data.

matador.export.utils.file_writer_function(function)

Wrapper for file writers to safely overwrite/hash duplicate files.

Keyword Arguments:

• overwrite (bool) – whether or not to overwrite colliding files.

• hash_dupe (bool) – whether or not to create a unique filename for any colliding files, or just skip writing them.

matador.export.utils.generate_hash(hash_len=6)

Quick hash generator, based on implementation in PyAIRSS by J. Wynn.

Keyword Arguments:

hash_len (int) – desired length of hash.

matador.export.utils.generate_relevant_path(**args)

Generates a suitable path name based on query.