tesliper.writing.txt_writer

Data export to text files.

Classes

TxtWriter(destination[, mode])

Writes extracted or calculated data to .txt format files.
class tesliper.writing.txt_writer.TxtWriter(destination: Union[str, pathlib.Path], mode: str = 'x')[source]

Writes extracted or calculated data to .txt format files.

Parameters

  • destination (str or pathlib.Path) – Directory, to which generated files should be written.

  • mode (str) – Specifies how writing to file should be handled. Should be one of characters: ‘a’ (append to existing file), ‘x’ (only write if file doesn’t exist yet), or ‘w’ (overwrite file if it already exists).

generic(data: List[Union[tesliper.glassware.arrays.DataArray, tesliper.glassware.arrays.IntegerArray, tesliper.glassware.arrays.FloatArray, tesliper.glassware.arrays.BooleanArray, tesliper.glassware.arrays.InfoArray]], name_template: Union[str, string.Template] = '${cat}.${det}.${ext}')[source]

Writes generic data from multiple DataArray-like objects to a single file. Said objects should provide a single value for each conformer.

Parameters

  • data – DataArray objects that are to be exported.

  • name_template – Template that will be used to generate filenames. Refer to make_name() documentation for details on supported placeholders.

overview(energies: Sequence[tesliper.glassware.arrays.Energies], frequencies: Optional[tesliper.glassware.arrays.Bands] = None, stoichiometry: Optional[tesliper.glassware.arrays.InfoArray] = None, name_template: Union[str, string.Template] = '${cat}.${ext}')[source]

Writes essential information from multiple Energies objects to single txt file.

Notes

All Energy objects given should contain information for the same set of files.

Parameters

  • energies (list of glassware.Energies) – Energies objects that is to be exported

  • frequencies (glassware.DataArray, optional) – DataArray object containing frequencies, needed for imaginary frequencies count

  • stoichiometry (glassware.InfoArray, optional) – InfoArray object containing stoichiometry information

  • name_template (str or string.Template) – Template that will be used to generate filenames. Refer to make_name() documentation for details on supported placeholders.

energies(energies: tesliper.glassware.arrays.Energies, corrections: Optional[tesliper.glassware.arrays.FloatArray] = None, name_template: Union[str, string.Template] = 'distribution-${genre}.${ext}')[source]

Writes Energies object to txt file.

Parameters

  • energies (glassware.Energies) – Energies object that is to be serialized

  • corrections (glassware.DataArray, optional) – DataArray object, containing energies corrections

  • name_template (str or string.Template) – Template that will be used to generate filenames. Refer to make_name() documentation for details on supported placeholders.

single_spectrum(spectrum: tesliper.glassware.spectra.SingleSpectrum, name_template: Union[str, string.Template] = '${cat}.${genre}-${det}.${ext}')[source]

Writes SingleSpectrum object to txt file.

Parameters

  • spectrum (glassware.SingleSpectrum) – spectrum, that is to be serialized

  • name_template (str or string.Template) – Template that will be used to generate filenames. Refer to make_name() documentation for details on supported placeholders.

spectral_activities(band: tesliper.glassware.arrays.SpectralActivities, data: List[tesliper.glassware.arrays.SpectralActivities], name_template: Union[str, string.Template] = '${conf}.${cat}-${det}.${ext}')[source]

Writes SpectralActivities objects to txt files (one for each conformer).

Parameters

  • band (glassware.SpectralActivities) – object containing information about band at which transitions occur; it should be frequencies for vibrational data and wavelengths or excitation energies for electronic data

  • data (list of glassware.SpectralActivities) – SpectralActivities objects that are to be serialized; all should contain information for the same conformers. Assumes that all data’s elements have the same spectra_type, which is passed to the name_template as “det”.

  • name_template (str or string.Template) – Template that will be used to generate filenames. Refer to make_name() documentation for details on supported placeholders.

Raises

ValueError – if data is an empty sequence

spectral_data(band: tesliper.glassware.arrays.SpectralActivities, data: List[tesliper.glassware.arrays.SpectralData], name_template: Union[str, string.Template] = '${conf}.${cat}-${det}.${ext}')[source]

Writes SpectralData objects to txt files (one for each conformer).

Parameters

  • band (glassware.SpectralData) – object containing information about band at which transitions occur; it should be frequencies for vibrational data and wavelengths or excitation energies for electronic data

  • data (list of glassware.SpectralData) – SpectralData objects that are to be serialized; all should contain information for the same conformers. Assumes that all data’s elements have the same spectra_type, which is passed to the name_template as “det”.

  • name_template (str or string.Template) – Template that will be used to generate filenames. Refer to make_name() documentation for details on supported placeholders.

Raises

ValueError – if data is an empty sequence

spectra(spectra: tesliper.glassware.spectra.Spectra, name_template: Union[str, string.Template] = '${conf}.${genre}.${ext}')[source]

Writes Spectra object to text files (one for each conformer).

Parameters

  • spectra (glassware.Spectra) – Spectra object, that is to be serialized

  • name_template (str or string.Template) – Template that will be used to generate filenames. Refer to make_name() documentation for details on supported placeholders.

transitions(transitions: tesliper.glassware.arrays.Transitions, wavelengths: tesliper.glassware.arrays.Bands, only_highest=True, name_template: Union[str, string.Template] = '${conf}.${cat}-${det}.${ext}')[source]

Writes electronic transitions data to text files (one for each conformer).

