pyCOFBuilder package

Detailed documentation of the submodules used on pyCOFBuilder.

Submodules

pycofbuilder.building_block module

The BuildingBlock class is used to create the building blocks for the Framework class.

class pycofbuilder.building_block.BuildingBlock(name: str = '', **kwargs)

Bases: object

add_R_group(R_name, R_type)

Adds group R in building blocks

add_connection_group(conector_name)

Adds the functional group by which the COF will be formed from the building blocks

add_connection_group_symm(conector_name)

Adds the functional group by which the COF will be formed from the building blocks

align_to(vec=[0, 1, 0], n: int = 0)

Align the first n-th X point to a given vector

Parameters:

• vec (list) – Vector to align the molecule

• n (int) – Index of the X point to be aligned

• align_to_y (bool) – If True, the second point is aligned to the y axis

calculate_size()

Calculate the size of the building block

centralize(by_X=True)

Centralize the molecule on its geometrical center

check_existence(name)

copy()

Return a deep copy of the BuildingBlock object

create_BB_structure(symmetry='L2', core_name='BENZ', conector='CHO', R1='H', R2='H', R3='H', R4='H', R5='H', R6='H', R7='H', R8='H', R9='H')

Create a building block

from_file(path, file_name)

Read a custom building block from a file.

Parameters:

• path (str) – Path to the file

• file_name (str) – Name of the file

from_name(name)

Automatically read or create a buiding block based on its name

get_Q_points(atom_types, atom_pos)

Get the Q points in a molecule

get_R_points(atom_types, atom_pos)

Get the R points in a molecule

get_X_points() → tuple

Get the X points in a molecule

get_available_R()

Get the list of available functional groups

get_available_conector()

Get the list of available conectores

get_available_core()

Get the list of available cores

get_buildingblock_list(shape, connector_group)

get_sizes()

Get the sizes of the building blocks

Returns:

List with the sizes of the building blocks

Return type:

list

property n_atoms

Returns the number of atoms in the unitary cell

print_structure()

Print the structure in xyz format: atom_label pos_x pos_y pos_z

remove_X()

replace_X(target_type)

rotate_around(rotation_axis: list | ndarray[tuple[Any, ...], dtype[_ScalarT]] = [1, 0, 0], angle: float = 0.0, degree: bool = True)

Rotate the molecule around a given axis

Parameters:

• rotation_axis (list) – Rotation axis

• angle (float) – Rotation angle in degrees

• degree (bool) – If True, the angle is given in degrees. Default is True.

rotate_to_xy_plane()

Rotate the molecule to the xy plane

save(extension='xyz')

shift(shift_vector: list)

Shift the molecule by a given vector

Parameters:

shift_vector (list) – Shift vector

structure_as_string()

to_ase()

Convert the building block to ASE atoms object

pycofbuilder.cjson module

The CJSON package implements functions to read, create and manipulate Chemical JSON objects.

class pycofbuilder.cjson.ChemJSON

Bases: object

Class to read, create and manupulate ChemJSON files.

file_name

The name of the file.

Type:

str

name

The name of the structure.

Type:

str

cell_parameters

The cell parameters of the structure as a (1,6) list.

Type:

list

cell_matrix

The cell matrix of the structure as a (3,3) list.

Type:

list

cartesian_positions

The cartesian positions of the structure as a (n,3) list.

Type:

list

fractional_positions

The fractional positions of the structure as a (n,3) list.

Type:

list

atomic_numbers

The atomic numbers of the structure as a (n,1) list.

Type:

list

atomic_types

The atomic types of the structure as a (n,1) list.

Type:

list

atomic_labels

The atomic labels of the structure as a (n,1) list.

Type:

list

formula

The formula of the structure.

Type:

str

properties

The properties of the structure.

Type:

dict

partial_charges

A dictionary contaning the partial charges of the atoms on the structure. Example: {‘DDEC’: [0.1, 0.2, 0.15], ‘EQeq’: [0.05, 0.15, 0.19]}

Type:

dict

as_dict() → dict

Returns the structure as a dictionary.

from_cif(path, file_name)

Reads a CIF file from a given path and file_name.

from_cjson(path, file_name)

Reads a ChemJSON file from a given path and file_name.

from_gjf(path, file_name)

Reads a Gaussian input file from a given path and file_name.

from_xyz(path, file_name)

Reads a XYZ file from a given path and file_name.

set_atomic_numbers(atomic_numbers)

Sets the atomic numbers of the structure. The atomic types and formula will be calculated and also updated.

set_atomic_types(atomic_types)

Sets the atomic labels of the structure.

set_bonds(bond_indexes: list[list], bond_orders: list = [None])

Sets the bonds of the structure.

Parameters:

• bond_indexes (list[list], required) – A list of lists containing the indexes of the atoms that are bonded. Example: [[0, 1], [1, 2], [2, 3]]

• bond_orders (list | None, optional) – A list of integers containing the bond orders of the bonds. Example: [1, 2, 1]

set_cartesian_positions(cartesian_positions)

Sets the cartesian positions of the structure. The fractional positions will be calculated and also updated.

set_cell_matrix(cell_matrix)

Sets the cell matrix of the structure. The cell parameters will be calculated and also updated.

set_cell_parameters(cell_parameters)

Sets the cell parameters of the structure.

set_fractional_positions(fractional_positions)

Sets the fractional positions of the structure. The cartesian positions will be calculated and also updated.

set_properties(properties: dict)

Sets the properties of the structure.

set_results(results)

Sets the results of the structure.

write_cjson(path, file_name)

Writes a ChemJSON file to a given path and file_name.

pycofbuilder.framework module

The Framework class implements definitions and methods for a Framework buiding

class pycofbuilder.framework.Framework(name: str | None = None, **kwargs)

Bases: object

A class used to represent a Covalent Organic Framework as a reticular entity.

…

name

Name of the material

Type:

str

out_dir

Path to save the results. If not defined, a out folder will be created in the current directory.

Type:

str

verbosity

Control the printing options. Can be ‘none’, ‘normal’, or ‘debug’. Default: ‘normal’

Type:

str

save_bb

Control the saving of the building blocks. Default: True

Type:

bool

lib_path

Path for saving the building block files. If not defined, a building_blocks folder will be created in the current directory.

Type:

str

topology

Type:

str = None

dimention

Type:

str = None

lattice

Type:

str = None

lattice_sgs

Type:

str = None

space_group

Type:

str = None

space_group_n

Type:

str = None

stacking

Type:

str = None

mass

Type:

str = None

composition

Type:

str = None

charge

Type:

int = 0

multiplicity

Type:

int = 1

chirality

Type:

bool = False

atom_types

Type:

list = []

atom_pos

Type:

list = []

lattice

Type:

list = [[], [], []]

symm_tol

Type:

float = 0.2

angle_tol

Type:

float = 0.2

dist_threshold

Type:

float = 0.8

available_2D_topologies

List of available 2D topologies

Type:

list

available_3D_topologies

List of available 3D topologies

Type:

list

available_topologies

List of all available topologies

Type:

list

available_stacking

