Fortran Table for dynamically extendable arrays

A Table is an extensible 2D array of integers, reals, strings and logicals. The lengths of all rows are the same and the number of rows will grow and shrink as datais appended or deleted. Extra columns can also be appended, although this is envisaged to be required less often. Any of the number of integers, number of reals, number of strings and number of logicals can be zero

Integers are referenced by table.int

Reals are referenced by table.real

Strings are referenced by table.str

Logicals are referenced by table.logical

Appending to the table is through the append interface.

Module contents for quippy.table:

Classes

Table(…)
Parameters:

Attributes

Name Value
TABLE_STRING_LENGTH 10
class quippy.table.Table([nint, nreal, nstr, nlogical, max_length, error])[source]

Bases: quippy._table.Table

Parameters:
nint : input int, optional

Number of integer columns

nreal : input int, optional

Number of real columns

nstr : input int, optional

Number of string columns

nlogical : input int, optional

Number of logical columns

max_length : input int, optional

Number of rows to initially allocate

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

References

Routine is wrapper around Fortran routine table_allocate defined in file src/libAtoms/Table.f95. Class is wrapper around Fortran type Table defined in file src/libAtoms/Table.f95.

Attributes:
increment

How many rows to grow the table by on reallocation (default 1000)

int

(intsize,N) array of integer data

intsize

Number of integer columns

logical

(logicalsize,N) array of logical data

logicalsize

Number of logical columns

max_length

Initial maximum length of the table before the first reallocation (default 100)

n

Number of rows

real

(realsize,N) array of real data

realsize

Number of real columns

str

(strsize,N) array of string data

strsize

Number of string columns

Methods

allocate(…) Allocate a Table.
append(*args, **kwargs) Append rows to a table.
append_column(*args, **kwargs) Append 1 or more columns to a table.
delete(*args, **kwargs) Delete a row by index or by value.
delete_multiple(indices) Delete multiple rows from a Table.
find(*args, **kwargs) Search the integer part of a table for a given element or array.
from_atom_indices(atoms[, mask, list, …]) Construct a new Table containing atomic indices from a list or mask
from_atom_list(atoms, list[, …]) Construct a new Table from a list of atom indices
from_atom_mask(atoms, mask[, …]) Construct a new Table from an atom mask
insert(…) insert a row at a given position
int_part(*args, **kwargs) Utility function to return one or more columns from the integer part of a table.
int_subtable(rows,cols)
Parameters:
is_same_fortran_object(other) Test if self and other point to the same Fortan object.
logical_part(*args, **kwargs) Wrapper around Fortran interface logical_part containing multiple routines:
print_(*args, **kwargs) Print this table to the mainlog or to an inoutput object.
real_part(*args, **kwargs) Utility function to return one or more columns from the real part of a table.
record_delete_multiple(indices)
Parameters:
remove_columns(…) remove a range of columns from a table’s int or real parts
search(intpart) Do a binary search (faster than find) on a pre-sorted table
select(to,from,[row_mask,row_list]) Select certains rows from a table based on a mask
set_increment(increment) Change the increment for this table.
shallow_copy() Return a shallow copy of self.
shallow_copy_from(other) Transform self into a shallow copy of other.
sort([idx,int_cols]) Sort a table according to its int part
str_part(*args, **kwargs) Wrapper around Fortran interface str_part containing multiple routines:
subtable(…)
Parameters:
to_atom_list([atoms]) Return list of atom indices that this Table represents.
to_atom_mask([atoms]) Return mask for atom indices that this Table represents
wipe([zero]) Clear this table, but keep the allocation.
allocate([nint, nreal, nstr, nlogical, max_length, error])

Allocate a Table. When allocating a table, you can optionally specify the number of integer and real columns and the initial amount of space to allocate (max_length). If a table is unallocated when append is called for the first time it will be allocated accordingly.

Parameters:
nint : input int, optional

Number of integer columns

nreal : input int, optional

Number of real columns

nstr : input int, optional

Number of string columns

