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, max_files=10000, top=None, prefix=None, cell=None, param=None, res=None, pdb=None, json=None, xsf=None, markdown=True, 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.

• max_files (int) – if the number of files to be written exceeds this number, then raise RuntimeError.

• **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, max_files=10000, top=None, prefix=None, cell=None, param=None, res=None, pdb=None, json=None, xsf=None, markdown=True, 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.

• max_files (int) – if the number of files to be written exceeds this number, then raise RuntimeError.

• **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.