class chemcoord.Cartesian(frame=None, atoms=None, coords=None, index=None, metadata=None, _metadata=None)[source]

The main class for dealing with cartesian Coordinates.

Mathematical Operations:

It supports binary operators in the logic of the scipy stack, but you need python3.x for using the matrix multiplication operator @.

The general rule is that mathematical operations using the binary operators + - * / @ and the unary operators + - abs are only applied to the ['x', 'y', 'z'] columns.

Addition/Subtraction/Multiplication/Division: If you add a scalar to a Cartesian it is added elementwise onto the ['x', 'y', 'z'] columns. If you add a 3-dimensional vector, list, tuple... the first element of this vector is added elementwise to the 'x' column of the Cartesian instance and so on. The last possibility is to add a matrix with shape=(len(Cartesian), 3) which is again added elementwise. The same rules are true for subtraction, division and multiplication.

Matrixmultiplication: Only leftsided multiplication with a matrix of shape=(n, 3), where n is a natural number, is supported. The usual usecase is for example np.diag([1, 1, -1]) @ cartesian_instance to mirror on the x-y plane.


The indexing behaves like Indexing and Selecting data in Pandas. You can slice with loc(), iloc() and Cartesian[...]. The only question is about the return type. If the information in the columns is enough to draw a molecule, an instance of the own class (e.g. Cartesian) is returned. If the information in the columns is not enough to draw a molecule, there are two cases to consider:

  • A Series instance is returned for one dimensional slices.
  • A DataFrame instance is returned in all other cases.

This means that:

molecule.loc[:, ['atom', 'x', 'y', 'z']] returns a Cartesian.

molecule.loc[:, ['atom', 'x']] returns a pandas.DataFrame.

molecule.loc[:, 'atom'] returns a pandas.Series.


Comparison for equality with == is supported. It behaves exactly like the equality comparison of DataFrames in pandas. Amongst other things this means that the index has to be the same and the comparison of floating point numbers is exact and not numerical. For this reason you rarely want to use ==. Usually the question is “are two given molecules chemically the same”. For this comparison you have to use the function allclose(), which moves to the barycenter, aligns along the principal axes of inertia and compares numerically.

Chemical Methods

__init__([frame, atoms, coords, index, ...]) How to initialize a Cartesian instance.
get_bonds([self_bonding_allowed, offset, ...]) Return a dictionary representing the bonds.
restrict_bond_dict(bond_dict) Restrict a bond dictionary to self.
get_fragment(list_of_indextuples[, ...]) Get the indices of the atoms in a fragment.
fragmentate([give_only_index, use_lookup]) Get the indices of non bonded parts in the molecule.
get_without(fragments[, use_lookup]) Return self without the specified fragments.
add_data([new_cols]) Adds a column with the requested data.
get_total_mass() Returns the total mass in g/mol.
get_electron_number([charge]) Return the number of electrons.
get_coordination_sphere(index_of_atom[, ...]) Return a Cartesian of atoms in the n-th coordination sphere.
partition_chem_env([n_sphere, use_lookup]) This function partitions the molecule into subsets of the same chemical environment.


cut_cuboid([a, b, c, origin, ...]) Cut a cuboid specified by edge and radius.
cut_sphere([radius, origin, outside_sliced, ...]) Cut a sphere specified by origin and radius.
basistransform(new_basis[, old_basis, ...]) Transform the frame to a new basis.
align(other[, indices, ignore_hydrogens]) Align two Cartesians.
reindex_similar(other[, n_sphere]) Reindex other to be similarly indexed as self.
change_numbering(rename_dict[, inplace]) Return the reindexed version of Cartesian.
subs(*args) Substitute a symbolic expression in ['x', 'y', 'z']


get_bond_lengths(indices) Return the distances between given atoms.
get_angle_degrees(indices) Return the angles between given atoms.
get_dihedral_degrees(indices[, start_row]) Return the dihedrals between given atoms.
get_barycenter() Return the mass weighted average location.
get_inertia() Calculate the inertia tensor and transforms along rotation axes.
get_centroid() Return the average location.
get_distance_to([origin, other_atoms, sort]) Return a Cartesian with a column for the distance from origin.
get_shortest_distance(other) Calculate the shortest distance between self and other

Conversion to internal coordinates

get_zmat([construction_table, use_lookup]) Transform to internal coordinates.
get_grad_zmat(construction_table[, as_function]) Return the gradient for the transformation to a Zmatrix.
get_construction_table([fragment_list, ...]) Create a construction table for a Zmatrix.
check_dihedral(construction_table) Checks, if the dihedral defining atom is colinear.
correct_dihedral(construction_table[, ...]) Reindexe the dihedral defining atom if linear reference is used.
check_absolute_refs(construction_table) Checks first three rows of construction_table for linear references
correct_absolute_refs(construction_table) Reindexe construction_table if linear reference in first three rows present.
to_zmat(*args, **kwargs) Deprecated, use get_zmat()


get_pointgroup([tolerance]) Returns a PointGroup object for the molecule.
get_equivalent_atoms([tolerance]) Returns sets of equivalent atoms with symmetry operations
symmetrize([max_n, tolerance, epsilon]) Returns a symmetrized molecule


to_xyz([buf, sort_index, index, header, ...]) Write xyz-file
write_xyz(*args, **kwargs) Deprecated, use to_xyz()
read_xyz(buf[, start_index, get_bonds, ...]) Read a file of coordinate information.
to_cjson([buf]) Write a cjson file or return dictionary.
read_cjson(buf) Read a cjson file or a dictionary.
view([viewer, use_curr_dir]) View your molecule.
to_string([buf, columns, col_space, header, ...]) Render a DataFrame to a console-friendly tabular output.
to_latex([buf, columns, col_space, header, ...]) Render a DataFrame to a tabular environment table.
get_pymatgen_molecule() Create a Molecule instance of the pymatgen library
from_pymatgen_molecule(molecule) Create an instance of the own class from a pymatgen molecule
get_ase_atoms() Create an Atoms instance of the ase library
from_ase_atoms(atoms) Create an instance of the own class from an ase molecule

Pandas DataFrame Wrapper

index Returns the index.
columns Returns the columns.
replace([to_replace, value, inplace, limit, ...]) Replace values given in ‘to_replace’ with ‘value’.
sort_index([axis, level, ascending, ...]) Sort object by labels (along an axis)
set_index(keys[, drop, append, inplace, ...]) Set the DataFrame index (row labels) using one or more existing columns.
append(other[, ignore_index]) Append rows of other to the end of this frame, returning a new object.
insert(loc, column, value[, ...]) Insert column into molecule at specified location.
sort_values(by[, axis, ascending, inplace, ...]) Sort by the values along either axis
loc Label based indexing
iloc Label based indexing

Advanced methods

_divide_et_impera([n_atoms_per_set, offset])
_preserve_bonds(sliced_cartesian[, use_lookup]) Is called after cutting geometric shapes.


columns Returns the columns.
index Returns the index.