nlogical : input int, optional

Number of logical columns

max_length : input int, optional

Number of rows to initially allocate

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

References

Routine is wrapper around Fortran routine __init__allocate defined in file src/libAtoms/Table.f95.

append(*args, **kwargs)

Append rows to a table. Overloaded to be able to append single elements, arrays or other tables.

Wrapper around Fortran interface append containing multiple routines:

append(intpart, realpart)
Parameters:
  • intpart (input int) –
  • realpart (input rank-1 array('d') with bounds (qp_n0)) –

Routine is wrapper around Fortran routine table_append_int_element_real_row defined in file src/libAtoms/Table.f95.

append(intpart[, error])
Parameters:
  • intpart (input int) –
  • error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine table_append_int_element defined in file src/libAtoms/Table.f95.

append(intpart, realpart)
Parameters:
  • intpart (input rank-1 array('i') with bounds (qp_n0)) –
  • realpart (input float) –

Routine is wrapper around Fortran routine table_append_int_row_real_element defined in file src/libAtoms/Table.f95.

append(intpart)
Parameters:intpart (input rank-2 array('i') with bounds (qp_n0,qp_n1)) –

Routine is wrapper around Fortran routine table_append_int_array defined in file src/libAtoms/Table.f95.

append(realpart)
Parameters:realpart (input float) –

Routine is wrapper around Fortran routine table_append_real_element defined in file src/libAtoms/Table.f95.

append(other)
Parameters:other (table object) –

Routine is wrapper around Fortran routine table_append_table defined in file src/libAtoms/Table.f95.

append(strpart)
Parameters:strpart (input rank-3 array('S') with bounds (qp_n0,qp_n1,(10))) –

Routine is wrapper around Fortran routine table_append_str_array defined in file src/libAtoms/Table.f95.

append(logicalpart)
Parameters:logicalpart (input rank-2 array('i') with bounds (qp_n0,qp_n1)) –

Routine is wrapper around Fortran routine table_append_logical_array defined in file src/libAtoms/Table.f95.

append(strpart[, error])
Parameters:
  • strpart (input string(len=-1)) –
  • error (in/output rank-0 array(int,'i'), optional) –

Routine is wrapper around Fortran routine table_append_str_element defined in file src/libAtoms/Table.f95.

append(logicalpart)
Parameters:logicalpart (input int) –

Routine is wrapper around Fortran routine table_append_logical_element defined in file src/libAtoms/Table.f95.

append(realpart)
Parameters:realpart (input rank-2 array('d') with bounds (qp_n0,qp_n1)) –

Routine is wrapper around Fortran routine table_append_real_array defined in file src/libAtoms/Table.f95.

append([intpart, realpart, strpart, logicalpart, intpart_2d, realpart_2d, strpart_2d, logicalpart_2d, blank_rows])
Parameters:
  • intpart (input rank-1 array('i') with bounds (qp_n0), optional) –
  • realpart (input rank-1 array('d') with bounds (qp_n1), optional) –
  • strpart (input rank-2 array('S') with bounds (qp_n2,(10)), optional) –
  • logicalpart (input rank-1 array('i') with bounds (qp_n3), optional) –
  • intpart_2d (input rank-2 array('i') with bounds (qp_n4,qp_n5), optional) –
  • realpart_2d (input rank-2 array('d') with bounds (qp_n6,qp_n7), optional) –
  • strpart_2d (input rank-3 array('S') with bounds (qp_n8,qp_n9,(10)), optional) –
  • logicalpart_2d (input rank-2 array('i') with bounds (qp_n10,qp_n11), optional) –
  • blank_rows (input int, optional) –

Routine is wrapper around Fortran routine table_append_row_or_arrays defined in file src/libAtoms/Table.f95.

append(intpart, realpart)
Parameters:
  • intpart (input int) –
  • realpart (input float) –

Routine is wrapper around Fortran routine table_append_int_element_and_real_element defined in file src/libAtoms/Table.f95.

append_column(*args, **kwargs)

