Metadata-Version: 2.4
Name: castep_outputs
Version: 0.3.2
Summary: A package for extracting information from castep outputs
Author-email: Jacob Wilkins <jacob.wilkins@stfc.ac.uk>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/oerc0122/castep_outputs
Project-URL: Documentation, https://oerc0122.github.io/castep_outputs/
Project-URL: Repository, https://github.com/oerc0122/castep_outputs.git
Project-URL: Bug Tracker, https://github.com/oerc0122/castep_outputs/issues
Keywords: castep,dft,parser
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: File Formats :: JSON
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Provides-Extra: ruamel
Requires-Dist: ruamel.yaml<0.19,>=0.17.22; extra == "ruamel"
Provides-Extra: yaml
Requires-Dist: pyYAML>=3.13; extra == "yaml"
Dynamic: license-file

castep_outputs
==============

.. image:: https://img.shields.io/badge/version-0.3.2-blue
   :alt: Version

Parser for CASTEP output files

``castep_outputs`` parses the output files of `castep
<https://www.castep.org/>`__ into a standard form and is able to subsequently
dump the processed data into a standard format.

Install
-------

To install ``castep_outputs`` simply run:

::

   pip install castep_outputs

To check it is installed run:

::

   python -m castep_outputs -h

Dependencies
------------

``castep_outputs`` is designed to have no external dependencies beyond the
standard library, however, it is possible to use either `PyYAML
<https://pypi.org/project/PyYAML/>`__ or `ruamel.yaml
<https://pypi.org/project/ruamel.yaml/>`__ to dump in the YAML format.

Command-line
------------

When run as a commandline tool, it attempts to find all files for the
given seedname, filtered by ``inc`` args (default: all). Explicit
files can be passed using longname arguments. castep_outputs can parse
most human-readable castep outputs including:
``.bands``, ``.castep``, ``.cell``, ``.chdiff_fmt``, ``.cst_esp``, ``.den_fmt``,
``.efield``, ``.elastic``, ``.elf_fmt``, ``.epme``, ``.err``, ``.geom``,
``.hug``, ``.magres``, ``.md``, ``.param``, ``.phonon``, ``.phonon_dos``,
``.pot_fmt``, ``.tddft``, ``.ts``, ``.xrd_sf``.

to run in basic mode:

::

   python -m castep_outputs seedname

Which will attempt to detect all found files and dump a ``.json`` to
stdout, ready for piping.

::

   python -m castep_outputs --inc-castep --inc-param seedname

Will parse only the ``seedname.castep`` and ``seedname.param`` files if
found.

::

   python -m castep_outputs seedname.castep

Will parse the single named file and again dump a ``.json`` to stdout.

::

   python -m castep_outputs --castep seedname.param

Will attempt to parse the file ``seedname.param`` as though it were a
``.castep`` file. While not ordinarily useful it can help with manually renamed
files.

::

   python -m castep_outputs -o my_file.yaml -f yaml seedname.castep

Will parse ``seedname.castep``, dump it to ``my_file.yaml`` in ``yaml`` format
using the ``PyYAML`` engine if available and the ``RUAMEL`` engine if not.

As a module
-----------

``import``\ ing ``castep_outputs`` exposes all of the parsers at the
top-level.

The simplest method to use ``castep_outputs`` in a tool is to use the
``parse_single`` method which attempts to determine the parser from the file
extension.

::

   from castep_outputs import parse_single

   my_dict = parse_single('my_file.castep')

If you need a specific parser rather than determining it by extension
it is possible to pass them as the second argument, or call them
directly.

::

   from castep_outputs import parse_single, parse_castep_file

   my_dict = parse_single('my_file', parse_castep_file)

   with open('my_file', 'r', encoding='utf-8') as inp:
       my_dict = parse_castep_file(inp)

It is recommended that you use ``parse_single`` as it uses special file-handling
to give better diagnostics if it fails. It is possible to enable more detailed
logging via the `logging
<https://docs.python.org/3/library/logging.html#logging.basicConfig>`_ module:

::

   import logging
   from castep_outputs import parse_single

   my_dict = parse_single('my_file', loglevel=logging.INFO)

The available parsing functions for parsing the given format are:

 - bands: ``parse_bands_file``
 - castep: ``parse_castep_file``
 - cell: ``parse_cell_param_file``
 - param: ``parse_cell_param_file``
 - chdiff_fmt: ``parse_chdiff_fmt_file``
 - cst_esp: ``parse_cst_esp_file``
 - den_fmt: ``parse_den_fmt_file``
 - efield: ``parse_efield_file``
 - elastic: ``parse_elastic_file``
 - elf_fmt: ``parse_elf_fmt_file``
 - epme: ``parse_epme_file``
 - err: ``parse_err_file``
 - hug: ``parse_hug_file``
 - magres: ``parse_magres_file``
 - geom: ``parse_md_geom_file``
 - md: ``parse_md_geom_file``
 - phonon_dos: ``parse_phonon_dos_file``
 - phonon: ``parse_phonon_file``
 - pot_fmt: ``parse_pot_fmt_file``
 - tddft: ``parse_tddft_file``
 - ts: ``parse_ts_file``
 - xrd_sf: ``parse_xrd_sf_file``

Which return processed ``list``\ s of ``dict``\ s of data ready for use
in other applications.

See `Documentation <https://oerc0122.github.io/castep_outputs/index.html>`_ for full layout.

Full usage
----------

