AKFReader

The AKFReader Python class provides a convenient way to read annotated data from the binary KF files generated by AMS.

Below is an example demonstrating some of the AKFReader class’s functionality

#!/usr/bin/env amspython

from scm.akfreader import AKFReader

# ===== Load a kf file.
akf = AKFReader("test.results/dftb.rkf")


# ===== Print all content in the kf file:
akf.print_all_variables()


# ===== Read a specific variable from file.
coordinates = akf.read("Molecule%Coords")
print("Coordinates:")
print(coordinates)

# Coordinates:
# [[-1.65367945e+00  4.59827802e+00 -9.59515212e-09]
#  [ 5.88355572e-01  2.78581237e+00  1.09863437e-08]
#  ...
#  [-3.26489723e+00  3.74833282e+00  9.66428930e-01]
#  [-2.21256221e+00  5.05007997e+00 -1.93285786e+00]]


# ====== Retrieve the description, units, and additional information for a variable:
description_dict = akf.description("Molecule%Coords")
print("'Molecule%Coords' description:")
print(description_dict)

# 'Molecule%Coords' description:
# {'_type': 'float_array',
#  '_shape': [3, 'nAtoms'],
#  '_comment': 'Coordinates of the nuclei (x,y,z)',
#  '_unit': 'bohr'}


# ====== Read another variable, and do a unit conversion:
energy_in_eV = akf.read("AMSResults%Energy", units="eV")
print(f"Energy: {energy_in_eV} [eV]")

# Energy: -203.21954672148195 [eV]


# ====== Read all variables matching the pattern:
history_energies = akf.read("History%Energy(#)")
print(history_energies)

# [('History%Energy(1)', -5.758015498298242),
#  ('History%Energy(2)', -5.765039556660788),
#  ('History%Energy(3)', -5.766261662994689),
#  ('History%Energy(4)', -5.766288141072665)]

Note

The KFFile Python class can also be used to read KF files. Key differences between the AKFReader and the KFFile:

  • The AKFReader can provide ‘extra information’ on the content of the KF files: it can give descriptions of sections, variables, units, and automatically reshapes matrices to the proper size/shape.

  • The KFFile can also be used to write KF files (while the AKFReader can only read).

See also

A command line utility $AMSBIN/akf (described here) offers an alternative way of using the AKFReader tool.

See also

The list of possible variables for the various kf files can be found in the respective user manuals: ams.rkf, adf.rkf, band.rkf, dftb.rkf

API documentation:

class AKFReader(path: str, kf_def_path=None, strict=False, verbose=False)

A class to read AMS binary output files in KF format.

description(name: str) → Dict[str, Any]

Return the description of the key as a dictionary.

find(name: str) → list

Given the name of a variable with patterns, return the list of actual variables that match the query.

E.g. if name=’History%Energy(#)’, this might return: [‘History%Energy(1)’,’History%Energy(2)’]

print_all_variables(include_hidden=False, print_metadata=True)

Print the whole content of the akf file

print_variable(name, print_metadata=True)

Print the content and description of a variable

read(name: str, units=None)

Read and return the value of a variable.

In case that the name is a pattern like ‘foo(#)’ the result is a list of tuples for all vars matching the pattern:

‘foo(#)’ -> [(‘foo(1)’, value1), (‘foo(3)’, value3)]

Partial patterns are not yet supported, but the idea would be the same:

‘bar(#,#)’ -> [(‘bar(1,1)’, value11), (‘bar(1,2)’,value12), (‘bar(2,1)’,value21)] ‘bar(1,#)’ -> [(‘bar(1,1)’, value11), (‘bar(1,2)’,value12)]

variables(include_hidden=False) → List[str]

Returns a list of all available variables on the file in the form “section%variable”.