Append 1 or more columns to a table. Overloaded to be able to append a scalar, 1-D array (must match N rows), or other tables (must match N rows)

Wrapper around Fortran interface append_column containing multiple routines:

append_column(val[, n_cols, cols])
Parameters:
  • val (input int) –
  • n_cols (input int, optional) –
  • cols (in/output rank-1 array('i') with bounds (2), optional) –

Routine is wrapper around Fortran routine table_append_col_i defined in file src/libAtoms/Table.f95.

append_column(val[, n_cols, cols])
Parameters:
  • val (input int) –
  • n_cols (input int, optional) –
  • cols (in/output rank-1 array('i') with bounds (2), optional) –

Routine is wrapper around Fortran routine table_append_col_l defined in file src/libAtoms/Table.f95.

append_column(val[, n_cols, cols])
Parameters:
  • val (input string(len=10)) –
  • n_cols (input int, optional) –
  • cols (in/output rank-1 array('i') with bounds (2), optional) –

Routine is wrapper around Fortran routine table_append_col_s defined in file src/libAtoms/Table.f95.

append_column(val[, n_cols, cols])
Parameters:
  • val (input float) –
  • n_cols (input int, optional) –
  • cols (in/output rank-1 array('i') with bounds (2), optional) –

Routine is wrapper around Fortran routine table_append_col_r defined in file src/libAtoms/Table.f95.

append_column(val_a[, n_cols, cols])
Parameters:
  • val_a (input rank-2 array('S') with bounds (qp_n0,(10))) –
  • n_cols (input int, optional) –
  • cols (in/output rank-1 array('i') with bounds (2), optional) –

Routine is wrapper around Fortran routine table_append_col_s_a defined in file src/libAtoms/Table.f95.

append_column(val_a[, n_cols, cols])
Parameters:
  • val_a (input rank-1 array('i') with bounds (qp_n0)) –
  • n_cols (input int, optional) –
  • cols (in/output rank-1 array('i') with bounds (2), optional) –

Routine is wrapper around Fortran routine table_append_col_i_a defined in file src/libAtoms/Table.f95.

append_column(other)
Parameters:other (Table object) –

Routine is wrapper around Fortran routine table_append_col_table defined in file src/libAtoms/Table.f95.

append_column(val_a[, n_cols, cols])
Parameters:
  • val_a (input rank-1 array('d') with bounds (qp_n0)) –
  • n_cols (input int, optional) –
  • cols (in/output rank-1 array('i') with bounds (2), optional) –

Routine is wrapper around Fortran routine table_append_col_r_a defined in file src/libAtoms/Table.f95.

append_column(val_a[, n_cols, cols])
Parameters:
  • val_a (input rank-1 array('i') with bounds (qp_n0)) –
  • n_cols (input int, optional) –
  • cols (in/output rank-1 array('i') with bounds (2), optional) –

Routine is wrapper around Fortran routine table_append_col_l_a defined in file src/libAtoms/Table.f95.

delete(*args, **kwargs)

Delete a row by index or by value. If by value then the match is made by the integer part of the table. The last row is copied over the row to be deleted, so the order of rows is not maintained.

Wrapper around Fortran interface delete containing multiple routines:

delete(n[, keep_order])
Parameters:
  • n (input int) –
  • keep_order (input int, optional) –

Routine is wrapper around Fortran routine table_record_delete_by_index defined in file src/libAtoms/Table.f95.

delete(n[, keep_order])
Parameters:
  • n (input rank-1 array('i') with bounds (n0)) –
  • keep_order (input int, optional) –

Routine is wrapper around Fortran routine table_record_delete_by_value defined in file src/libAtoms/Table.f95.

delete_multiple(indices)

Delete multiple rows from a Table. Beware, the order of rows is not maintained.

Parameters:
indices : input rank-1 array(‘i’) with bounds (qp_n0)

References

Routine is wrapper around Fortran routine record_delete_multiple defined in file src/libAtoms/Table.f95.

find(*args, **kwargs)

