Fortran Dictionary objects for storing key/value pairs

A Dictionary object contains a list of keys (strings) and corresponding entries. Entries are a variable type, containing one of: integer, real(dp), complex(dp), logical, extendable_str or a 1-D array of any of those. 2-D arrays of integers and reals are also supported.

Module contents for quippy.dictionary:

Classes

Dictionary([D]) Fortran implementation of a dictionary to store key/value pairs of the following types:

Functions

bcast(*args, **kwargs) Routine is wrapper around Fortran interface bcast containing multiple routines:

Attributes

Name Value
T_CHAR_A 10
PROPERTY_INT 1
C_KEY_LEN 256
n_entry_block 10
T_INTEGER_A 5
T_LOGICAL 4
PROPERTY_REAL 2
T_LOGICAL_A 8
T_REAL_A2 13
STRING_LENGTH 10240
T_INTEGER_A2 12
T_COMPLEX 3
T_REAL_A 6
T_DATA 11
PROPERTY_STR 3
T_REAL 2
T_COMPLEX_A 7
T_NONE 0
DICT_N_FIELDS 100
T_DICT 14
T_INTEGER 1
T_CHAR 9
PROPERTY_LOGICAL 4
class quippy.dictionary.Dictionary([D])[source]

Bases: quippy.dictmixin.DictMixin, quippy.dictmixin.ParamReaderMixin, quippy._dictionary.Dictionary

Fortran implementation of a dictionary to store key/value pairs of the following types:

  • Integer
  • Real
  • String
  • Complex
  • Logical
  • 1D integer array
  • 1D real array
  • 1D complex array
  • 1D logical array
  • 2D integer array
  • 2D real array
  • Arbitrary data, via Fortran transform() intrinsic

Initialise a new empty dictionary

References

Routine is wrapper around Fortran routine __init__initialise defined in file src/libAtoms/Dictionary.f95.

The quippy Python Dictionary class is designed to behave as much as possible like a true Python dictionary, but since it is implemented in Fortran it can only store a restricted range of data types. Keys much be strings and values must be one of the types above.

Trying to store any other type of data will raise a ValueError.

For Atoms’ params entries, there are further restrictions imposed by the implementation of the XYZ and NetCDF I/O routines. The only types of data that can be stored here are:

  • Integer
  • Real
  • String
  • Integer 3-vector
  • Real 3-vector
  • Integer 3 x 3 matrix
  • Real 3 x 3 matrix

A Dictionary can be created from a standard Python dictionary, and easily converted back:

>>> py_dict = {'a':1, 'b':2}
>>> fortran_dict = Dictionary(py_dict)
>>> py_dict == dict(fortran_dict)
True

It also supports all the standard dictionary operations and methods:

>>> fortran_dict['c'] = 3
>>> fortran_dict.keys()
['a', 'b', 'c']

An additional feature of the quippy Dictionary is that it can read and write itself to a string in the format used within XYZ files:

>>> str(fortran_dict)
'a=1 b=2 c=3'
>>> d2 = Dictionary('a=1 b=2 c=3')
>>> d2.keys(), d2.values()
(['a', 'b', 'c'], [1, 2, 3])

Class is wrapper around Fortran type Dictionary defined in file src/libAtoms/Dictionary.f95.

Attributes:
cache_invalid

non-zero on exit from set_value(), set_value_pointer(), add_array(), remove_entry() if any array memory locations changed

key_cache_invalid

non-zero on exit from set_value(), set_value_pointer(), add_array(), remove_entry() if any keys changed

n

number of entries in use

Methods

