This module provides classes to specify atomic structure.

Module Contents



Generate Atoms python object.


Adds vaccum padding to make 2D structure or making molecules.


Module to work with optimade.



Use for making Atoms with vacuum.

add_atoms(top, bottom, distance=[0, 0, 1], apply_strain=False)

Add top and bottom Atoms with a distance array.

get_supercell_dims(atoms, enforce_c_size=10, extend=1)

Get supercell dimensions.


Convert pymatgen structure to Atoms.

ase_to_atoms(ase_atoms='', cartesian=True)

Convert ase structure to Atoms.

crop_square(atoms=None, csize=10)

Crop a sqaur portion from a surface/2D system.

compare_atoms(atoms1=[], atoms2=[], primitive_cell=True, verbose=True)

Compare atomic strutures.

build_xanes_poscar(atoms=None, selected_element='Si', prefix='-', extend=1, enforce_c_size=12, dir='.', filename_with_prefix=False)

Generate POSCAR file for XANES, note the element ordering.




jarvis.core.atoms.amu_gm = 1.66054e-24
jarvis.core.atoms.ang_cm = 1e-08
class jarvis.core.atoms.Atoms(lattice_mat=None, coords=None, elements=None, props=None, cartesian=False, show_props=False)[source]

Bases: object

Generate Atoms python object.

>>> box = [[2.715, 2.715, 0], [0, 2.715, 2.715], [2.715, 0, 2.715]]
>>> coords = [[0, 0, 0], [0.25, 0.2, 0.25]]
>>> elements = ["Si", "Si"]
>>> Si = Atoms(lattice_mat=box, coords=coords, elements=elements)
>>> print(round(Si.volume,2))
>>> Si.composition
{'Si': 2}
>>> round(Si.density,2)
>>> round(Si.packing_fraction,2)
>>> Si.atomic_numbers
[14, 14]
>>> Si.num_atoms
>>> Si.frac_coords[0][0]
>>> Si.cart_coords[0][0]
>>> coords = [[0, 0, 0], [1.3575 , 1.22175, 1.22175]]
>>> round(Si.density,2)
>>> Si.spacegroup()
'C2/m (12)'
>>> Si.pymatgen_converter()!={}
write_cif(self, filename='atoms.cif', comment=None, with_spg_info=True)[source]

Write CIF format file from Atoms object.

Caution: can’t handle fractional occupancies right now

static read_with_cif2cell(filename='1000000.cif', get_primitive_atoms=False)[source]

Use cif2cell package to read cif files.

static from_pdb_old(filename='abc.pdb')[source]

Read PDB file, kept of checking, use from_pdb instead.

static from_pdb(filename='abc.pdb', max_lat=200)[source]

Read pdb/sdf/mol2 etc. file and make Atoms object, using pytraj.

static from_cif(filename='atoms.cif', from_string='', get_primitive_atoms=True, use_cif2cell=True)[source]

Read .cif format file.

write_poscar(self, filename='POSCAR')[source]

Write POSCAR format file from Atoms object.

property get_xyz_string(self)

Get xyz string for atoms.

write_xyz(self, filename='atoms.xyz')[source]

Write XYZ format file.

classmethod from_xyz(self, filename='dsgdb9nsd_057387.xyz', box_size=40)[source]

Read XYZ file from to make Atoms object.

classmethod from_poscar(self, filename='POSCAR')[source]

Read POSCAR/CONTCAR file from to make Atoms object.

property check_polar(self)

Check if the surface structure is polar.

Comparing atom types at top and bottom. Applicable for sufcae with vaccums only.


file:atoms object (surface with vacuum)



strain_atoms(self, strain)[source]

Apply volumetric strain to atoms.

apply_strain(self, strain)[source]

Apply a strain(e.g. 0.01, [0,0,.01]) to the lattice.


Provide dictionary representation of the atoms object.

classmethod from_dict(self, d={})[source]

Form atoms object from the dictionary.

remove_site_by_index(self, site=0)[source]

Remove an atom by its index number.

add_site(self, element='Si', coords=[0.1, 0.1, 0.1], props=[], index=0)[source]

Ad an atom, coords in fractional coordinates.

property get_conventional_atoms(self)

Get conventional Atoms using spacegroup information.

property get_spacegroup(self)

Get spacegroup information.

property get_primitive_atoms(self)

Get primitive Atoms using spacegroup information.

get_all_neighbors(self, r=5, bond_tol=0.15)[source]

Get neighbors for each atom in the unit cell, out to a distance r.

Contains [index_i, index_j, distance, image] array. Adapted from pymatgen.

get_neighbors_cutoffs(self, max_cut=10, r=5, bond_tol=0.15)[source]

Get neighbors within cutoff.

atomwise_angle_and_radial_distribution(self, r=5, bond_tol=0.15, c_size=10, verbose=False)[source]

Get atomwise distributions.

property raw_distance_matrix(self)

Provide distance matrix.