::

   usage: castep_outputs [-h] [-V] [-L {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                         [-o OUTPUT] [-f {json,ruamel,pyyaml,pprint,print}]
                         [-t] [-A] [--inc-castep] [--inc-cell] [--inc-param]
                         [--inc-geom] [--inc-md] [--inc-bands] [--inc-hug]
                         [--inc-phonon_dos] [--inc-efield] [--inc-xrd_sf]
                         [--inc-elf_fmt] [--inc-chdiff_fmt] [--inc-pot_fmt]
                         [--inc-den_fmt] [--inc-elastic] [--inc-ts]
                         [--inc-magres] [--inc-tddft] [--inc-err]
                         [--inc-phonon] [--inc-epme] [--inc-cst_esp]
                         [--castep [CASTEP ...]] [--cell [CELL ...]]
                         [--param [PARAM ...]] [--geom [GEOM ...]]
                         [--md [MD ...]] [--bands [BANDS ...]]
                         [--hug [HUG ...]] [--phonon_dos [PHONON_DOS ...]]
                         [--efield [EFIELD ...]] [--xrd_sf [XRD_SF ...]]
                         [--elf_fmt [ELF_FMT ...]]
                         [--chdiff_fmt [CHDIFF_FMT ...]]
                         [--pot_fmt [POT_FMT ...]] [--den_fmt [DEN_FMT ...]]
                         [--elastic [ELASTIC ...]] [--ts [TS ...]]
                         [--magres [MAGRES ...]] [--tddft [TDDFT ...]]
                         [--err [ERR ...]] [--phonon [PHONON ...]]
                         [--epme [EPME ...]] [--cst_esp [CST_ESP ...]]
                         ...

   Attempts to find all files for seedname, filtered by `inc` args (default:
   all). Explicit files can be passed using longname arguments. castep_outputs
   can parse most castep outputs including: .castep, .cell, .param, .geom,
   .md, .bands, .hug, .phonon_dos, .efield, .xrd_sf, .elf_fmt, .chdiff_fmt,
   .pot_fmt, .den_fmt, .elastic, .ts, .magres, .tddft, .err, .phonon, .epme,
   .cst_esp

   positional arguments:
     seedname              Seed name for data

   options:
     -h, --help            show this help message and exit
     -V, --version         show program's version number and exit
     -L, --log {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                           Verbose output
     -o, --output OUTPUT   File to write output, default: screen
     -f, --out-format {json,ruamel,pyyaml,pprint,print}
                           Output format
     -t, --testing         Set testing mode to produce flat outputs
     -A, --inc-all         Extract all available information
     --inc-castep          Extract .castep information
     --inc-cell            Extract .cell information
     --inc-param           Extract .param information
     --inc-geom            Extract .geom information
     --inc-md              Extract .md information
     --inc-bands           Extract .bands information
     --inc-hug             Extract .hug information
     --inc-phonon_dos      Extract .phonon_dos information
     --inc-efield          Extract .efield information
     --inc-xrd_sf          Extract .xrd_sf information
     --inc-elf_fmt         Extract .elf_fmt information
     --inc-chdiff_fmt      Extract .chdiff_fmt information
     --inc-pot_fmt         Extract .pot_fmt information
     --inc-den_fmt         Extract .den_fmt information
     --inc-elastic         Extract .elastic information
     --inc-ts              Extract .ts information
     --inc-magres          Extract .magres information
     --inc-tddft           Extract .tddft information
     --inc-err             Extract .err information
     --inc-phonon          Extract .phonon information
     --inc-epme            Extract .epme information
     --inc-cst_esp         Extract .cst_esp information
     --castep [CASTEP ...]
                           Extract from CASTEP as .castep type
     --cell [CELL ...]     Extract from CELL as .cell type
     --param [PARAM ...]   Extract from PARAM as .param type
     --geom [GEOM ...]     Extract from GEOM as .geom type
     --md [MD ...]         Extract from MD as .md type
     --bands [BANDS ...]   Extract from BANDS as .bands type
     --hug [HUG ...]       Extract from HUG as .hug type
     --phonon_dos [PHONON_DOS ...]
                           Extract from PHONON_DOS as .phonon_dos type
     --efield [EFIELD ...]
                           Extract from EFIELD as .efield type
     --xrd_sf [XRD_SF ...]
                           Extract from XRD_SF as .xrd_sf type
     --elf_fmt [ELF_FMT ...]
                           Extract from ELF_FMT as .elf_fmt type
     --chdiff_fmt [CHDIFF_FMT ...]
                           Extract from CHDIFF_FMT as .chdiff_fmt type
     --pot_fmt [POT_FMT ...]
                           Extract from POT_FMT as .pot_fmt type
     --den_fmt [DEN_FMT ...]
                           Extract from DEN_FMT as .den_fmt type
     --elastic [ELASTIC ...]
                           Extract from ELASTIC as .elastic type
     --ts [TS ...]         Extract from TS as .ts type
     --magres [MAGRES ...]
                           Extract from MAGRES as .magres type
     --tddft [TDDFT ...]   Extract from TDDFT as .tddft type
     --err [ERR ...]       Extract from ERR as .err type
     --phonon [PHONON ...]
                           Extract from PHONON as .phonon type
     --epme [EPME ...]     Extract from EPME as .epme type
     --cst_esp [CST_ESP ...]
                           Extract from CST_ESP as .cst_esp type


Current Parsers:

- ``.bands``
- ``.castep``
- ``.cell``
- ``.chdiff_fmt``
- ``.cst_esp``
- ``.den_fmt``
- ``.efield``
- ``.elastic``
- ``.elf_fmt``
- ``.epme``
- ``.err``
- ``.geom``
- ``.hug``
- ``.magres``
- ``.md``
- ``.param``
- ``.phonon``
- ``.phonon_dos``
- ``.pot_fmt``
- ``.tddft``
- ``.ts``
- ``.xrd_sf``

Current dumpers:

- ``json``
- ``pprint``
- ``print``
- ``pyyaml``
- ``ruamel``