add_array(*args, **kwargs) Wrapper around Fortran interface add_array containing multiple routines:
assignment(from) Make a deep copy of from in this, allocating new memory for array components; no error passing, for the assignment operator
deepcopy(from,[error]) Make a deep copy of from in this, allocating new memory for array components
deepcopy_no_error(from) Make a deep copy of from in this, allocating new memory for array components; no error passing, for the assignment operator
expand_string(in,[error]) Copy extendable string from in to out, expanding variables formatted as \:math:`KEY or \`\{KEY\} using values in this Dictionary.
get_array(key) Return a _reference_ to an array stored in this Dictionary
get_key(i,[error])
Parameters:
get_type(key) Return an integer code for the type of the value associated with a key
get_type_and_size(key,[error])
Parameters:
get_value(k) Return a _copy_ of a value stored in Dictionary
is_same_fortran_object(other) Test if self and other point to the same Fortan object.
iterkeys()
lookup_entry_i(key,[case_sensitive]) OMIT
print_([verbosity,file]) Print a DictEntry or a Dictionary
print_keys([verbosity,file]) dictionary_print_keys([verbosity,file])
read_string(str,[append,error]) Read into this dictionary from a string
remove_value(key) Remove an entry from a Dictionary
set_value(*args, **kwargs) Set a value in a Dictionary
set_value_pointer(*args, **kwargs) Wrapper around Fortran interface set_value_pointer containing multiple routines:
shallow_copy() Return a shallow copy of self.
shallow_copy_from(other) Transform self into a shallow copy of other.
swap(key1,key2,[case_sensitive,error]) Swap the positions of two entries in the dictionary.
write_string(…) Write a string representation of this dictionary
add_array(*args, **kwargs)

Wrapper around Fortran interface add_array containing multiple routines:

add_array(key, value, len2[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-3 array('S') with bounds (qp_n0,qp_n1,(1))) –
  • len2 (input rank-1 array('i') with bounds (2)) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_s_a defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-1 array('d') with bounds (qp_n0)) –
  • len (input int) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_r_a defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-1 array('i') with bounds (qp_n0)) –
  • len (input int) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_l_a defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-1 array('D') with bounds (qp_n0)) –
  • len (input int) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_c_a defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-1 array('i') with bounds (qp_n0)) –
  • len (input int) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_i_a defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len2[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-2 array('d') with bounds (qp_n0,qp_n1)) –
  • len2 (input rank-1 array('i') with bounds (2)) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_r2_a defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input int) –
  • len (input int) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_l defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len2[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input float) –
  • len2 (input rank-1 array('i') with bounds (2)) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_r2 defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len2[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-2 array('i') with bounds (qp_n0,qp_n1)) –
  • len2 (input rank-1 array('i') with bounds (2)) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_i2_a defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input int) –
  • len (input int) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_i defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len2[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input int) –
  • len2 (input rank-1 array('i') with bounds (2)) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_i2 defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len2[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input string(len=1)) –
  • len2 (input rank-1 array('i') with bounds (2)) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_s defined in file src/libAtoms/Dictionary.f95.

add_array(key, value, len[, overwrite])
Parameters:
  • key (input string(len=-1)) –
  • value (input float) –
  • len (input int) –
  • overwrite (input int, optional) –

Routine is wrapper around Fortran routine dictionary_add_array_r defined in file src/libAtoms/Dictionary.f95.

assignment(from)

Make a deep copy of from in this, allocating new memory for array components; no error passing, for the assignment operator

Parameters:
from : Dictionary object

References

Routine is wrapper around Fortran routine deepcopy_no_error defined in file src/libAtoms/Dictionary.f95.

deepcopy(from[, error])

Make a deep copy of from in this, allocating new memory for array components

Parameters:
from : Dictionary object
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine deepcopy defined in file src/libAtoms/Dictionary.f95.

deepcopy_no_error(from)

Make a deep copy of from in this, allocating new memory for array components; no error passing, for the assignment operator

Parameters:
from : Dictionary object

References

Routine is wrapper around Fortran routine dictionary_deepcopy_no_error defined in file src/libAtoms/Dictionary.f95.

expand_string(in[, error])

Copy extendable string from in to out, expanding variables formatted as \:math:`KEY or \`\{KEY\} using values in this Dictionary. An error is raised if a key is not found, or if the string ends with a dollar sign or braces aren’t matched

Parameters:
in : Extendable_str object
error : in/output rank-0 array(int,’i’), optional
Returns:
out : Extendable_str object

References

Routine is wrapper around Fortran routine expand_string defined in file src/libAtoms/Dictionary.f95.

get_array(key)[source]

Return a _reference_ to an array stored in this Dictionary

get_key(i[, error])
Parameters:
i : input int
error : in/output rank-0 array(int,’i’), optional
Returns:
key : string(len=1024)

References

Routine is wrapper around Fortran routine dictionary_get_key defined in file src/libAtoms/Dictionary.f95.

get_type(key)[source]

Return an integer code for the type of the value associated with a key

get_type_and_size(key[, error])
Parameters:
key : input string(len=-1)
type : int
thesize : int
thesize2 : rank-1 array(‘i’) with bounds (2)
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine dictionary_get_type_and_size defined in file src/libAtoms/Dictionary.f95.

get_value(k)[source]

Return a _copy_ of a value stored in Dictionary

has_key(key)[source]

Return true if key is in Dictionary or false if not

Parameters:
key : input string(len=-1)
case_sensitive : input int, optional
Returns:
ret_dictionary_has_key : int

References

Routine is wrapper around Fortran routine has_key defined in file src/libAtoms/Dictionary.f95.

keys()[source]

array of keys

lookup_entry_i(key[, case_sensitive])

OMIT

Parameters:
key : input string(len=-1)
case_sensitive : input int, optional
Returns:
ret_lookup_entry_i : int

References

Routine is wrapper around Fortran routine lookup_entry_i defined in file src/libAtoms/Dictionary.f95.

print_([verbosity, file])

Print a DictEntry or a Dictionary

Parameters:
verbosity : input int, optional
file : InOutput object, optional

References

Routine is wrapper around Fortran routine print_ defined in file src/libAtoms/Dictionary.f95.

print_keys([verbosity, file])

dictionary_print_keys([verbosity,file])

Parameters:
verbosity : input int, optional
file : InOutput object, optional

References

Routine is wrapper around Fortran routine print_keys defined in file src/libAtoms/Dictionary.f95.

read_string(str[, append, error])

Read into this dictionary from a string

Parameters:
str : input string(len=-1)
append : input int, optional

If true, append to dictionary (default false)

error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine read_string defined in file src/libAtoms/Dictionary.f95.

remove_value(key)

Remove an entry from a Dictionary

Parameters:
key : input string(len=-1)

References

Routine is wrapper around Fortran routine remove_value defined in file src/libAtoms/Dictionary.f95.

set_value(*args, **kwargs)

Set a value in a Dictionary

Wrapper around Fortran interface set_value containing multiple routines:

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-1 array('i') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine dictionary_set_value_l_a defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (Extendable_str object) –

Routine is wrapper around Fortran routine dictionary_set_value_s_es defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-3 array('S') with bounds (qp_n0,qp_n1,(1))) –

Routine is wrapper around Fortran routine dictionary_set_value_s_a2 defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-1 array('D') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine dictionary_set_value_c_a defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-1 array('i') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine dictionary_set_value_i_a defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-2 array('d') with bounds (qp_n0,qp_n1)) –

Routine is wrapper around Fortran routine dictionary_set_value_r_a2 defined in file src/libAtoms/Dictionary.f95.

set_value(key)
Parameters:key (input string(len=-1)) –

Routine is wrapper around Fortran routine dictionary_set_value_none defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-1 array('d') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine dictionary_set_value_r_a defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input string(len=-1)) –

Routine is wrapper around Fortran routine dictionary_set_value_s defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-2 array('S') with bounds (qp_n0,(*))) –

Routine is wrapper around Fortran routine dictionary_set_value_s_a defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input int) –

Routine is wrapper around Fortran routine dictionary_set_value_l defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input rank-2 array('i') with bounds (qp_n0,qp_n1)) –

Routine is wrapper around Fortran routine dictionary_set_value_i_a2 defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (Dictionary object) –

Routine is wrapper around Fortran routine dictionary_set_value_dict defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input int) –

Routine is wrapper around Fortran routine dictionary_set_value_i defined in file src/libAtoms/Dictionary.f95.

set_value(key, value)
Parameters:
  • key (input string(len=-1)) –
  • value (input float) –

Routine is wrapper around Fortran routine dictionary_set_value_r defined in file src/libAtoms/Dictionary.f95.

set_value_pointer(*args, **kwargs)

Wrapper around Fortran interface set_value_pointer containing multiple routines:

set_value_pointer(key, ptr)
Parameters:
  • key (input string(len=-1)) –
  • ptr (input rank-1 array('i') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine dictionary_set_value_pointer_i defined in file src/libAtoms/Dictionary.f95.

set_value_pointer(key, ptr)
Parameters:
  • key (input string(len=-1)) –
  • ptr (input rank-1 array('i') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine dictionary_set_value_pointer_l defined in file src/libAtoms/Dictionary.f95.

set_value_pointer(key, ptr)
Parameters:
  • key (input string(len=-1)) –
  • ptr (input rank-1 array('D') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine dictionary_set_value_pointer_c defined in file src/libAtoms/Dictionary.f95.

set_value_pointer(key, ptr)
Parameters:
  • key (input string(len=-1)) –
  • ptr (input rank-1 array('d') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine dictionary_set_value_pointer_r defined in file src/libAtoms/Dictionary.f95.

set_value_pointer(key, ptr)
Parameters:
  • key (input string(len=-1)) –
  • ptr (input rank-2 array('i') with bounds (qp_n0,qp_n1)) –

Routine is wrapper around Fortran routine dictionary_set_value_pointer_i2 defined in file src/libAtoms/Dictionary.f95.

set_value_pointer(key, ptr)
Parameters:
  • key (input string(len=-1)) –
  • ptr (input rank-2 array('d') with bounds (qp_n0,qp_n1)) –

Routine is wrapper around Fortran routine dictionary_set_value_pointer_r2 defined in file src/libAtoms/Dictionary.f95.

set_value_pointer(key, ptr)
Parameters:
  • key (input string(len=-1)) –
  • ptr (input rank-3 array('S') with bounds (qp_n0,qp_n1,(1))) –

Routine is wrapper around Fortran routine dictionary_set_value_pointer_s defined in file src/libAtoms/Dictionary.f95.

subset(keys, out=None, case_sensitive=None, out_no_initialise=None)[source]

dictionary_subset(keys,out,[case_sensitive,out_no_initialise,error])

Parameters:
keys : input rank-2 array(‘S’) with bounds (qp_n0,(*))
out : Dictionary object
case_sensitive : input int, optional
out_no_initialise : input int, optional
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine subset defined in file src/libAtoms/Dictionary.f95.

swap(key1, key2[, case_sensitive, error])

Swap the positions of two entries in the dictionary. Arrays are not moved in memory.

Parameters:
key1 : input string(len=-1)
key2 : input string(len=-1)
case_sensitive : input int, optional
error : in/output rank-0 array(int,’i’), optional

References

Routine is wrapper around Fortran routine swap defined in file src/libAtoms/Dictionary.f95.

write_string([real_format, entry_sep, char_a_sep, quote_char, error])

Write a string representation of this dictionary

Parameters:
real_format : input string(len=-1), optional

Output format for reals, default is f9.3

entry_sep : input string(len=1), optional

Entry seperator, default is single space

char_a_sep : input string(len=1), optional

Output separator for character arrays, default is ,

quote_char : input string(len=1), optional

Character to use to quote output fields containing whitespace, default is "

error : in/output rank-0 array(int,’i’), optional
Returns:
ret_dictionary_write_string : string(len=10240)

References

Routine is wrapper around Fortran routine write_string defined in file src/libAtoms/Dictionary.f95.

cache_invalid

non-zero on exit from set_value(), set_value_pointer(), add_array(), remove_entry() if any array memory locations changed

key_cache_invalid

non-zero on exit from set_value(), set_value_pointer(), add_array(), remove_entry() if any keys changed

n

number of entries in use

quippy.dictionary.bcast(*args, **kwargs)

Routine is wrapper around Fortran interface bcast containing multiple routines:

quippy.dictionary.bcast(mpi, dict[, error])
Parameters:

Routine is wrapper around Fortran routine dictionary_bcast defined in file src/libAtoms/Dictionary.f95.

quippy.dictionary.bcast(mpi, at[, test_out, error])
Parameters:
  • mpi (MPI_context object) –
  • at (Atoms object) –
  • test_out (Atoms object, optional) –
  • error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine atoms_bcast defined in file src/libAtoms/Atoms_types.f95.