property raw_angle_matrix(self, cut_off=5.0)

Provide distance matrix.

center(self, axis=2, vacuum=18.0, about=None)[source]

Center structure with vacuum padding.


vacuum:vacuum size

axis: direction

property volume(self)

Get volume of the atoms object.

property composition(self)

Get composition of the atoms object.

property density(self)

Get density in g/cm3 of the atoms object.

property atomic_numbers(self)

Get list of atomic numbers of atoms in the atoms object.

property num_atoms(self)

Get number of atoms.

property uniq_species(self)

Get unique elements.


Get center of mass of the atoms object.


Get center of mass of the atoms object.

center_around_origin(self, new_origin=[0.0, 0.0, 0.5])[source]

Center around given origin.


Get pymatgen representation of the atoms object.

phonopy_converter(self, pbc=True)[source]

Get phonopy representation of the atoms object.

ase_converter(self, pbc=True)[source]

Get ASE representation of the atoms object.

spacegroup(self, symprec=0.001)[source]

Get spacegroup of the atoms object.

property packing_fraction(self)

Get packing fraction of the atoms object.

lattice_points_in_supercell(self, supercell_matrix)[source]

Adapted from Pymatgen.

Returns the list of points on the original lattice contained in the supercell in fractional coordinates (with the supercell basis). e.g. [[2,0,0],[0,1,0],[0,0,1]] returns [[0,0,0],[0.5,0,0]]


supercell_matrix: 3x3 matrix describing the supercell


numpy array of the fractional coordinates

make_supercell_matrix(self, scaling_matrix)[source]

Adapted from Pymatgen.

Makes a supercell. Allowing to have sites outside the unit cell.


scaling_matrix: A scaling matrix for transforming the lattice vectors. Has to be all integers. Several options are possible: a. A full 3x3 scaling matrix defining the linear combination

the old lattice vectors. E.g., [[2,1,0],[0,3,0],[0,0, 1]] generates a new structure with lattice vectors a’ = 2a + b, b’ = 3b, c’ = c where a, b, and c are the lattice vectors of the original structure.

  1. An sequence of three scaling factors. E.g., [2, 1, 1]

specifies that the supercell should have dimensions 2a x b x c.

  1. A number, which simply scales all lattice vectors by the

same factor.


Supercell structure. Note that a Structure is always returned, even if the input structure is a subclass of Structure. This is to avoid different arguments signatures from causing problems. If you prefer a subclass to return its own type, you need to override this method in the subclass.

make_supercell(self, dim=[2, 2, 2])[source]

Make supercell of dimension dim.


Get LLL algorithm based reduced structure.


Get representation during print statement.

get_string(self, cart=True, sort_order='X')[source]

Convert Atoms to string.

Optional arguments below.


cart:True/False for cartesian/fractional coords.

sort_order: sort by chemical properties of

elements. Default electronegativity.

class jarvis.core.atoms.VacuumPadding(atoms, vacuum=20.0)[source]

Bases: object

Adds vaccum padding to make 2D structure or making molecules.


Add 2D vacuum to a system.


Add vacuum around a system.


Use for making Atoms with vacuum.

jarvis.core.atoms.add_atoms(top, bottom, distance=[0, 0, 1], apply_strain=False)[source]

Add top and bottom Atoms with a distance array.

Bottom Atoms lattice-matrix is chosen as final lattice.

jarvis.core.atoms.get_supercell_dims(atoms, enforce_c_size=10, extend=1)[source]

Get supercell dimensions.


Convert pymatgen structure to Atoms.

jarvis.core.atoms.ase_to_atoms(ase_atoms='', cartesian=True)[source]

Convert ase structure to Atoms.

jarvis.core.atoms.crop_square(atoms=None, csize=10)[source]

Crop a sqaur portion from a surface/2D system.

class jarvis.core.atoms.OptimadeAdaptor(atoms=None)[source]

Bases: object

Module to work with optimade.

reduce(self, content={})[source]

Reduce chemical formula.

optimade_reduced_formula(self, content={}, sort_alphabetical=True)[source]

Get chemical formula.

get_optimade_prototype(self, content={})[source]

Get chemical prototypes such as A, AB etc.


Get optimade species.

from_optimade(self, info={})[source]

Get Atoms from optimade.

to_optimade(self, idx='x', itype='structures', source='JARVIS-DFT-3D', reference_url='https://www.ctcms.nist.gov/~knc6/static/JARVIS-DFT/', now=datetime.datetime.now(datetime.timezone.utc).isoformat())[source]

Get optimade format data.

jarvis.core.atoms.compare_atoms(atoms1=[], atoms2=[], primitive_cell=True, verbose=True)[source]

Compare atomic strutures.

jarvis.core.atoms.build_xanes_poscar(atoms=None, selected_element='Si', prefix='-', extend=1, enforce_c_size=12, dir='.', filename_with_prefix=False)[source]

Generate POSCAR file for XANES, note the element ordering.