List of available stakings for all 2D topologies

Type:

list

lib_bb

String with the name of the folder containing the building block files Default: bb_lib

Type:

str

as_string() → str

Returns a string with the Framework information.

check_name_concistency(FrameworkName) → tuple[str, str, str, str]

Checks if the name is in the correct format and returns a tuple with the building blocks names, the net and the stacking.

In case the name is not in the correct format, an error is raised.

Parameters:

FrameworkName (str, required) – The name of the COF to be created

Returns:

A tuple with the building blocks names, the net and the stacking.

Return type:

tuple[str, str, str, str]

create_bor_structure(BB_D4: str, BB_T3: str, interp_dg: str = '1', d_param_base: float = 7.2, print_result: bool = True, **kwargs)

Creates a COF with BOR network.

The BOR net is composed of one tetrapodal tetrahedical building block and one tripodal triangular building block.

Parameters:

• BB_D4 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• BB_T3 (BuildingBlock, required) – The BuildingBlock object of the tripodal triangular Buiding Block

• interp_dg (str, optional) – The degree of interpenetration of the framework (default is ‘1’)

• d_param_base (float, optional) – The base value for interlayer distance in angstroms (default is 7.2)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_dia_a_structure(BB_D4: str, BB_L2: str, interp_dg: str = '1', d_param_base: float = 7.2, print_result: bool = True, **kwargs)

Creates a COF with DIA-A network.

The DIA net is composed of two tetrapodal tetrahedical building blocks.

Parameters:

• BB_D4 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the dipodal linear Buiding Block

• interp_dg (str, optional) – The degree of interpenetration of the framework (default is ‘1’)

• d_param_base (float, optional) – The base value for interlayer distance in angstroms (default is 7.2)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_dia_structure(BB_D41: str, BB_D42: str, interp_dg: str = '1', d_param_base: float = 7.2, print_result: bool = True, **kwargs)

Creates a COF with DIA network.

The DIA net is composed of two tetrapodal tetrahedical building blocks.

Parameters:

• BB_D41 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• BB_D42 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• interp_dg (str, optional) – The degree of interpenetration of the framework (default is ‘1’)

• d_param_base (float, optional) – The base value for interlayer distance in angstroms (default is 7.2)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_fxt_a_structure(BB_S4: str, BB_L2: str, stacking: str = 'AA', c_parameter_base: float = 3.6, print_result: bool = True, slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with FXT-A network.

The FXT-A net is composed of one tetrapodal and one linear building blocks.

Parameters:

• BB_S4 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the bipodal Buiding Block

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_fxt_structure(BB_R4_A: BuildingBlock, BB_R4_B: BuildingBlock, stacking: str = 'AA', print_result: bool = True, slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0.0), tilt_angle: float = 5.0)

Creates a COF with FXT network.

The FXT net is composed of two tetrapodal building blocks.

Parameters:

• BB_R4_A (BuildingBlock, required) – The BuildingBlock object of the rectangular tetrapodal Buiding Block A