Search the integer part of a table for a given element or array.

Wrapper around Fortran interface find containing multiple routines:

find(n[, mask])
Parameters:
  • n (input rank-1 array('i') with bounds (n0)) –
  • mask (input rank-1 array('i') with bounds (qp_n1), optional) –
Returns:

ret_i – int

Routine is wrapper around Fortran routine table_find_row defined in file src/libAtoms/Table.f95.

find(n)
Parameters:n (input int) –
Returns:ret_i – int

Routine is wrapper around Fortran routine table_find_element defined in file src/libAtoms/Table.f95.

classmethod from_atom_indices(atoms, mask=None, list=None, force_fortran_indexing=True)[source]

Construct a new Table containing atomic indices from a list or mask

The new table will include 4 integer columns, for indices plus shifts, and is suitable for passing to bfs_step, construct_hysteretic_region, etc.

If force_fortran_indexing is True (the default), all atom indices are converted to Fortran 1-based indexing.

classmethod from_atom_list(atoms, list, force_fortran_indexing=True)[source]

Construct a new Table from a list of atom indices

See Table.from_atom_indices for more details.

classmethod from_atom_mask(atoms, mask, force_fortran_indexing=True)[source]

Construct a new Table from an atom mask

See Table.from_atom_indices for more details.

insert(pos[, intpart, realpart, strpart, logicalpart])

insert a row at a given position

Parameters:
pos : input int
intpart : input rank-1 array(‘i’) with bounds (qp_n0), optional
realpart : input rank-1 array(‘d’) with bounds (qp_n1), optional
strpart : input rank-2 array(‘S’) with bounds (qp_n2,(10)), optional
logicalpart : input rank-1 array(‘i’) with bounds (qp_n3), optional

References

Routine is wrapper around Fortran routine insert defined in file src/libAtoms/Table.f95.

int_part(*args, **kwargs)

Utility function to return one or more columns from the integer part of a table. Since this is a function the array may be returned on the stack, so be careful when working with large tables — the same goes for the ‘real_part’ interface below.

Wrapper around Fortran interface int_part containing multiple routines:

int_part(column, n0)
Parameters:
  • column (input int) –
  • n0 (input int) – shape(qp_ret_table_int_column,0)
Returns:

ret_table_int_column – rank-1 array(‘i’) with bounds (qp_n0)

Routine is wrapper around Fortran routine table_int_column defined in file src/libAtoms/Table.f95.

int_part(n0, n1)
Parameters:
  • n0 (input int) – shape(qp_ret_table_int_part,0)
  • n1 (input int) – shape(qp_ret_table_int_part,1)
Returns:

ret_table_int_part – rank-2 array(‘i’) with bounds (qp_n0,qp_n1)

Routine is wrapper around Fortran routine table_int_part defined in file src/libAtoms/Table.f95.

int_part(columns, n1)
Parameters:
  • columns (input rank-1 array('i') with bounds (qp_n0)) –
  • n1 (input int) – shape(qp_ret_table_int_columns,0)
Returns:

ret_table_int_columns – rank-2 array(‘i’) with bounds (size(qp_columns),qp_n1)

Routine is wrapper around Fortran routine table_int_columns defined in file src/libAtoms/Table.f95.

int_subtable(rows, cols)
Parameters:
rows : input rank-1 array(‘i’) with bounds (qp_n0)
cols : input rank-1 array(‘i’) with bounds (qp_n1)
Returns:
ret_int_subtable : Table object

References

Routine is wrapper around Fortran routine int_subtable defined in file src/libAtoms/Table.f95.

logical_part(*args, **kwargs)

Wrapper around Fortran interface logical_part containing multiple routines:

logical_part(n0, n1)
Parameters:
  • n0 (input int) – shape(qp_ret_table_logical_part,0)
  • n1 (input int) – shape(qp_ret_table_logical_part,1)
Returns:

ret_table_logical_part – rank-2 array(‘i’) with bounds (qp_n0,qp_n1)

