.. _03_atoms_objects:

.. include:: ../../examples/03_atoms_objects/README.rst

----

.. code-block:: python

   from eminus import Atoms
   

The only necessary parameters are :code:`atom` and :code:`pos`

:code:`atom` holds the atom symbols, and :code:`pos` holds the atom positions

Please note that atomic units will be used

.. code-block:: python

   atom = "N2"
   pos = [[-1.037, 0, 0], [1.037, 0, 0]]
   

Create an object for dinitrogen and display it

.. code-block:: python

   atoms = Atoms(atom, pos)
   print(f"Atoms object:\n{atoms}\n")
   

Cut-off energy

.. code-block:: python

   ecut = 20
   

Optional parameters with examples are listed as follows

Cell size or vacuum size

.. code-block:: python

   a = 20
   

Spin of the system, i.e., the number of unpaired electrons (2S, not 2S+1)

.. code-block:: python

   spin = 0
   

Total charge of the system

.. code-block:: python

   charge = 0
   

Spin handling

.. code-block:: python

   unrestricted = False
   

Center the system inside the box by its geometric center of mass and rotate it such that its geometric moment of inertia aligns with the coordinate axes

.. code-block:: python

   center = True
   

Level of output, larger numbers mean more output

.. code-block:: python

   verbose = 4
   

Create an :code:`Atoms` object for dinitrogen and display it

.. code-block:: python

   atoms = Atoms(
       atom=atom,
       pos=pos,
       ecut=ecut,
       a=a,
       spin=spin,
       charge=charge,
       unrestricted=unrestricted,
       center=center,
       verbose=verbose,
   )
   print(f"New Atoms object:\n{atoms}\n")
   

Albeit discouraged, some properties can be changed after the initialization as seen below

Valence charge per atom, the charges should not differ for the same species

:code:`None` will use valence charges from GTH pseudopotentials

.. code-block:: python

   atoms.Z = [5, 5]
   

Real-space sampling of the cell using an equidistant grid

.. code-block:: python

   atoms.s = 40
   

Occupation numbers per state

:code:`None` will assume occupations of 2

The last state will be adjusted if the sum of :code:`f` is not equal to the sum of :code:`Z`

.. code-block:: python

   atoms.f = [2, 2, 2, 2, 2]
   

You can manipulate the object by displaying or editing most properties

To display the calculated cell volume

.. code-block:: python

   print(f"Cell volume = {atoms.Omega} a0^3")
   

If you edit properties of an existing object dependent properties can be updated by rebuilding the :code:`Atoms` object

The :code:`atoms.build` function is used to generate cell parameters for an SCF calculation, but an SCF object will call the function if necessary

Edit the cell size, rebuild the object, and display the new cell volume

.. code-block:: python

   atoms.a = 3
   atoms.build()
   print(f"New cell volume = {atoms.Omega} a0^3")
   

To display all relevant electronic information regarding the occupations, one can display the :code:`Occupations` object every :code:`Atoms` object has

.. code-block:: python

   print(f"\nOccupations object:\n{atoms.occ}")
   

More information is always available in the respective docstring

.. code-block:: python

   # print(f"\nAtoms docstring:\n{Atoms.__doc__}")

or:

.. code-block:: python

   # help(Atoms)

Download :download:`03_atoms_objects.py <../../examples/03_atoms_objects/03_atoms_objects.py>`