• BB_R4_B (BuildingBlock, required) – The BuildingBlock object of the rectangular tetrapodal Buiding Block B

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0.0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_hcb_a_structure(BB_T3: str, BB_L2: str, stacking: str = 'AA', slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with HCB-A network.

The HCB-A net is composed of one tripodal and one linear building blocks.

Parameters:

• BB_T3 (BuildingBlock, required) – The BuildingBlock object of the tripodal Buiding Block

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the linear Buiding Block

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• c_parameter_base (float, optional) – The base value for interlayer distance in angstroms (default is 3.6)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name

2. lattice type

3. hall symbol of the cristaline structure

4. space group

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_hcb_structure(BB_T3_A, BB_T3_B, stacking: str = 'AA', slab: float = 10.0, shift_vector: tuple = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with HCB network.

The HCB net is composed of two tripodal building blocks.

Parameters:

• BB_T3_1 (BuildingBlock, required) – The BuildingBlock object of the tripodal Buiding Block A

• BB_T3_2 (BuildingBlock, required) – The BuildingBlock object of the tripodal Buiding Block B

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (tuple, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_hxl_a_structure(BB_H6: str, BB_L2: str, stacking: str = 'AA', print_result: bool = True, slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with HXL-A network.

The HXL-A net is composed of one hexapodal and one linear building blocks.

Parameters:

• BB_H6 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block A

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block B

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_kgd_structure(BB_H6: str, BB_T3: str, stacking: str = 'AA', print_result: bool = True, slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with KGD network.

The KGD net is composed of one hexapodal and one tripodal building blocks.

Parameters:

• BB_H6 (BuildingBlock, required) – The BuildingBlock object of the hexapodal Buiding Block

• BB_T3 (BuildingBlock, required) – The BuildingBlock object of the tripodal Buiding Block

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• c_parameter_base (float, optional) – The base value for interlayer distance in angstroms (default is 3.6)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_lon_a_structure(BB_D4: BuildingBlock, BB_L2: BuildingBlock, interp_dg: str | int = 0, d_param_base: float = 10, print_result: bool = True, **kwargs)

Creates a COF with LON network.

The LON_A net is composed of one tetrapodal tetrahedical and one linear building blocks.

Parameters:

• BB_D4 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the dipodal linear Buiding Block

• interp_dg (str, optional) – The degree of interpenetration of the framework (default is ‘1’)

• d_param_base (float, optional) – The base value for interlayer distance in angstroms (default is 7.2)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_lon_structure(BB_D4_A: str, BB_D4_B: str, interp_dg: str = '1', d_param_base: float = 7.2, print_result: bool = True, **kwargs)

Creates a COF with LON network.

The LON net is composed of two tetrapodal tetrahedical building blocks.

Parameters:

• BB_D4_A (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• BB_D4_B (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• interp_dg (str, optional) – The degree of interpenetration of the framework (default is ‘1’)

• d_param_base (float, optional) – The base value for interlayer distance in angstroms (default is 7.2)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_sql_a_structure(BB_S4: str, BB_L2: str, stacking: str = 'AA', c_parameter_base: float = 3.6, slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with SQL-A network.

The SQL-A net is composed of one tetrapodal and one linear building blocks.

Parameters:

• BB_S4 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the bipodal Buiding Block

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_sql_structure(BB_A: str, BB_B: str, stacking: str = 'AA', slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with SQL network.

The SQL net is composed of two tetrapodal building blocks.

Parameters:

• BB_S4_A (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block A

• BB_S4_B (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block B

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

from_building_blocks(bb1: BuildingBlock, bb2: BuildingBlock, net: str, stacking: str, **kwargs)

Creates a COF from the building blocks.

Parameters:

• BB1 (BuildingBlock, required) – The first building block

• BB2 (BuildingBlock, required) – The second building block

• Net (str, required) – The network of the COF

• Stacking (str, required) – The stacking of the COF

Returns:

COF – The COF object

Return type:

Framework

from_name(FrameworkName, **kwargs) → None

Creates a COF from a given FrameworkName.

Parameters:

FrameworkName (str, required) – The name of the COF to be created

Returns:

COF – The COF object

Return type:

Framework

get_available_topologies(dimensionality: str = 'all', print_result: bool = True)

Get the available topologies implemented in the class.

Parameters:

• dimensionality (str, optional) – The dimensionality of the topologies to be printed. Can be ‘all’, ‘2D’ or ‘3D’. Default: ‘all’

• print_result (bool, optional) – If True, the available topologies are printed.

Returns:

dimensionality_list – A list with the available topologies.

Return type:

list

get_n_atoms() → int

Returns the number of atoms in the unitary cell

make_cubic(min_length=10, force_diagonal=False, force_90_degrees=True, min_atoms=None, max_atoms=None, angle_tolerance=0.001)

Transform the primitive structure into a supercell with alpha, beta, and gamma equal to 90 degrees. The algorithm will iteratively increase the size of the supercell until the largest inscribed cube’s side length is at least ‘min_length’ and the number of atoms in the supercell falls in the range min_atoms < n < max_atoms.

Parameters:

• min_length (float, optional) – Minimum length of the cubic cell (default is 10)

• force_diagonal (bool, optional) – If True, generate a transformation with a diagonal transformation matrix (default is False)

• force_90_degrees (bool, optional) – If True, force the angles to be 90 degrees (default is True)

• min_atoms (int, optional) – Minimum number of atoms in the supercell (default is None)

• max_atoms (int, optional) – Maximum number of atoms in the supercell (default is None)

• angle_tolerance (float, optional) – The angle tolerance for the transformation (default is 1e-3)

save(fmt: str = 'cif', supercell: tuple = (1, 1, 1), save_dir=None, primitive=False, save_bonds=True, save_labels=False) → None

Save the structure in a specif file format.

Parameters:

• fmt (str, optional) – The file format to be saved Can be json, cif, xyz, turbomole, vasp, xsf, pdb, pqr, qe. Default: ‘cif’

• supercell (tuple, optional) – The supercell to be used to save the structure. Default: [1,1,1]

• save_dir (str, optional) – The path to save the structure. By default, the structure is saved in a out folder created in the current directory.

• primitive (bool, optional) – If True, the primitive cell is saved. Otherwise, the conventional cell is saved. Default: False

• save_bonds (bool, optional) – If True, the bonds are saved in the structure. Default: True

• save_labels (bool, optional) – If True, the atom labels are saved in the structure. Default: False

to_ase()

Convert the framework to an ASE Atoms object.

pycofbuilder.io_tools module

This module contains tools for input and output file manipulation used by pyCOFBuilder.

pycofbuilder.io_tools.generate_mol_dict(path, file_name, name, code, smiles)

pycofbuilder.io_tools.read_cif(path, file_name, useASE=False, usePymatgen=False)

Reads a file in format .cif from the path given and returns a list containg the N atom labels and a Nx3 array contaning the atoms coordinates.

Parameters:

• path (str) – Path to the file.

• file_name (str) – Name of the cif file. Does not neet to contain the .cif extention.

• useASE (bool) – If True, the function will use ASE library to read the file.

• usePymatgen (bool) – If True, the function will use Pymatgen library to read the file.

Returns:

• atomTypes (list) – List of strings containing containg the N atom labels.

• cartPos (numpy array) – Nx3 array contaning the atoms coordinates

• cellMatrix (numpy array) – 3x3 array contaning the cell vectors.

• partialCharges (list) – List of floats containing the N atom partial charges.

pycofbuilder.io_tools.read_gjf(path, file_name) → tuple

Reads a file in format .gjf from the path given and returns a list containg the N atom labels and a Nx3 array contaning the atoms coordinates.

Parameters:

• path (str) – Path to the file.

• file_name (str) – Name of the gjf file. Does not neet to contain the .gjf extention.

Returns:

• atonTypes (list) – List of strings containing containg the N atom labels.

• cartPos (numpy array) – Nx3 array contaning the atoms coordinates

• cellMatrix (numpy array) – 3x3 array contaning the cell vectors.

pycofbuilder.io_tools.read_pdb(path, file_name)

Reads a file in format .pdb from the path given and returns a list containg the N atom labels and a Nx3 array contaning the atoms coordinates.

Parameters:

• path (str) – Path to the file.

• file_name (str) – Name of the pdb file. Does not neet to contain the .pdb extention.

Returns:

• atonTypes (list) – List of strings containing containg the N atom labels.

• cartPos (numpy array) – Nx3 array contaning the atoms coordinates

• cellMatrix (numpy array) – 3x3 array contaning the cell vectors.

pycofbuilder.io_tools.read_xyz(path: str, file_name: str, extxyz=False) → tuple

Reads a file in format .xyz from the given path and returns a list containg the N atom labels and a Nx3 array contaning the atoms coordinates.

Parameters:

• path (str) – Path to the file.

• file_name (str) – Name of the xyz file. Does not neet to contain the .xyz extention.

• extxyz (bool) – If True, the function will consider the extended xyz file format and use ase library to read the file.

Returns:

• atonTypes (list) – List of strings containing containg the N atom labels.

• cartPos (numpy array) – Nx3 array contaning the atoms coordinates

• cellMatrix (numpy array) – 3x3 array contaning the cell vectors.

pycofbuilder.io_tools.save_chemjson(path: str, file_name: str, cell: list, atomTypes: list, atomLabels: list, atomPos: list, partialCharges: list = [], bonds: list = [], frac_coords=False)

Save a file in format .json on the path.

Parameters:

• path (str) – Path to the save the file.

• file_name (str) – Name of the file. Does not neet to contain the extention.

• cell (numpy array) – Can be a 3x3 array contaning the cell vectors or a list with the 6 cell parameters.

• atomTypes (list) – List of strings containing containg the N atom types

• atomLabels (list) – List of strings containing containg the N atom labels

• atomPos (list) – Nx3 array contaning the atoms coordinates.

• partialCharges (list) – List of floats containing containg the N atom partial charges.

• bonds (list) – List of lists containing the index of the bonded atoms and the bond length.

• frac_coords (bool) – If True, the coordinates are in fractional coordinates.

pycofbuilder.io_tools.save_cif(path: str, file_name: str, atomTypes: list, atomPos: list, cell: list = [], atomLabels: list = [], partialCharges: list[float] = [], bonds: list = [], bondTypes: list = [], frac_coords=False, renormalize_charges=False, **kwargs) → None

Save a file in format .cif on the path.

Parameters:

• path (str) – Path to the save the file.

• file_name (str) – Name of the file. Does not neet to contain the extention.

• atomTypes (list) – List of strings containing containg the N atom types

• atomPos (list) – Nx3 array contaning the atoms coordinates.

• cell (numpy array) – Can be a 3x3 array contaning the cell vectors or a list with the 6 cell parameters.

• atomLabels (list) – List of strings containing containg the N atom labels

• partialCharges (list) – List of strings containing containg the N atom partial charges.

• bonds (list) – List of lists containing the index of the bonded atoms and the bond length.

• bondTypes (list) – List of strings containing the bond types. Can be singe (S), double (D), triple (T), or aromatic (A).

• frac_coords (bool) – If True, the coordinates are in fractional coordinates.

• renormalize_charges (bool) – If True, the charges will be renormalized to the total charge of the system.

pycofbuilder.io_tools.save_csv(path: str, file_name: str, data: list, delimiter: str = ',', head: list = []) → None

Saves a file in format .csv.

Parameters:

• path (str) – Path to the file.

• file_name (str) – Name of the csv file. Does not neet to contain the .csv extention.

• data (list) – Data to be saved.

• delimiter (str) – Delimiter of the columns. , is the default.

• head (list) – Names of the columns.

pycofbuilder.io_tools.save_gjf(path: str, file_name: str, atomTypes: list, atomPos: list, cell: list = [], frac_coords=False, **kwargs) → None

Save a file in format .gjf on the path.

Parameters:

• path (str) – Path to the save the file.

• file_name (str) – Name of the file. Does not neet to contain the extention.

• atomTypes (list) – List of strings containing containg the N atom types

• atomPos (list) – Nx3 array contaning the atoms coordinates.

• cell (list, optional) – Can be a 3x3 array contaning the cell vectors or a list with the 6 cell parameters.

• frac_coords (bool, optional) – If True, the coordinates are in fractional coordinates and will be converted to cartesian. Default is False.

pycofbuilder.io_tools.save_pdb(path: str, file_name: str, atomTypes: list, atomPos: list, cell: list = [], frac_coords=False, atomLabels: list = [], bonds: list = [], bond_orders: list = [], **kwargs) → None

Save a file in format .pdb on the path.

pathstr

Path to the save the file.

file_namestr

Name of the file. Does not neet to contain the extention.

atomTypeslist

List of strings containing containg the N atom types

atomPoslist

Nx3 array contaning the atoms coordinates.

celllist, optional

Can be a 3x3 array contaning the cell vectors or a list with the 6 cell parameters.

frac_coordsbool, optional

If True, the coordinates are in fractional coordinates and will be converted to cartesian. Default is False.

atomLabelslist, optional

List of strings containing containg the N atom labels.

bondslist, optional

List of lists containing the index of the bonded atoms and the bond length.

bond_orderslist, optional

List of integers containing the bond orders.

pycofbuilder.io_tools.save_pqr(path: str, file_name: str, atomTypes: list, atomPos: list, cell: list = [], partialCharges: list = [], frac_coords=False, atomLabels: list = [], bonds: list = [], bond_orders: list = []) → None

Save a file in format .pqr on the path.

Parameters:

• path (str) – Path to the save the file.

• file_name (str) – Name of the file. Does not neet to contain the extention.

• atomTypes (list) – List of strings containing containg the N atom types

• atomPos (list) – Nx3 array contaning the atoms coordinates.

• cell (list, optional) – Can be a 3x3 array contaning the cell vectors or a list with the 6 cell parameters.

• partialCharges (list, optional) – List of strings containing containg the N atom partial charges.

• frac_coords (bool, optional) – If True, the coordinates are in fractional coordinates and will be converted to cartesian. Default is False.

• atomLabels (list, optional) – List of strings containing containg the N atom labels.

• bonds (list, optional) – List of lists containing the index of the bonded atoms and the bond length.

• bond_orders (list, optional) – List of integers containing the bond orders.

pycofbuilder.io_tools.save_qe(path: str, file_name: str, cell: list, atomTypes: list, atomLabels: list, atomPos: list, frac_coords=False, calc_type: str = 'scf', kspacing: float = 0.3, **kwargs) → None

Save the structure in Quantum Espresso .pwscf format.

The input_dict can be used to specify the input parameters for the QuantumESPRESSO calculation.

This dictionary must contain the keys: control, system, electrons, and ions. Each of these keys must contain a dictionary with the corresponding input parameters. This dictionary can contain the kpoints item, with the kpoints grid as a list of 3 integers. Additionally, it can contain the kspacing item, with the kpoints spacing as a float. In this case the kpoints grid will be calculated automatically. By default, the kspacing is set to 0.3.

Parameters:

• path (str) – Path to the save the file.

• file_name (str) – Name of the file. Does not neet to contain the extention.

• cell (numpy array) – Can be a 3x3 array contaning the cell vectors or a list with the 6 cell parameters.

• atomTypes (list) – List of strings containing containg the N atom types

• atomLabels (list) – List of strings containing containg the N atom labels

• atomPos (list) – Nx3 array contaning the atoms coordinates.

• frac_coords (bool) – If True, the coordinates are in fractional coordinates.

• calc_type (str) – Type of calculation. Can be ‘scf’, ‘vc-relax’, ‘relax’, ‘md’, ‘vc-md’, ‘vc-tddft’, ‘tddft’.

• kspacing (float) – Kpoints spacing in 1/Angstrom.

pycofbuilder.io_tools.save_turbomole(path: str, file_name: str, atomTypes: list, atomPos: list, cell: list = [], frac_coords=False, **kwargs) → None

Save the structure in Turbomole .coord format on the path.

Parameters:

• path (str) – Path to the save the file.

• file_name (str) – Name of the file. Does not neet to contain the extention.

• atomTypes (list) – List of strings containing containg the N atom types

• atomPos (list) – Nx3 array contaning the atoms coordinates.

• cell (list, optional) – Can be a 3x3 array contaning the cell vectors or a list with the 6 cell parameters.

• frac_coords (bool, optional) – If True, the coordinates are in fractional coordinates and will be converted to cartesian. Default is False.

pycofbuilder.io_tools.save_vasp(path: str, file_name: str, atomTypes: list, atomPos: list, cell: list = [], frac_coords=False, **kwargs) → None

Save the structure in VASP .vasp format on the path.

Parameters:

• path (str) – Path to the save the file.

• file_name (str) – Name of the file. Does not neet to contain the extention.

• atomTypes (list) – List of strings containing containg the N atom types

• atomPos (list) – Nx3 array contaning the atoms coordinates.

• cell (list, optional) – Can be a 3x3 array contaning the cell vectors or a list with the 6 cell parameters.

• frac_coords (bool, optional) – If True, the coordinates are in fractional coordinates and will be converted to cartesian. Default is False.

pycofbuilder.io_tools.save_xsf(path: str, file_name: str, atomTypes: list, atomPos: list, cellMatrix: list, frac_coords=False, **kwargs)

Save a file in format .xsf on the path.

Parameters:

• path (str) – Path to the save the file.

• file_name (str) – Name of the file. Does not neet to contain the extention.

• atomTypes (list) – List of strings containing containg the N atom types

• atomPos (list) – Nx3 array contaning the atoms coordinates.

• cellMatrix (numpy array) – Can be a 3x3 array contaning the cell vectors or a list with the 6 cell parameters.

• frac_coords (bool) – If True, the coordinates are in fractional coordinates.

pycofbuilder.io_tools.save_xyz(path: str, file_name: str, atomTypes: list, atomPos: list, cell: list = [], partialCharges: list = [], frac_coords=False, **kwargs) → None

Save a file in format .pqr on the path.

Parameters:

• path (str) – Path to the save the file.

• file_name (str) – Name of the file. Does not neet to contain the extention.

• atomTypes (list) – List of strings containing containg the N atom types

• atomPos (list) – Nx3 array contaning the atoms coordinates.

• cell (list, optional) – Can be a 3x3 array contaning the cell vectors or a list with the 6 cell parameters.

• partialCharges (list, optional) – List of strings containing containg the N atom partial charges.

• frac_coords (bool, optional) – If True, the coordinates are in fractional coordinates and will be converted to cartesian. Default is False.

pycofbuilder.tools module

This module contains the tools used by pyCOFBuilder.

pycofbuilder.tools.angle(v1, v2, unit='degree') → float

Calculates the angle between two vectors v1 and v2.

Parameters:

• v1 (array) – (N,1) matrix with N dimensions

• v2 (array) – (N,1) matrix with N dimensions

• unit (str) – Unit of the output. Could be ‘degree’, ‘radians’ or ‘cos’.

Returns:

angle – Angle in the selected unit.

Return type:

float

pycofbuilder.tools.calculate_UnitCells(cell, cutoff) → tuple[int, int, int]

Calculate the number of unit cell repetitions so that all supercell lengths are larger than twice the interaction potential cut-off radius.

RASPA considers the perpendicular directions the directions perpendicular to the ab, bc, and ca planes. Thus, the directions depend on who the crystallographic vectors a, b, and c are and the length in the perpendicular directions would be the projections of the crystallographic vectors on the vectors a x b, b x c, and c x a. (here x means cross product)

Parameters:

cell_matrix (array) – (3,3) cell vectors or (6,1)

Returns:

(3,1) list containg the number of repiting units in x, y, z directions.

Return type:

superCell

pycofbuilder.tools.calculate_sides(points) → ndarray

Calculate the lengths of the sides of a geometric shape defined by a set of points in 3D space.

This function takes an array of 3D points and computes the unique side lengths of the shape formed by these points. The sides are calculated as the Euclidean distances between pairs of points.

Parameters:

pointsnumpy.ndarray

A 2D array of shape (n, 3), where n is the number of points. Each row represents the coordinates of a point (x, y, z).

Returns:

numpy.ndarray

A sorted array of unique side lengths of the geometric shape.

Raises:

ValueError

If the input is not a 2D numpy array with shape (n, 3).

Example:

>>> points = np.array([[0, 0, 0], [0, 2, 0], [2, 0, 0], [2, 2, 0]])
>>> calculate_sides(points)
array([2., 2.82842712])

pycofbuilder.tools.cell_to_cellpar(cell, radians=False) → ndarray

Returns the cell parameters [a, b, c, alpha, beta, gamma] given a 3x3 cell matrix.

Angles are in degrees unless radian=True is used.

Parameters:

• cell (array) – (3,3) matrix of cell vectors v1, v2, and v3

• radians (bool) – Return the cell angles in radians

Returns:

cellpar – (6,1) vector with the cell parameters

Return type:

array

pycofbuilder.tools.cell_to_ibrav(cell)

Return the ibrav number for a given cell.

pycofbuilder.tools.cellpar_to_cell(cellpar, ab_normal=(0, 0, 1), a_direction=None) → ndarray

Return a 3x3 cell matrix from cell parameters (a,b,c,alpha,beta, and gamma).

Angles must be in degrees.

The returned cell is orientated such that a and b are normal to ab_normal and a is parallel to the projection of a_direction in the a-b plane.

Default a_direction is (1,0,0), unless this is parallel to ab_normal, in which case default a_direction is (0,0,1).

The returned cell has the vectors va, vb and vc along the rows. The cell will be oriented such that va and vb are normal to ab_normal and va will be along the projection of a_direction onto the a-b plane.

Parameters:

• cellpar (array) – (6,1) vector with the cell parameters

• ab_normal (array) – Normal vector between a and b cell vectors. Default: (0, 0, 1)

• a_direction (array) – Specific direction for the a vector. Default: None

Returns:

cell – (3,3) matrix of cell vectors v1, v2, and v3

Return type:

array

pycofbuilder.tools.cellpar_to_lammpsbox(a: float, b: float, c: float, alpha: float, beta: float, gamma: float, angle_in_degrees: bool = True) → ndarray

Return the box parameters lx, ly, lz, xy, xz, yz for LAMMPS data input. :param a: The lengths of the edges. :type a: float :param b: The lengths of the edges. :type b: float :param c: The lengths of the edges. :type c: float :param alpha: The angles between the sides. :type alpha: float :param gamma: The angles between the sides. :type gamma: float :param beta: The angles between the sides. :type beta: float :param angle_in_degrees: True if alpha, beta and gamma are expressed in degrees. :type angle_in_degrees: bool

Returns:

r – The 1x6 array with the box parameters ‘lx’, ‘ly’, ‘lz’, ‘xy’, ‘xz’, ‘yz’.

Return type:

array_like

pycofbuilder.tools.change_X_atoms(atom_labels, atom_pos, bond_atom) → tuple

Changes the X atom for the desired bond_atom or remove it if bond_atom == ‘R’.

Parameters:

• atom_labels (list) – List containing the atom labels

• atom_pos (list) – List containing the atom position

Returns:

• labels (list) – List containing the processed atom labels

• pos (list) – List containing the processed atom position

pycofbuilder.tools.classify_unit_cell(cell, thr=0.001) → str

Determine the bravais lattice based on the cell lattice. The cell lattice can be the cell parameters as (6,1) array or the cell vectors as (3x3) array.

Bravais lattice can be cubic, tetragonal, orthorhombic, hexagonal, monoclinic, or triclinic.

Parameters:

• cell (array) – Array with the cell vectors or parameters

• threshold (float) – Numeric threshold for the analysis. Default: 1e-3

Returns:

cell_type – Bravais lattice.

Return type:

string

pycofbuilder.tools.closest_atom_struc(label_1, pos_1, labels, pos)

Finds the closest atom on the structure to a given atom

pycofbuilder.tools.create_CellBox(A, B, C, alpha, beta, gamma) → ndarray

Creates the CellBox using the same expression as RASPA.

pycofbuilder.tools.elements_dict(property='atomic_mass') → dict

Returns a dictionary containing the elements symbol and its selected property.

Parameters:

prop (string) –

The desired property can be:

• ”full_name”

• ”atomic_number”

• ”atomic_mass”

• ”polarizability”

• ”pauling_electronegativity”

• ”thermo_electronegativity”

• ”mulliken_electronegativity”

• ”sanderson_electronegativity”

• ”allen_electronegativity”

• ”ghosh_electronegativity”

• ”martynov_batsanov_electronegativity”

• ”atomic_radius”

• ”covalent_radius”

• ”vdw_radius”

Returns:

prop_dic – A dictionary containing the elements symbol and its respective property.

Return type:

dictionary

pycofbuilder.tools.equal_value(val1, val2, threshold=0.001) → bool

Determine if two values are equal based on a given threshold.

pycofbuilder.tools.find_closest_atom(target_label: str, target_position: list | ndarray[tuple[Any, ...], dtype[_ScalarT]], atom_labels: list, atom_positions: list | ndarray[tuple[Any, ...], dtype[_ScalarT]])

Find the closest atom to a given atom in a structure.

Parameters:

• target_label (str) – Label of the target atom.

• target_position (list | NDArray) – Position of the target atom as a list or numpy array.

• atom_labels (list) – List of all atom labels in the structure.

• atom_positions (list | NDArray) – List or numpy array of all atom positions in the structure.

Returns:

• closest_label (str) – Label of the closest atom.

• closest_position (NDArray) – Position of the closest atom as a numpy array.

• euclidean_distance (float) – Euclidean distance between the target atom and the closest atom.

pycofbuilder.tools.find_index(element, e_list) → int

Finds the index of a given element in a list

Parameters:

• element (string) – String containing the label of the element in e_list

• e_list (list) – List with the atom labels

Returns:

i – The index of element in the e_list

Return type:

int

pycofbuilder.tools.formula_from_atom_list(AtomLabels: list) → str

Create a string with the formula of the structure from the list of atoms.

Parameters:

AtomLabels (list) – List of strings containing the atom labels.

Returns:

formula – String with the formula of the structure.

Return type:

str

pycofbuilder.tools.get_bond_atom(connector_1: str, connector_2: str) → str

Get the atom that will be used to bond two building blocks.

pycofbuilder.tools.get_bonds(structure, cutoff=1.3)

Get the bonded atoms in a structure based on the distance between them.

Parameters:

• structure (pymatgen.Structure) – Structure object of pymatgen

• cutoff (float) – Cutoff factor for the covalent radii. Default: 1.3 Å

pycofbuilder.tools.get_cartesian_to_fractional_matrix(a: float, b: float, c: float, alpha: float, beta: float, gamma: float, angle_in_degrees: bool = True) → ndarray

Return the transformation matrix that converts cartesian coordinates to fractional coordinates.

Parameters:

• a (float) – The lengths of the edges.

• b (float) – The lengths of the edges.

• c (float) – The lengths of the edges.

• alpha (float) – The angles between the sides.

• gamma (float) – The angles between the sides.

• beta (float) – The angles between the sides.

• angle_in_degrees (bool) – True if alpha, beta and gamma are expressed in degrees.

Returns:

T_matrix – The 3x3 rotation matrix. R_frac = np.dot(T_matrix, R_cart).

Return type:

np.array

pycofbuilder.tools.get_fractional_to_cartesian_matrix(cell_a: float, cell_b: float, cell_c: float, alpha: float, beta: float, gamma: float, angle_in_degrees: bool = True) → ndarray

Return the transformation matrix that converts fractional coordinates to cartesian coordinates.

Parameters:

• a (float) – The lengths of the edges.

• b (float) – The lengths of the edges.

• c (float) – The lengths of the edges.

• alpha (float) – The angles between the sides.

• gamma (float) – The angles between the sides.

• beta (float) – The angles between the sides.

• angle_in_degrees (bool) – True if alpha, beta and gamma are expressed in degrees.

Returns:

T_matrix – The 3x3 rotation matrix. V_cart = np.dot(T_matrix, V_frac).

Return type:

ndarray

pycofbuilder.tools.get_framework_symm_text(name, lattice, hall, space_group, space_number, symm_op)

Get the text for the framework symmop

pycofbuilder.tools.get_kgrid(cell, distance=0.3) → tuple[int, int, int]

Get the k-points grid in the reciprocal space with a given distance for a cell given in cell parameters of cell vectors.

Parameters:

• cell (array) – (3,1) array for cell vectors or (6,1) array for cell parameters

• distance (float) – distance between the points in the reciprocal space

Returns:

• kx (int) – Number of points in the x direction on reciprocal space

• ky (int) – Number of points in the y direction on reciprocal space

• kz (int) – Number of points in the z direction on reciprocal space

pycofbuilder.tools.get_reciprocal_vectors(cell) → tuple[float, float, float]

Get the reciprocal vectors of a cell given in cell parameters of cell vectors.

Parameters:

cell (array) – (3,1) array for cell vectors or (6,1) array for cell parameters

Returns:

• b1 (array) – (3,1) array containing b_1 vector in the reciprocal space

• b2 (array) – (3,1) array containing b_2 vector in the reciprocal space

• b3 (array) – (3,1) array containing b_3 vector in the reciprocal space

pycofbuilder.tools.ibrav_to_cell(ibrav, celldm1, celldm2, celldm3, celldm4, celldm5, celldm6)

Convert a value of ibrav to a cell.

Parameters:

• ibrav (int)

• celldmx (float)

Returns:

cell – The cell as a 3x3 numpy array

Return type:

matrix

pycofbuilder.tools.is_bonded(atom1: str, atom2: str, dist: float, cutoff: float = 1.3)

Determine if two atoms are bonded based on the distance between them. Two atoms are considered bonded if the distance between them is less than the sum of their covalent radii multiplied by a cutoff factor.

Parameters:

• atom1 (str) – Label of the first atom

• atom2 (str) – Label of the second atom

• dist (float) – Distance between the two atoms

• cutoff (float) – Cutoff factor for the covalent radii. Default: 1.3

pycofbuilder.tools.print_command(text, verbose, match)

pycofbuilder.tools.print_framework_name(name, lattice, hall, space_group, space_number, symm_op)

Print the results of the created structure

pycofbuilder.tools.rmsd(V, W) → float

Calculate Root-mean-square deviation from two sets of vectors V and W. :param V: (N,D) matrix, where N is points and D is dimension. :type V: array :param W: (N,D) matrix, where N is points and D is dimension. :type W: array

Returns:

rmsd – Root-mean-square deviation between the two vectors

Return type:

float

pycofbuilder.tools.rotation_matrix_from_vectors(vec1, vec2) → ndarray

Find the rotation matrix that aligns vec1 to vec2

Parameters:

• vec1 (array) – (3,3) array

• vec2 (array) – (3,3) array

Returns:

rotation_matrix – A transform matrix (3x3) which when applied to vec1, aligns it with vec2.

Return type:

array

pycofbuilder.tools.smiles_to_xsmiles(smiles_string: str) → tuple[str, str, str]

Converts a SMILES string to an extended SMILES string with labels

Parameters:

smiles_string (str) – SMILES string to be converted

Returns:

• xsmiles (str) – Extended SMILES string with special labels

• xsmiles_label (str) – xsmiles labels for images with the special labels

• composition (str) – String containing the composition

pycofbuilder.tools.unit_vector(vector: list[float] | ndarray[tuple[Any, ...], dtype[_ScalarT]]) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

Return a unit vector in the same direction as x.

Module contents

class pycofbuilder.BuildingBlock(name: str = '', **kwargs)

Bases: object

add_R_group(R_name, R_type)

Adds group R in building blocks

add_connection_group(conector_name)

Adds the functional group by which the COF will be formed from the building blocks

add_connection_group_symm(conector_name)

Adds the functional group by which the COF will be formed from the building blocks

align_to(vec=[0, 1, 0], n: int = 0)

Align the first n-th X point to a given vector

Parameters:

• vec (list) – Vector to align the molecule

• n (int) – Index of the X point to be aligned

• align_to_y (bool) – If True, the second point is aligned to the y axis

calculate_size()

Calculate the size of the building block

centralize(by_X=True)

Centralize the molecule on its geometrical center

check_existence(name)

copy()

Return a deep copy of the BuildingBlock object

create_BB_structure(symmetry='L2', core_name='BENZ', conector='CHO', R1='H', R2='H', R3='H', R4='H', R5='H', R6='H', R7='H', R8='H', R9='H')

Create a building block

from_file(path, file_name)

Read a custom building block from a file.

Parameters:

• path (str) – Path to the file

• file_name (str) – Name of the file

from_name(name)

Automatically read or create a buiding block based on its name

get_Q_points(atom_types, atom_pos)

Get the Q points in a molecule

get_R_points(atom_types, atom_pos)

Get the R points in a molecule

get_X_points() → tuple

Get the X points in a molecule

get_available_R()

Get the list of available functional groups

get_available_conector()

Get the list of available conectores

get_available_core()

Get the list of available cores

get_buildingblock_list(shape, connector_group)

get_sizes()

Get the sizes of the building blocks

Returns:

List with the sizes of the building blocks

Return type:

list

property n_atoms

Returns the number of atoms in the unitary cell

print_structure()

Print the structure in xyz format: atom_label pos_x pos_y pos_z

remove_X()

replace_X(target_type)

rotate_around(rotation_axis: list | ndarray[tuple[Any, ...], dtype[_ScalarT]] = [1, 0, 0], angle: float = 0.0, degree: bool = True)

Rotate the molecule around a given axis

Parameters:

• rotation_axis (list) – Rotation axis

• angle (float) – Rotation angle in degrees

• degree (bool) – If True, the angle is given in degrees. Default is True.

rotate_to_xy_plane()

Rotate the molecule to the xy plane

save(extension='xyz')

shift(shift_vector: list)

Shift the molecule by a given vector

Parameters:

shift_vector (list) – Shift vector

structure_as_string()

to_ase()

Convert the building block to ASE atoms object

class pycofbuilder.Framework(name: str | None = None, **kwargs)

Bases: object

A class used to represent a Covalent Organic Framework as a reticular entity.

…

name

Name of the material

Type:

str

out_dir

Path to save the results. If not defined, a out folder will be created in the current directory.

Type:

str

verbosity

Control the printing options. Can be ‘none’, ‘normal’, or ‘debug’. Default: ‘normal’

Type:

str

save_bb

Control the saving of the building blocks. Default: True

Type:

bool

lib_path

Path for saving the building block files. If not defined, a building_blocks folder will be created in the current directory.

Type:

str

topology

Type:

str = None

dimention

Type:

str = None

lattice

Type:

str = None

lattice_sgs

Type:

str = None

space_group

Type:

str = None

space_group_n

Type:

str = None

stacking

Type:

str = None

mass

Type:

str = None

composition

Type:

str = None

charge

Type:

int = 0

multiplicity

Type:

int = 1

chirality

Type:

bool = False

atom_types

Type:

list = []

atom_pos

Type:

list = []

lattice

Type:

list = [[], [], []]

symm_tol

Type:

float = 0.2

angle_tol

Type:

float = 0.2

dist_threshold

Type:

float = 0.8

available_2D_topologies

List of available 2D topologies

Type:

list

available_3D_topologies

List of available 3D topologies

Type:

list

available_topologies

List of all available topologies

Type:

list

available_stacking

List of available stakings for all 2D topologies

Type:

list

lib_bb

String with the name of the folder containing the building block files Default: bb_lib

Type:

str

as_string() → str

Returns a string with the Framework information.

check_name_concistency(FrameworkName) → tuple[str, str, str, str]

Checks if the name is in the correct format and returns a tuple with the building blocks names, the net and the stacking.

In case the name is not in the correct format, an error is raised.

Parameters:

FrameworkName (str, required) – The name of the COF to be created

Returns:

A tuple with the building blocks names, the net and the stacking.

Return type:

tuple[str, str, str, str]

create_bor_structure(BB_D4: str, BB_T3: str, interp_dg: str = '1', d_param_base: float = 7.2, print_result: bool = True, **kwargs)

Creates a COF with BOR network.

The BOR net is composed of one tetrapodal tetrahedical building block and one tripodal triangular building block.

Parameters:

• BB_D4 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• BB_T3 (BuildingBlock, required) – The BuildingBlock object of the tripodal triangular Buiding Block

• interp_dg (str, optional) – The degree of interpenetration of the framework (default is ‘1’)

• d_param_base (float, optional) – The base value for interlayer distance in angstroms (default is 7.2)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_dia_a_structure(BB_D4: str, BB_L2: str, interp_dg: str = '1', d_param_base: float = 7.2, print_result: bool = True, **kwargs)

Creates a COF with DIA-A network.

The DIA net is composed of two tetrapodal tetrahedical building blocks.

Parameters:

• BB_D4 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the dipodal linear Buiding Block

• interp_dg (str, optional) – The degree of interpenetration of the framework (default is ‘1’)

• d_param_base (float, optional) – The base value for interlayer distance in angstroms (default is 7.2)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_dia_structure(BB_D41: str, BB_D42: str, interp_dg: str = '1', d_param_base: float = 7.2, print_result: bool = True, **kwargs)

Creates a COF with DIA network.

The DIA net is composed of two tetrapodal tetrahedical building blocks.

Parameters:

• BB_D41 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• BB_D42 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• interp_dg (str, optional) – The degree of interpenetration of the framework (default is ‘1’)

• d_param_base (float, optional) – The base value for interlayer distance in angstroms (default is 7.2)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_fxt_a_structure(BB_S4: str, BB_L2: str, stacking: str = 'AA', c_parameter_base: float = 3.6, print_result: bool = True, slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with FXT-A network.

The FXT-A net is composed of one tetrapodal and one linear building blocks.

Parameters:

• BB_S4 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the bipodal Buiding Block

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_fxt_structure(BB_R4_A: BuildingBlock, BB_R4_B: BuildingBlock, stacking: str = 'AA', print_result: bool = True, slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0.0), tilt_angle: float = 5.0)

Creates a COF with FXT network.

The FXT net is composed of two tetrapodal building blocks.

Parameters:

• BB_R4_A (BuildingBlock, required) – The BuildingBlock object of the rectangular tetrapodal Buiding Block A

• BB_R4_B (BuildingBlock, required) – The BuildingBlock object of the rectangular tetrapodal Buiding Block B

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0.0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_hcb_a_structure(BB_T3: str, BB_L2: str, stacking: str = 'AA', slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with HCB-A network.

The HCB-A net is composed of one tripodal and one linear building blocks.

Parameters:

• BB_T3 (BuildingBlock, required) – The BuildingBlock object of the tripodal Buiding Block

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the linear Buiding Block

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• c_parameter_base (float, optional) – The base value for interlayer distance in angstroms (default is 3.6)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name

2. lattice type

3. hall symbol of the cristaline structure

4. space group

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_hcb_structure(BB_T3_A, BB_T3_B, stacking: str = 'AA', slab: float = 10.0, shift_vector: tuple = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with HCB network.

The HCB net is composed of two tripodal building blocks.

Parameters:

• BB_T3_1 (BuildingBlock, required) – The BuildingBlock object of the tripodal Buiding Block A

• BB_T3_2 (BuildingBlock, required) – The BuildingBlock object of the tripodal Buiding Block B

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (tuple, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_hxl_a_structure(BB_H6: str, BB_L2: str, stacking: str = 'AA', print_result: bool = True, slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with HXL-A network.

The HXL-A net is composed of one hexapodal and one linear building blocks.

Parameters:

• BB_H6 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block A

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block B

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_kgd_structure(BB_H6: str, BB_T3: str, stacking: str = 'AA', print_result: bool = True, slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with KGD network.

The KGD net is composed of one hexapodal and one tripodal building blocks.

Parameters:

• BB_H6 (BuildingBlock, required) – The BuildingBlock object of the hexapodal Buiding Block

• BB_T3 (BuildingBlock, required) – The BuildingBlock object of the tripodal Buiding Block

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• c_parameter_base (float, optional) – The base value for interlayer distance in angstroms (default is 3.6)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_lon_a_structure(BB_D4: BuildingBlock, BB_L2: BuildingBlock, interp_dg: str | int = 0, d_param_base: float = 10, print_result: bool = True, **kwargs)

Creates a COF with LON network.

The LON_A net is composed of one tetrapodal tetrahedical and one linear building blocks.

Parameters:

• BB_D4 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the dipodal linear Buiding Block

• interp_dg (str, optional) – The degree of interpenetration of the framework (default is ‘1’)

• d_param_base (float, optional) – The base value for interlayer distance in angstroms (default is 7.2)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_lon_structure(BB_D4_A: str, BB_D4_B: str, interp_dg: str = '1', d_param_base: float = 7.2, print_result: bool = True, **kwargs)

Creates a COF with LON network.

The LON net is composed of two tetrapodal tetrahedical building blocks.

Parameters:

• BB_D4_A (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• BB_D4_B (BuildingBlock, required) – The BuildingBlock object of the tetrapodal tetrahedical Buiding Block

• interp_dg (str, optional) – The degree of interpenetration of the framework (default is ‘1’)

• d_param_base (float, optional) – The base value for interlayer distance in angstroms (default is 7.2)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_sql_a_structure(BB_S4: str, BB_L2: str, stacking: str = 'AA', c_parameter_base: float = 3.6, slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with SQL-A network.

The SQL-A net is composed of one tetrapodal and one linear building blocks.

Parameters:

• BB_S4 (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block

• BB_L2 (BuildingBlock, required) – The BuildingBlock object of the bipodal Buiding Block

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

create_sql_structure(BB_A: str, BB_B: str, stacking: str = 'AA', slab: float = 10.0, shift_vector: list = (1.0, 1.0, 0), tilt_angle: float = 5.0)

Creates a COF with SQL network.

The SQL net is composed of two tetrapodal building blocks.

Parameters:

• BB_S4_A (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block A

• BB_S4_B (BuildingBlock, required) – The BuildingBlock object of the tetrapodal Buiding Block B

• stacking (str, optional) – The stacking pattern of the COF layers (default is ‘AA’)

• print_result (bool, optional) – Parameter for the control for printing the result (default is True)

• slab (float, optional) – Default parameter for the interlayer slab (default is 10.0)

• shift_vector (list, optional) – Shift vector for the AAl and AAt stakings (defatult is [1.0,1.0,0])

• tilt_angle (float, optional) – Tilt angle for the AAt staking in degrees (default is 5.0)

Returns:

A list of strings containing:

1. the structure name,

2. lattice type,

3. hall symbol of the cristaline structure,

4. space group,

5. number of the space group,

6. number of operation symmetry

Return type:

list

from_building_blocks(bb1: BuildingBlock, bb2: BuildingBlock, net: str, stacking: str, **kwargs)

Creates a COF from the building blocks.

Parameters:

• BB1 (BuildingBlock, required) – The first building block

• BB2 (BuildingBlock, required) – The second building block

• Net (str, required) – The network of the COF

• Stacking (str, required) – The stacking of the COF

Returns:

COF – The COF object

Return type:

Framework

from_name(FrameworkName, **kwargs) → None

Creates a COF from a given FrameworkName.

Parameters:

FrameworkName (str, required) – The name of the COF to be created

Returns:

COF – The COF object

Return type:

Framework

get_available_topologies(dimensionality: str = 'all', print_result: bool = True)

Get the available topologies implemented in the class.

Parameters:

• dimensionality (str, optional) – The dimensionality of the topologies to be printed. Can be ‘all’, ‘2D’ or ‘3D’. Default: ‘all’

• print_result (bool, optional) – If True, the available topologies are printed.

Returns:

dimensionality_list – A list with the available topologies.

Return type:

list

get_n_atoms() → int

Returns the number of atoms in the unitary cell

make_cubic(min_length=10, force_diagonal=False, force_90_degrees=True, min_atoms=None, max_atoms=None, angle_tolerance=0.001)

Transform the primitive structure into a supercell with alpha, beta, and gamma equal to 90 degrees. The algorithm will iteratively increase the size of the supercell until the largest inscribed cube’s side length is at least ‘min_length’ and the number of atoms in the supercell falls in the range min_atoms < n < max_atoms.

Parameters:

• min_length (float, optional) – Minimum length of the cubic cell (default is 10)

• force_diagonal (bool, optional) – If True, generate a transformation with a diagonal transformation matrix (default is False)

• force_90_degrees (bool, optional) – If True, force the angles to be 90 degrees (default is True)

• min_atoms (int, optional) – Minimum number of atoms in the supercell (default is None)

• max_atoms (int, optional) – Maximum number of atoms in the supercell (default is None)

• angle_tolerance (float, optional) – The angle tolerance for the transformation (default is 1e-3)

save(fmt: str = 'cif', supercell: tuple = (1, 1, 1), save_dir=None, primitive=False, save_bonds=True, save_labels=False) → None

Save the structure in a specif file format.

Parameters:

• fmt (str, optional) – The file format to be saved Can be json, cif, xyz, turbomole, vasp, xsf, pdb, pqr, qe. Default: ‘cif’

• supercell (tuple, optional) – The supercell to be used to save the structure. Default: [1,1,1]

• save_dir (str, optional) – The path to save the structure. By default, the structure is saved in a out folder created in the current directory.

• primitive (bool, optional) – If True, the primitive cell is saved. Otherwise, the conventional cell is saved. Default: False

• save_bonds (bool, optional) – If True, the bonds are saved in the structure. Default: True

• save_labels (bool, optional) – If True, the atom labels are saved in the structure. Default: False

to_ase()

Convert the framework to an ASE Atoms object.