Routine is wrapper around Fortran routine table_logical_part defined in file src/libAtoms/Table.f95.

logical_part(columns, n1)
Parameters:
  • columns (input rank-1 array('i') with bounds (qp_n0)) –
  • n1 (input int) – shape(qp_ret_table_logical_columns,0)
Returns:

ret_table_logical_columns – rank-2 array(‘i’) with bounds (size(qp_columns),qp_n1)

Routine is wrapper around Fortran routine table_logical_columns defined in file src/libAtoms/Table.f95.

logical_part(column, n0)
Parameters:
  • column (input int) –
  • n0 (input int) – shape(qp_ret_table_logical_column,0)
Returns:

ret_table_logical_column – rank-1 array(‘i’) with bounds (qp_n0)

Routine is wrapper around Fortran routine table_logical_column defined in file src/libAtoms/Table.f95.

print_(*args, **kwargs)

Print this table to the mainlog or to an inoutput object.

Wrapper around Fortran interface print_ containing multiple routines:

print(file[, verbosity, real_format, int_format, str_format, logical_format, mask])
Parameters:
  • verbosity (input int, optional) –
  • file (InOutput object) –
  • real_format (input string(len=-1), optional) –
  • int_format (input string(len=-1), optional) –
  • str_format (input string(len=-1), optional) –
  • logical_format (input string(len=-1), optional) –
  • mask (input rank-1 array('i') with bounds (qp_n0), optional) –

Routine is wrapper around Fortran routine table_print defined in file src/libAtoms/Table.f95.

print([verbosity])
Parameters:verbosity (input int, optional) –

Routine is wrapper around Fortran routine table_print_mainlog defined in file src/libAtoms/Table.f95.

real_part(*args, **kwargs)

Utility function to return one or more columns from the real part of a table.

Wrapper around Fortran interface real_part containing multiple routines:

real_part(columns, n1)
Parameters:
  • columns (input rank-1 array('i') with bounds (qp_n0)) –
  • n1 (input int) – shape(qp_ret_table_real_columns,0)
Returns:

ret_table_real_columns – rank-2 array(‘d’) with bounds (size(qp_columns),qp_n1)

Routine is wrapper around Fortran routine table_real_columns defined in file src/libAtoms/Table.f95.

real_part(n0, n1)
Parameters:
  • n0 (input int) – shape(qp_ret_table_real_part,0)
  • n1 (input int) – shape(qp_ret_table_real_part,1)
Returns:

ret_table_real_part – rank-2 array(‘d’) with bounds (qp_n0,qp_n1)

Routine is wrapper around Fortran routine table_real_part defined in file src/libAtoms/Table.f95.

real_part(column, n0)
Parameters:
  • column (input int) –
  • n0 (input int) – shape(qp_ret_table_real_column,0)
Returns:

ret_table_real_column – rank-1 array(‘d’) with bounds (qp_n0)

Routine is wrapper around Fortran routine table_real_column defined in file src/libAtoms/Table.f95.

record_delete_multiple(indices)
Parameters:
indices : input rank-1 array(‘i’) with bounds (qp_n0)

References

Routine is wrapper around Fortran routine table_record_delete_multiple defined in file src/libAtoms/Table.f95.

remove_columns([int_col_min, int_col_max, real_col_min, real_col_max, str_col_min, str_col_max, logical_col_min, logical_col_max])

remove a range of columns from a table’s int or real parts

Parameters:
int_col_min : input int, optional
int_col_max : input int, optional
real_col_min : input int, optional
real_col_max : input int, optional
str_col_min : input int, optional
str_col_max : input int, optional
logical_col_min : input int, optional
logical_col_max : input int, optional

References

Routine is wrapper around Fortran routine remove_columns defined in file src/libAtoms/Table.f95.

search(intpart)

Do a binary search (faster than find) on a pre-sorted table

Parameters:
intpart : input rank-1 array(‘i’) with bounds (qp_n0)
Returns:
ret_index : int

References

