Getting started¶
The objective of this tutorial is to give a basic idea of how Octopus works.
All tutorials assume that you have octopus in your PATH. Refer to Running tutorials for different options to prepare your environment.
mkdir -p 1-getting_started/01-H_atom
Generating the input file¶
With the %%writefile magic command, create a text file called inp in the directory 1-getting_started/01-H_atom containing the following text:
%%writefile 1-getting_started/01-H_atom/inp
stdout = "stdout_gs.txt"
stderr = "stderr_gs.txt"
CalculationMode = gs
%Coordinates
'H' | 0 | 0 | 0
%
Spacing = 0.25 * angstrom
Radius = 4.0 * angstrom
Writing 1-getting_started/01-H_atom/inp
This is the simplest example of an Octopus input file:
CalculationMode = gs: This variable defines the run mode – please consult the manual for the full list of the possible run modes. In this case we set it togs, which instructs the code to start a ground-state calculation.%Coordinates: The entry is not just the definition of a variable, but rather of a full set of them – a “block” of variables. The beginning of a block is marked by the%identifierline, and ended by a%line. In this case the identifier isCoordinates, where we list the atoms or species in our calculation and its coordinates, one per line. In this case, we put a single hydrogen atom in the center of our simulation box.
The reason this input file can be so simple is that Octopus comes with default values for the simulation parameters, and a set of default pseudopotentials for several elements (for properly converged calculations you might need to adjust these parameters, though).
To get a general idea of the format of the Octopus input file, go and read the page about the Input file in the manual.
The documentation for each input variable can be found in the variable reference online, and can also be accessed via the oct-help utility.
Running Octopus¶
Once you have written your input file, run the octopuscommand (using mpirun and perhaps a job script if you are using the parallel version).
In the notebook, you can call Octopus in a new subshell using the syntax !command. We first change to the directory where the inputfile has been saved and then execute Octopus inside. (As this is executed in a subshell, the cd does not change the notebook’s working directory.)
!cd 1-getting_started/01-H_atom && octopus
If everything goes correctly, you should see several lines of output in the file stdout_gs.txt (if you don’t, there must be a problem with your installation). As this is probably the first time you run Octopus, we will examine the most important parts of the output.
First there is an octopus drawn in ASCII art, the copyright notice and some information about the octopus version you are using and the system where you are running:
<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>
___
.-' `'.
/ \
| ;
| | ___.--,
_.._ |0) ~ (0) | _.---'`__.-( (_.
__.--'`_.. '.__.\ '--. \_.-' ,.--'` `""`
( ,.--'` ',__ /./; ;, '.__.'` __
_`) ) .---.__.' / | |\ \__..--"" """--.,_
`---' .'.''-._.-'`_./ /\ '. \ _.-~~~````~~~-._`-.__.'
| | .' _.-' | | \ \ '. `~---`
\ \/ .' \ \ '. '-._)
\/ / \ \ `=.__`~-.
jgs / /\ `) ) / / `"".`\
, _.-'.'\ \ / / ( ( / /
`--~` ) ) .-'.' '.'. | (
(/` ( (` ) ) '-;
` '-; (-'
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
<><><><><><><><><><><><><><><><><><><><><><><><><><><><><><><>
Running octopus
Version : Chierchiae
Commit : 4a158ca5b2
Configuration time : 2026-02-07T03:37:49
Configuration options : openmp mpi libxc_fxc libxc_kxc
Optional libraries : adios2 cgal etsf_io metis netcdf scalapack nlopt
Architecture : x86_64
Vectorization level : default
C compiler : /usr/bin/cc
C compiler flags :
C++ compiler : /usr/bin/c++
C++ compiler flags :
Fortran compiler : /usr/bin/gfortran (GCC version 14.2.0)
Fortran compiler flags : -ffree-line-length-none
The octopus is swimming in runner-utinjsnim-project-2018405-concurrent-0 (Linux)
Calculation started on 2026/02/07 at 03:59:44
Note that it also gives you the revision number, the compiler, and the compiler flags used. You should always include this information as well as your full cmake configure command when submitting a bug report!
The type of calculation it was asked to perform:
************************** Calculation Mode **************************
Input: [CalculationMode = gs]
**********************************************************************
The species and pseudopotentials it is using:
****************************** Species *******************************
Species 'H'
type : pseudopotential
file : '/app/share/octopus/pseudopotentials/PSF/H.psf'
file format : PSF
valence charge : 1.0
atomic number : 1
form on file : semilocal
orbital origin : calculated
lmax : 0
llocal : 0
projectors per l : 1
total projectors : 0
application form : local
orbitals : 16
bound orbitals : 1
**********************************************************************
After some other output, Octopus prints information about the grid: as we didn’t say anything in the input file, Octopus used the parameters recommended for this pseupopotential:
******************************** Grid ********************************
Simulation Box:
Type = minimum
Radius [b] = 7.559
Main mesh:
Spacing [b] = ( 0.472, 0.472, 0.472) volume/point [b^3] = 0.10544
# inner mesh = 17077
# total mesh = 30461
Grid Cutoff [H] = 22.110166 Grid Cutoff [Ry] = 44.220331
**********************************************************************
The level of theory and, in the case of (TD)DFT, the approximation to the exchange-correlation term:
**************************** Theory Level ****************************
Input: [TheoryLevel = kohn_sham]
Exchange-correlation:
Exchange
Slater exchange (LDA)
[1] P. A. M. Dirac., Math. Proc. Cambridge Philos. Soc. 26, 376 (1930)
[2] F. Bloch., Z. Phys. 57, 545 (1929)
Correlation
Perdew & Zunger (Modified) (LDA)
[1] J. P. Perdew and A. Zunger., Phys. Rev. B 23, 5048 (1981)
**********************************************************************
At this point, Octopus tries to read the wave-functions from a previous calculation. As there are none, it will give a warning.
** Warning:
** Unable to read wavefunctions.
** Starting from scratch!
** Warning:
** Cannot do LCAO for all states because there are not enough atomic orbitals.
** Required: 2. Available: 1. 1 orbitals will be randomized.
** Warning:
** Some of the states are not fully converged!
** With the Chebyshev filtering eigensolver, it usually helps to
** increase ExtraStates and set ExtraStatesToConverge to the number
** of states to be converged.
Now Octopus commences the calculation. To get a reasonable starting point for the DFT calculation, the initial wavefunctions are calculated as a Linear Combination of Atomic Orbitals (LCAO).
Info: Performing initial LCAO calculation with 1 orbitals.
Info: Getting Hamiltonian matrix elements.
Eigenvalues [H]
#st Spin Eigenvalue Occupation
1 -- -0.233536 1.000000
Generating random wavefunctions for states 2 and above
Orthogonalizing wavefunctions.
Info: Ground-state restart information will be written to '/builds/octopus-code/octopus/doc/jupyter_tutorials/1-basics/1-getting_started/01-H_atom/restart//gs'.
After the LCAO, the real DFT calculation starts. For each self-consistency step some information is printed. When SCF converges, the calculation is done.
*********************** SCF CYCLE ITER # 1 ************************
etot = -4.48524995E-01 abs_ev = 1.16E-03 rel_ev = 4.95E-03
ediff = 4.49E-01 abs_dens = 9.73E-03 rel_dens = 9.73E-03
Matrix vector products: 25
Converged eigenvectors: 0
# State Eigenvalue [H] Occupation Error
1 -0.234698 1.000000 ( 4.3E-07)
2 0.104327 0.000000 ( 6.6E-02)
Density of states:
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
^
Elapsed time for SCF step 1: 0.07
**********************************************************************
…
*********************** SCF CYCLE ITER # 8 ************************
etot = -4.46666262E-01 abs_ev = 1.55E-08 rel_ev = 6.63E-08
ediff = 1.78E-08 abs_dens = 4.70E-08 rel_dens = 4.70E-08
Matrix vector products: 25
Converged eigenvectors: 0
# State Eigenvalue [H] Occupation Error
1 -0.233152 1.000000 ( 1.3E-07)
2 0.102909 0.000000 ( 1.1E-02)
Density of states:
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
%--------------------------------------------------------------------%
^
Elapsed time for SCF step 8: 0.02
**********************************************************************
Info: Writing states. 2026/02/07 at 03:59:45
Info: Finished writing states. 2026/02/07 at 03:59:45
Info: SCF converged in 8 iterations
Info: Number of matrix-vector products: 200
Info: Finished writing information Ground-state to '/builds/octopus-code/octopus/doc/jupyter_tutorials/1-basics/1-getting_started/01-H_atom/restart//gs'.
Calculation ended on 2026/02/07 at 03:59:45
Walltime: 01. 38s
Octopus emitted 3 warnings.
Just running the command octopus will write the output directly to the terminal. To have a saved copy of the output, it is generally advisable to redirect the output into files, which can be done by specifying stdout = "stdout.txt" and stderr = "stderr.txt" in the inp file as has been done in this example.
This creates a file called stdout.txt containing all output and a file called stderr.txt containing all warnings and errors.
Analyzing the results¶
After finishing the calculation you will find a series of files in the directory you ran:
!ls 1-getting_started/01-H_atom/
exec inp restart static stderr_gs.txt stdout_gs.txt
For the moment we will ignore the “exec” and “restart” directories and focus on the static/info file, which contains the detailed results of the ground-state calculation. If you open that file, first you will see some parameters of the calculations (that we already got from the output) and then the calculated energies and eigenvalues in Hartrees:
Eigenvalues [H]
#st Spin Eigenvalue Occupation
1 -- -0.233152 1.000000
2 -- 0.102909 0.000000
Energy [H]:
Total = -0.44666629
Free = -0.44666629
-----------
Ion-ion = 0.00000000
Eigenvalues = -0.23315171
Hartree = 0.28435834
Int[n*v_xc] = -0.30452586
Exchange = -0.19391658
Correlation = -0.03976552
vanderWaals = 0.00000000
Delta XC = 0.00000000
Entropy = 1.38629436
-TS = -0.00000000
Photon ex. = 0.00000000
Kinetic = 0.41883274
External = -0.91617527
Non-local = 0.00000000
Int[n*v_E] = 0.00000000
Since by default Octopus does a spin-unpolarized density-functional-theory calculation with the local-density approximation, our results differ from the exact total energy of 0.5 H. Our exchange-correlation functional can be set by the variable XCFunctional, using the set provided by the libxc library.
Extras¶
If you want to improve the LDA results, you can try to repeat the calculation with spin-polarization by adding SpinComponents = spin_polarized to the inp file:
mkdir -p 1-getting_started/01-H_atom_spin
%%writefile 1-getting_started/01-H_atom_spin/inp
stdout = "stdout_gs_spin_polarized.txt"
stderr = "stderr_gs_spin_polarized.txt"
CalculationMode = gs
%Coordinates
'H' | 0 | 0 | 0
%
Spacing = 0.25 * angstrom
Radius = 4.0 * angstrom
SpinComponents = spin_polarized
Writing 1-getting_started/01-H_atom_spin/inp
!cd 1-getting_started/01-H_atom_spin && octopus
Eigenvalues [H]
#st Spin Eigenvalue Occupation
1 up -0.269243 1.000000
1 dn -0.080050 0.000000
2 up 0.097234 0.000000
2 dn 0.114399 0.000000
Energy [H]:
Total = -0.47973940
Free = -0.47973940
-----------
Ion-ion = 0.00000000
Eigenvalues = -0.26924272
Hartree = 0.29941095
Int[n*v_xc] = -0.36781848
Exchange = -0.25702318
Correlation = -0.02188103
vanderWaals = 0.00000000
Delta XC = 0.00000000
Entropy = 0.00000000
-TS = -0.00000000
Photon ex. = 0.00000000
Kinetic = 0.45850850
External = -0.95875464
Non-local = 0.00000000
Int[n*v_E] = 0.00000000
Total Spin Magnetic Moment:
mz = 1.000000
Local Spin Magnetic Moments (sphere radius [b] = 100.000):
Ion mz
1 H 1.000000
Dipole: [b] [Debye]
<x> = 3.97125E-09 1.00939E-08
<y> = 2.18813E-08 5.56167E-08
<z> = 4.68186E-09 1.19001E-08
Convergence:
abs_energy = 5.12183938E-08 ( 0.00000000E+00) [H]
rel_energy = 1.06762979E-07 ( 0.00000000E+00)
abs_dens = 9.12269213E-08 ( 0.00000000E+00)
rel_dens = 9.12269213E-08 ( 1.00000000E-06)
abs_evsum = 3.65732981E-08 ( 0.00000000E+00) [H]
rel_evsum = 1.35837687E-07 ( 0.00000000E+00)
Forces on the ions [H/b]
Ion x y z
1 H -2.40011630E-09 -9.74417990E-09 -2.87263684E-09
----------------------------------------------------------
Max abs force 2.40011630E-09 9.74417990E-09 2.87263684E-09
Total force -2.40011630E-09 -9.74417990E-09 -2.87263684E-09
Total torque 0.00000000E+00 0.00000000E+00 0.00000000E+00
And if you want to obtain the exact Schödinger equation result (something possible only for very simple systems like this one) you have to remove the self-interaction error (a problem of the LDA). Since we only have one electron the simplest way to do it for this case is to use independent electrons by adding TheoryLevel = independent_particles:
mkdir -p 1-getting_started/01-H_atom_independent
%%writefile 1-getting_started/01-H_atom_independent/inp
stdout = "stdout_gs_spin_polarized_independent.txt"
stderr = "stderr_gs_spin_polarized_independent.txt"
CalculationMode = gs
%Coordinates
'H' | 0 | 0 | 0
%
Spacing = 0.25 * angstrom
Radius = 4.0 * angstrom
SpinComponents = spin_polarized
TheoryLevel = independent_particles
Writing 1-getting_started/01-H_atom_independent/inp
!cd 1-getting_started/01-H_atom_independent && octopus
Eigenvalues [H]
#st Spin Eigenvalue Occupation
1 up -0.501213 0.500000
1 dn -0.501213 0.500000
2 up -0.074005 0.000000
2 dn -0.074174 0.000000
Energy [H]:
Total = -0.50121348
Free = -0.50121348
-----------
Ion-ion = 0.00000000
Eigenvalues = -0.50121348
Hartree = 0.00000000
Int[n*v_xc] = 0.00000000
Exchange = 0.00000000
Correlation = 0.00000000
vanderWaals = 0.00000000
Delta XC = 0.00000000
Entropy = 1.38629436
-TS = -0.00000000
Photon ex. = 0.00000000
Kinetic = 0.49111374
External = -0.99232723
Non-local = 0.00000000
Int[n*v_E] = 0.00000000
Total Spin Magnetic Moment:
mz = -0.000000
Local Spin Magnetic Moments (sphere radius [b] = 100.000):
Ion mz
1 H -0.000000
Dipole: [b] [Debye]
<x> = -1.90063E-09 -4.83091E-09
<y> = -2.67501E-09 -6.79920E-09
<z> = 1.58130E-09 4.01926E-09
Convergence:
abs_energy = 6.66133815E-16 ( 0.00000000E+00) [H]
rel_energy = 1.32904209E-15 ( 0.00000000E+00)
abs_dens = 4.76308423E-08 ( 0.00000000E+00)
rel_dens = 4.76308423E-08 ( 1.00000000E-06)
abs_evsum = 6.66133815E-16 ( 0.00000000E+00) [H]
rel_evsum = 1.32904209E-15 ( 0.00000000E+00)
Forces on the ions [H/b]
Ion x y z
1 H 3.00523305E-10 4.29064282E-10 -2.47013579E-10
----------------------------------------------------------
Max abs force 3.00523305E-10 4.29064282E-10 2.47013579E-10
Total force 3.00523305E-10 4.29064282E-10 -2.47013579E-10
Total torque 0.00000000E+00 0.00000000E+00 0.00000000E+00
A more general way would be to include self-interaction correction.
Tutorial Validation Checks¶
If you are not an Octopus developer you can ignore this section.
The purpose of these checks is to automatically inform the developers if tutorials have to be updated, due to changes in Octopus. These tests are not meant to be regression tests, as all functionality is tested in the testsuite.
Please, note that the reference values are determined by the original input files in the tutorials. The tests might fail if you experiment with the input variables, e.g. to test the convergence, or try different algorithms.
from postopus import Run
import numpy as np
run = Run("1-getting_started/01-H_atom")
scf_iterations = run.scf.info.get_scf_iteration_count()
evals = run.scf.info.get_eigenvalues()
total_energy = run.scf.info.get_total_energy()
assert(run.scf.info.scf_is_converged())
np.testing.assert_array_less(scf_iterations, 13)
np.testing.assert_allclose(evals.Eigenvalue.iloc[0], -0.233146, atol=1e-4)
np.testing.assert_allclose(total_energy, -0.44662908, atol=1e-4)
run = Run("1-getting_started/01-H_atom_spin")
evals = run.scf.info.get_eigenvalues()
total_energy = run.scf.info.get_total_energy()
assert(run.scf.info.scf_is_converged())
np.testing.assert_allclose(evals.Eigenvalue[evals.Spin == 'up'].iloc[0], -0.269243, atol=1e-4)
np.testing.assert_allclose(total_energy, -0.479739, atol=1e-4)
run = Run("1-getting_started/01-H_atom_independent")
evals = run.scf.info.get_eigenvalues()
total_energy = run.scf.info.get_total_energy()
assert(run.scf.info.scf_is_converged())
np.testing.assert_allclose(evals.Eigenvalue[evals.Spin == 'up'].iloc[0], -0.501213, atol=1e-4)
np.testing.assert_allclose(total_energy, -0.501213, atol=1e-4)