Parameters

  • transitions (glassware.Transitions) – Electronic transitions data that should be serialized.

  • wavelengths (glassware.ElectronicActivities) – Object containing information about wavelength at which transitions occur.

  • only_highest (bool) – Specifies if only transition of highest contribution to given band should be reported. If False all transition are saved to file. Defaults to True.

  • name_template (str or string.Template) – Template that will be used to generate filenames. Refer to make_name() documentation for details on supported placeholders.

_get_handle(template: Union[str, string.Template], template_params: dict, open_params: Optional[dict] = None) → Iterator[IO]

Helper method for creating files. Given additional kwargs will be passed to Path.open() method. Implemented as context manager for use with with statement.

Parameters

  • template (str or string.Template) – Template that will be used to generate filenames.

  • template_params (dict) – Dictionary of {identifier: value} for .make_name method.

  • open_params (dict, optional) – Arguments for Path.open() used to open file.

Yields

  • IO – file handle, will be closed automatically after with statement exits

  • meta public:

_iter_handles(filenames: Iterable[str], template: Union[str, string.Template], template_params: dict, open_params: Optional[dict] = None) → Iterator[IO]

Helper method for iteration over generated files. Given additional kwargs will be passed to Path.open() method.

Parameters

  • filenames (list of str) – list of source filenames, used as value for ${conf} placeholder in name_template

  • template_params (dict) – Dictionary of {identifier: value} for .make_name method.

  • open_params (dict, optional) – arguments for Path.open() used to open file.

Yields

  • TextIO – file handle, will be closed automatically on next iteration

  • meta public:

property destination: pathlib.Path

Directory, to which generated files should be written.

Raises

FileNotFoundError – If given destination doesn’t exist or is not a directory.

Type

pathlib.Path

static distribute_data(data: List) → Tuple[Dict[str, List], Dict[str, Any]]

Sorts given data by genre category for use by specialized writing methods.

Returns

  • distr (dict) – Dictionary with DataArray-like objects, sorted by their type. Each {key: value} pair is {name of the type in lowercase format: list of DataArray objects of this type}.

  • extras (dict) – Spacial-case genres: extra information used by some writer methods when exporting data. Available {key: value} pairs (if given in data) are:

    corrections: dict of {“energy genre”: FloatArray},
    frequencies: Bands,
    wavelengths: Bands,
    excitation: Bands,
    stoichiometry: InfoArray,
    charge: IntegerArray,
    multiplicity: IntegerArray

geometry(geometry: tesliper.glassware.arrays.Geometry, charge: Optional[Union[tesliper.glassware.arrays.IntegerArray, Sequence[int], int]] = None, multiplicity: Optional[Union[tesliper.glassware.arrays.IntegerArray, Sequence[int], int]] = None, name_template: Union[str, string.Template] = '')

Interface for writing single object with geometry of each conformer. Evoked when handling Geometry objects.

Parameters

  • geometry – Positions of atoms in each conformer. Mandatory in custom implementation.

  • charge – Value of each structure’s charge. Mandatory in custom implementation.

  • multiplicity – Value of each structure’s multiplicity. Mandatory in custom implementation.

  • name_template – Template that defines naming scheme for files generated by this method. May be omitted in custom implementation.

Raises

NotImplementedError – Whenever called, this is an interface that should not be used directly.

make_name(template: Union[str, string.Template], conf: str = '', num: Union[str, int] = '', genre: str = '', cat: str = '', det: str = '', ext: str = '') → str

Create filename using given template and given or global values for known identifiers. The identifier should be used in the template as "${identifier}" where “identifier” is the name of identifier. Available names and their meaning are:

${ext} - appropriate file extension
${conf} - name of the conformer
${num} - number of the file according to internal counter
${genre} - genre of exported data
${cat} - category of produced output
${det} - category-specific detail

The ${ext} identifier is filled with the value of Writers extension attribute if not explicitly given as parameter to this method’s call. Values for other identifiers should be provided by the caller.

Parameters

  • template (str or string.Template) – Template that will be used to generate filenames. It should contain only known identifiers, listed above.

  • conf (str) – value for ${conf} identifier, defaults to empty string.

  • num (str or int) – value for ${str} identifier, defaults to empty string.

  • genre (str) – value for ${genre} identifier, defaults to empty string.

  • cat (str) – value for ${cat} identifier, defaults to empty string.

  • det (str) – value for ${det} identifier, defaults to empty string.

  • ext (str) – value for ${ext} identifier, defaults to empty string.

Raises

ValueError – If given template or string contains any unexpected identifiers.

Examples

Must be first subclassed and instantiated:

>>> class MyWriter(WriterBase):
>>>     extension = "foo"
>>> wrt = MyWriter("/path/to/some/directory/")

>>> wrt.make_name(template="somefile.${ext}")
"somefile.foo"
>>> wrt.make_name(template="${conf}.${ext}")
".foo"  # conf is empty string by default
>>> wrt.make_name(template="${conf}.${ext}", conf="conformer")
"conformer.foo"
>>> wrt.make_name(template="Unknown_identifier_${bla}.${ext}")
Traceback (most recent call last):
ValueError: Unexpected identifiers given: bla.
property mode

Specifies how writing to file should be handled. Should be one of characters: “a”, “x”, or “w”. “a” - append to existing file; “x” - only write if file doesn’t exist yet; “w” - overwrite file if it already exists.

Raises

ValueError – If given anything other than “a”, “x”, or “w”.

write(data: List) → None

Writes DataArray-like objects to disk, decides how to write them based on the type of each object. If some types of given objects are not supported by this writer, data of this type is ignored and a warning is emitted.

Parameters

data (List) – DataArray-like objects that should be written to disk.