Routine is wrapper around Fortran routine search defined in file src/libAtoms/Table.f95.

select(to, from[, row_mask, row_list])

Select certains rows from a table based on a mask

Parameters:
to : table object
from : table object
row_mask : input rank-1 array(‘i’) with bounds (qp_n0), optional
row_list : input rank-1 array(‘i’) with bounds (qp_n1), optional

References

Routine is wrapper around Fortran routine select defined in file src/libAtoms/Table.f95.

set_increment(increment)

Change the increment for this table.

Parameters:
increment : input int

References

Routine is wrapper around Fortran routine set_increment defined in file src/libAtoms/Table.f95.

sort([idx, int_cols])

Sort a table according to its int part

Parameters:
idx : in/output rank-1 array(‘i’) with bounds (qp_n0), optional
int_cols : input rank-1 array(‘i’) with bounds (qp_n1), optional

References

Routine is wrapper around Fortran routine sort defined in file src/libAtoms/Table.f95.

str_part(*args, **kwargs)

Wrapper around Fortran interface str_part containing multiple routines:

str_part(column, n0)
Parameters:
  • column (input int) –
  • n0 (input int) – shape(qp_ret_table_str_column,0)
Returns:

ret_table_str_column – rank-2 array(‘S’) with bounds (qp_n0,(10))

Routine is wrapper around Fortran routine table_str_column defined in file src/libAtoms/Table.f95.

str_part(columns, n1)
Parameters:
  • columns (input rank-1 array('i') with bounds (qp_n0)) –
  • n1 (input int) – shape(qp_ret_table_str_columns,0)
Returns:

ret_table_str_columns – rank-3 array(‘S’) with bounds (size(qp_columns),qp_n1,(10))

Routine is wrapper around Fortran routine table_str_columns defined in file src/libAtoms/Table.f95.

str_part(n0, n1)
Parameters:
  • n0 (input int) – shape(qp_ret_table_str_part,0)
  • n1 (input int) – shape(qp_ret_table_str_part,1)
Returns:

ret_table_str_part – rank-3 array(‘S’) with bounds (qp_n0,qp_n1,(10))

Routine is wrapper around Fortran routine table_str_part defined in file src/libAtoms/Table.f95.

subtable(rows[, intcols, realcols, strcols, logicalcols])
Parameters:
rows : input rank-1 array(‘i’) with bounds (qp_n0)
intcols : input rank-1 array(‘i’) with bounds (qp_n1), optional
realcols : input rank-1 array(‘i’) with bounds (qp_n2), optional
strcols : input rank-1 array(‘i’) with bounds (qp_n3), optional
logicalcols : input rank-1 array(‘i’) with bounds (qp_n4), optional
Returns:
ret_subtable : Table object

References

Routine is wrapper around Fortran routine subtable defined in file src/libAtoms/Table.f95.

to_atom_list(atoms=None)[source]

Return list of atom indices that this Table represents.

Indices returns are 0-based or 1-based depending on value of get_fortran_indexing().

If atoms is not present, the Atoms object passed to Table.from_atom_indices is used, or an exception is raised if this Table was not created in that way.

to_atom_mask(atoms=None)[source]

Return mask for atom indices that this Table represents

Result is either an array of an FortranArray, depending on value of get_fortran_indexing().

If atoms is not present, the Atoms object passed to Table.from_atom_indices is used, or an exception is raised if this Table was not created in that way.

wipe([zero])

Clear this table, but keep the allocation.

Parameters:
zero : input int, optional

References

Routine is wrapper around Fortran routine wipe defined in file src/libAtoms/Table.f95.

increment

How many rows to grow the table by on reallocation (default 1000)

int

(intsize,N) array of integer data

intsize

Number of integer columns

logical

(logicalsize,N) array of logical data

logicalsize

Number of logical columns

max_length

Initial maximum length of the table before the first reallocation (default 100)

n

Number of rows

real

(realsize,N) array of real data

realsize

Number of real columns

str

(strsize,N) array of string data

strsize

Number of string columns