4. Interface

4.1. The ‘cell’ command

The ‘cell’ command defines the inq simulation cell. There are different variations of the command depending on the type of cell you want to define.

In all cases you must include the units for the cell. For the moment note you can use ‘bohr’ (or ‘b’) and ‘angstrom’ (or ‘A’). See inq help units for other supported units.

An optional last argument defines the periodicity of the cell. The periodicity can be specified as a number from 0 (or ‘0d’) to 3 (‘3d’), or as ‘finite’, ‘wire’, ‘slab’ and ‘periodic’. If the periodicity is not given, the system is considered periodic. For Python either a integer or a string can be given.

Note that defining the cell is not necessary if you are going to read it from a file (using the inq ion file command).

The following are the accepted forms of the cell command:

inq cell

Without any arguments (or the status function in python), cell prints the cell currently defined in the system.
```
inq cell
```
inq cell cubic <a> <units> [periodicity]

Defines a cubic cell of side <a>.
```
inq cell cubic 5.0 A finite
```
inq cell orthorhombic <a> <b> <c> <units> [periodicity]

Defines a orthorhombic cell of sides a, b and c.
```
inq cell orthorhombic 10.0 10.0 12.0 bohr
```
inq cell <a1> <a2> <a3> <b1> <b2> <b3> <c1> <c2> <c3> <units> [periodicity]

Creates a general cell defined by the lattice vectors a, b, and c (given by components). The units are applied to all the vector components.
```
inq cell  4.6478 0 0  -2.3239 4.02512 0  0 0 10.0 b 2d
```
inq cell <a1> <a2> <a3> <b1> <b2> <b3> <c1> <c2> <c3> scale <s> <units> [periodicity]

Like the previous case, creates a general cell defined by the lattice vectors a, b, and c (given by components). However in this case a general scale factor is applied to all the vectors.
```
inq cell  0.0 0.5 0.5  0.5 0.0 0.5  0.5 0.5 0.0  scale 3.57 angstrom
```

The ‘cell’ command defines the inq simulation cell. There are different variations of the command depending on the type of cell you want to define.

In all cases you must include the units for the cell. For the moment note you can use ‘bohr’ (or ‘b’) and ‘angstrom’ (or ‘A’). See inq help units for other supported units.

An optional last argument defines the periodicity of the cell. The periodicity can be specified as a number from 0 (or ‘0d’) to 3 (‘3d’), or as ‘finite’, ‘wire’, ‘slab’ and ‘periodic’. If the periodicity is not given, the system is considered periodic. For Python either a integer or a string can be given.

Note that defining the cell is not necessary if you are going to read it from a file (using the inq ion file command).

The following are the accepted forms of the cell command:

pinq.cell.status()

Without any arguments (or the status function in python), cell prints the cell currently defined in the system.
```
pinq.cell.status()
```
pinq.cell.cubic(a, units, periodicity = 3)

Defines a cubic cell of side <a>.
```
pinq.cell.cubic(5.0, "A", "finite")
```
pinq.cell.orthorhombic(a, b, c, units, periodicity = 3)

Defines a orthorhombic cell of sides a, b and c.
```
pinq.cell.orthorhombic(10.0, 10.0, 12.0, "bohr")
```
pinq.cell.lattice([a1, a2, a3], [b1, b2, b3], [c1, c2, c3], units, periodicity)

Creates a general cell defined by the lattice vectors a, b, and c (given by components). The units are applied to all the vector components.
```
pinq.cell.lattice([4.6478, 0, 0], [-2.3239, 4.02512, 0], [0, 0, 10.0], "b", "2d")
```
pinq.cell.lattice([a1, a2, a3], [b1, b2, b3], [c1, c2, c3], scale, units, periodicity)

Like the previous case, creates a general cell defined by the lattice vectors a, b, and c (given by components). However in this case a general scale factor is applied to all the vectors.
```
pinq.cell.lattice([0.0, 0.5, 0.5], [0.5, 0.0, 0.5], [0.5, 0.5, 0.0], 3.57, "angstrom")
```

4.2. The ‘clear’ command

The ‘clear’ command removes all inq information from the current directory. It doesn’t take any arguments.

pinq clear

The ‘clear’ command removes all inq information from the current directory. It doesn’t take any arguments.

pinq.clear()

4.3. The ‘electrons’ command

This command defines the electrons that are in the system and how they are going to be represented through several values that can be set by the user.

electrons

When no arguments are given (or the status function in Python), electrons will just print the currently defined options (including default values).
```
inq electrons
```
electrons cutoff <value> <units>

Sets the energy cutoff for the simulation grid. A higher cutoff implies a more precise, but more costly, simulation. The value must be followed by its units, check inq help units for details on what units are available.
```
inq electrons cutoff 30.0 Ry
```
electrons spacing <value> <units>

As an alternative to the cutoff, you can sets the spacing for the simulation grid. A lower spacing implies a more precise, but more costly, simulation. The value must be followed by its length units, check inq help units for details on what units are available.
```
inq electrons spacing 0.23 A
```
electrons spin <value>

Sets the spin configuration used in the simulation. In the command line interface this is selected by an argument whose values can be ‘unpolarized’ (the default), ‘polarized’ and ‘non-collinear’. For Python there are different functions for each value.
```
inq electrons spin polarized
```
electrons extra-electrons <value>

Inq determines the number of electrons from the ions present in the system. Using this variable you can add or remove electrons from the simulation. Positive values add electrons and negative values remove them. The number of electrons does not have to be an integer, you can add fractions of an electrons (given as a decimal number).

Note that in first principles simulations the electrons are not associated a priory to a certain atom. So when you add an electron there is no concept of ‘where’ you put it. This will be determined by the ground-state optimization.
```
inq electrons extra-electrons -0.5
```
electrons extra-states <value>

Inq automatically selects a number of states (orbitals, bands) that is enough to represent all the electrons in the system. In many cases you want additional states, and you do that using this command. The value must be a positive integer.

Extra-states are necessary when setting an electronic temperature and to improve ground-state convergence.
```
inq electrons extra-states 2
```
electrons temperature <value> <units>

This command sets the temperature of the electrons in the ground-state optimization. The value must be positive and the units must be given. Check inq help units for details on what units are available. Most likely you want to use ‘eV’ or ‘K’.

Note that when you add a temperature you also need to specify extra-states.
```
inq electrons temperature 273.15 Kelvin
```

This command defines the electrons that are in the system and how they are going to be represented through several values that can be set by the user.

electrons.status()

When no arguments are given (or the status function in Python), electrons will just print the currently defined options (including default values).
```
pinq.electrons.status()
```
electrons.cutoff(value, units)

Sets the energy cutoff for the simulation grid. A higher cutoff implies a more precise, but more costly, simulation. The value must be followed by its units, check inq help units for details on what units are available.
```
pinq.electrons.cutoff(30.0, "Ry")
```
electrons.spacing(value, units)

As an alternative to the cutoff, you can sets the spacing for the simulation grid. A lower spacing implies a more precise, but more costly, simulation. The value must be followed by its length units, check inq help units for details on what units are available.
```
pinq.electrons.spacing(0.23, "A")
```
electrons.spin_unpolarized()` `electrons.spin_polarized()` `electrons.spin_non_collinear()

Sets the spin configuration used in the simulation. In the command line interface this is selected by an argument whose values can be ‘unpolarized’ (the default), ‘polarized’ and ‘non-collinear’. For Python there are different functions for each value.
```
pinq.electrons.spin_polarized()
```
electrons.extra_electrons(value)

Inq determines the number of electrons from the ions present in the system. Using this variable you can add or remove electrons from the simulation. Positive values add electrons and negative values remove them. The number of electrons does not have to be an integer, you can add fractions of an electrons (given as a decimal number).

Note that in first principles simulations the electrons are not associated a priory to a certain atom. So when you add an electron there is no concept of ‘where’ you put it. This will be determined by the ground-state optimization.
```
pinq.electrons.extra_electrons(-0.5)
```
electrons.extra_states(value)

Inq automatically selects a number of states (orbitals, bands) that is enough to represent all the electrons in the system. In many cases you want additional states, and you do that using this command. The value must be a positive integer.

Extra-states are necessary when setting an electronic temperature and to improve ground-state convergence.
```
pinq.electrons.extra_states(2)
```
electrons.temperature(value, units)

This command sets the temperature of the electrons in the ground-state optimization. The value must be positive and the units must be given. Check inq help units for details on what units are available. Most likely you want to use ‘eV’ or ‘K’.

Note that when you add a temperature you also need to specify extra-states.
```
pinq.electrons.temperature(273.15, "Kelvin")
```

4.4. The ‘ground-state’ command

This command defines the options for ground-state self-consistency calculations. These are the available options:

ground-state

When no arguments are given, ground-state will just print the currently defined options (including default values).
```
inq ground-state
```
ground-state max-steps <value>

Sets the maximum number of self-consistency steps that will be done. The default value is 200.
```
inq ground-state max-steps 100
```
ground-state tolerance <value>

The tolerance used to consider that the self-consistency iteration is converged. The default value is 1e-6.
```
inq ground-state tolerance 1e-9
```
ground-state mixing <value>

Set the mixing factor for the self-consistency. The default value is 0.3.
```
inq ground-state mixing 0.1
```

This command defines the options for ground-state self-consistency calculations. These are the available options:

ground_state.status()

When no arguments are given, ground-state will just print the currently defined options (including default values).
```
pinq.ground_state.status()
```
ground_state.max_steps(value)

Sets the maximum number of self-consistency steps that will be done. The default value is 200.
```
pinq.ground_state.max_steps(100)
```
ground_state.tolerance(value)

The tolerance used to consider that the self-consistency iteration is converged. The default value is 1e-6.
```
pinq.ground_state.tolerance(1e-9)
```
ground_state.mixing(value)

Set the mixing factor for the self-consistency. The default value is 0.3.
```
pinq.ground_state.mixing(0.1)
```

4.5. The ‘history’ command

This command provides access to the history of the inq commands executed in the current directory. This command is only available for the shell interface.

These are the available subcommands:

history

Prints a full list of the inq commands that have been executed in the current directory.

Shell example: inq history

history clear

Clears the list of saved commands.

Shell example: inq history clear

history script

Prints a bash script containing the list of commands that reproduce the calculation in the current directory. The recommended script headers are included. Any command issues before inq clear will not be included.

Shell example: inq history script > my_calculation.sh

4.6. The ‘ions’ command

This command defines the ions present in the system and its coordinates. These can be given one by one using insert or from a file using file.

If you are adding ions one by one or reading an XYZ file, you must first declare the cell for system (see inq help cell or help(pinq.cell)).

These are the uses for the command:

ions

Without any arguments (or status() in python), ions prints a list of the ions currently in the system.
```
inq ions
```
ions clear

Removes any ions present in the system. Does not change the cell.
```
inq ions clear
```
ions insert <symbol> <x> <y> <z> <units>

Add an ion of type _symbol_ at coordinates _x_, _y_, and _z_. The units for the coordinates must be specified (check inq help units for details).
```
inq ions insert He  0.0 0.0 2.0 angstrom
```
ions insert fractional <symbol> <x> <y> <z>

Insert an ion of type _symbol_ at fractional coordinates _x_, _y_, and _z_.
```
inq ions insert fractional Si 0.25 0.25 0.25
```
ions remove <index>

Removes the ion given by _index_. Note that the ions indices start from 0, not 1.
```
inq ions remove 3
```
ions file <filename>

Read a coordinate file given by <filename>. The supported formats are POSCAR, CIF and XYZ. For POSCAR and CIF both the ions and the cell information will be read. For XYZ only the atomic positions are read, so the cell must be defined before reading the file.
```
inq ions file diamond.cif
```
ions file <filename> radius <r> <units>

Reads a coordinate file from <filename> and define a cell around the ions. The cell is orthorhombic and finite. The cell has the smallest possible size so that walls are at least distance ‘r’ from any atom. This is useful for molecular systems where you need to converge the size of the cell. The units for the radius value must be specified (check inq help units for details).

Note: right now this functionality is only implemented for XYZ files.
```
inq ions file glucose.xyz radius 2.0 A
```
(not available)

Imports the cell and ions from an Atomic Simulation Environment (ASE) object. This is only available for the Python interface.
```
(not available)
```

This command defines the ions present in the system and its coordinates. These can be given one by one using insert or from a file using file.

If you are adding ions one by one or reading an XYZ file, you must first declare the cell for system (see inq help cell or help(pinq.cell)).

These are the uses for the command:

ions.status()

Without any arguments (or status() in python), ions prints a list of the ions currently in the system.
```
pinq.ions.status()
```
ions.clear()

Removes any ions present in the system. Does not change the cell.
```
pinq.ions.clear()
```
ions.insert(symbol, [x, y, z], units)

Add an ion of type _symbol_ at coordinates _x_, _y_, and _z_. The units for the coordinates must be specified (check inq help units for details).
```
pinq.ions.insert("He", [0.0, 0.0, 2.0], "Angstrom")
```
ions.insert_fractional(symbol, [x, y, z])

Insert an ion of type _symbol_ at fractional coordinates _x_, _y_, and _z_.
```
pinq.ions.insert_fractional("Si", [0.25, 0.25, 0.25])
```
ions.remove(index)

Removes the ion given by _index_. Note that the ions indices start from 0, not 1.
```
pinq.ions.remove(3)
```
ions.file(filename)

Read a coordinate file given by <filename>. The supported formats are POSCAR, CIF and XYZ. For POSCAR and CIF both the ions and the cell information will be read. For XYZ only the atomic positions are read, so the cell must be defined before reading the file.
```
pinq.ions.file("diamond.cif")
```
ions.file(filename, radius, units)

Reads a coordinate file from <filename> and define a cell around the ions. The cell is orthorhombic and finite. The cell has the smallest possible size so that walls are at least distance ‘r’ from any atom. This is useful for molecular systems where you need to converge the size of the cell. The units for the radius value must be specified (check inq help units for details).

Note: right now this functionality is only implemented for XYZ files.
```
pinq.ions.file("glucose.xyz", 2.0, "A")
```
ions.from_ase(atoms)

Imports the cell and ions from an Atomic Simulation Environment (ASE) object. This is only available for the Python interface.
```
pinq.ions.from_ase(atoms)
```

4.7. The ‘kpoints’ command

This command defines the kpoints to be used in the simulation. Kpoints have to be given after the ions are defined.

Note that right now inq doesn’t use symmetries to reduce the kpoint grid.

These are the options available:

kpoints

Prints a list of the current kpoints in the simulation.
```
inq kpoints
```
kpoints gamma

Tells the system to only use the 0 0 0 point. This is the default.
```
inq kpoints gamma
```
kpoints grid <nx> <ny> <nz>

Define a uniform grid to sample the Brillouin zone with sizes _nx_, _ny_ and _nz_. This generates a non-shifted grid that will include gamma.
```
inq kpoints grid 8 8 8
```
kpoints shifted grid <nx> <ny> <nz>

Define a shifted uniform grid to sample the Brillouin zone with sizes _nx_, _ny_ and _nz_. This grid doesn’t include gamma.
```
inq kpoints shifted grid 4 4 4
```
kpoints insert <kx> <ky> <kz> <w>

Add a kpoint to the grid with coordinates _kx_, _ky_, _kz_, and weight _w_. The kpoint must be given in covariant coordinates in the range [-0.5, 0.5).
```
inq kpoints insert 0.25 0.25 0.25 1.0
```
kpoints clear

Removes all the kpoints defined in the grid.
```
inq kpoints clear
```

This command defines the kpoints to be used in the simulation. Kpoints have to be given after the ions are defined.

Note that right now inq doesn’t use symmetries to reduce the kpoint grid.

These are the options available:

kpoints.status()

Prints a list of the current kpoints in the simulation.
```
pinq.kpoints.status()
```
kpoints.gamma()

Tells the system to only use the 0 0 0 point. This is the default.
```
pinq.kpoints.gamma()
```
kpoints.grid(nx, ny, nz)

Define a uniform grid to sample the Brillouin zone with sizes _nx_, _ny_ and _nz_. This generates a non-shifted grid that will include gamma.
```
pinq.kpoints.grid(8, 8, 8)
```
kpoints.shifted_grid(nx, ny, nz)

Define a shifted uniform grid to sample the Brillouin zone with sizes _nx_, _ny_ and _nz_. This grid doesn’t include gamma.
```
pinq.kpoints.shifted_grid(4, 4, 4)
```
kpoints.insert(kx, ky, kz, w)

Add a kpoint to the grid with coordinates _kx_, _ky_, _kz_, and weight _w_. The kpoint must be given in covariant coordinates in the range [-0.5, 0.5).
```
pinq.kpoints.insert(0.25, 0.25, 0.25, 1.0)
```
kpoints.clear()

Removes all the kpoints defined in the grid.
```
pinq.kpoints.clear()
```

4.8. The ‘perturbations’ command

This command defines the perturbations applied to the system in a real-time simulations.

Note that the perturbations can be applied in different ways depending on the periodicity of the system. The gauge selection is done automatically by the code.

These are the uses for the command:

perturbations

Without any arguments (or with the status() function in Python), perturbations prints a the perturbations that are currently defined.
```
inq perturbations
```
perturbations clear

Removes any perturbations currently defined in the system.
```
inq perturbations clear
```
perturbations kick <px> <py> <pz>

Specifies a kick perturbation. This corresponds of a uniform time-dependent electric field. The time profile is a delta function at time 0. The direction and intensity of the field is given by the values _px_, _py_ and _pz_ (these values are in cartesian units and always considered in atomic units).

A kick has a flat profile in frequency space, so it will excite all frequencies equally. This is useful to obtain linear response properties.

For finite systems this kick is applied in the length gauge as a phase to the orbitals (this avoid time-discretization errors). For periodic systems, the kick is applied in the velocity gauge as a uniform vector potential.
```
inq perturbations kick 0.0 0.0 0.1
```
perturbations laser <px> <py> <pz> <frequency|wavelength> <f> <units>

Adds a laser perturbation. The laser is approximated by a monochromatic electric field (the magnetic part is ignored). The direction and intensity of the field is given by the values _px_, _py_ and _pz_ (in cartesian coordinated and always in atomic units).

You also have to specify the frequency of the laser using the keyword ‘frequency’ followed by its value and its units (you can use ‘eV’ or ‘THz’ for example, check inq help units for a full list of the energy units available).

Alternative you can use the keyword ‘wavelength’ followed by the wavelength of the laser and its units (typically ‘nm’).

For finite systems the laser is applied in the length gauge as a potential. For periodic systems, the laser is applied in the velocity gauge as a uniform vector potential.
```
inq perturbations laser  0    0    0.5 frequency  300 THz
inq perturbations laser -0.01 0.01 0   wavelength 880 nm
```

This command defines the perturbations applied to the system in a real-time simulations.

Note that the perturbations can be applied in different ways depending on the periodicity of the system. The gauge selection is done automatically by the code.

These are the uses for the command:

perturbations.status()

Without any arguments (or with the status() function in Python), perturbations prints a the perturbations that are currently defined.
```
pinq.perturbations.status()
```
perturbations.clear()

Removes any perturbations currently defined in the system.
```
pinq.perturbations.clear()
```
perturbations.kick([px, py, pz])

Specifies a kick perturbation. This corresponds of a uniform time-dependent electric field. The time profile is a delta function at time 0. The direction and intensity of the field is given by the values _px_, _py_ and _pz_ (these values are in cartesian units and always considered in atomic units).

A kick has a flat profile in frequency space, so it will excite all frequencies equally. This is useful to obtain linear response properties.

For finite systems this kick is applied in the length gauge as a phase to the orbitals (this avoid time-discretization errors). For periodic systems, the kick is applied in the velocity gauge as a uniform vector potential.
```
pinq.perturbations.kick([0.0, 0.0, 0.1])
```
currently not implemented

Adds a laser perturbation. The laser is approximated by a monochromatic electric field (the magnetic part is ignored). The direction and intensity of the field is given by the values _px_, _py_ and _pz_ (in cartesian coordinated and always in atomic units).

You also have to specify the frequency of the laser using the keyword ‘frequency’ followed by its value and its units (you can use ‘eV’ or ‘THz’ for example, check inq help units for a full list of the energy units available).

Alternative you can use the keyword ‘wavelength’ followed by the wavelength of the laser and its units (typically ‘nm’).

For finite systems the laser is applied in the length gauge as a potential. For periodic systems, the laser is applied in the velocity gauge as a uniform vector potential.
```
(currently not implemented)
```

4.9. The ‘real-time’ command

This command defines the options for real-time electron dynamics simulations. These are the available options:

real-time

When no arguments are given (or “status” in python), real-time will just print the currently defined options (including default values).
```
inq real-time
```
real-time time-step <value> <units>

Sets the time step for the real-time integration. In most cases you want to pick the largest value that gives you a stable propagation. Note you need to pass the units, you can use “atu” (or “atomictimeunits”), “as” or “fs” among others. The default value is 0.01 atu.
```
inq real-time time-step 0.1 atu
```
real-time num-steps <value>

The number of time-steps to do in the time propagation. The default value is 100.
```
inq real-time num-steps 10000
```
real-time propagation-time <value> <units>

Sets the number of step so that the total propagation time is (slightly larger than) value. You need to pass the units as a second argument, you can use “atu” (or “atomictimeunits”), “as” or “fs” among others.

Note that this variable directly calculates the number of steps based on the currently defined time-step. If the time-step is later changed the number of steps will remain unchanged and the propagation time will change.
```
inq real-time propagation-time 10.0 fs
```
real-time ions <value>

This value decides how the ions will move during the time-propagation. The options are: static, impulsive and ehrenfest.

The default is static where the ions don’t move during the propagation.

In impulsive the ions move with a constant velocity given by the initial conditions. This implies that the energy is not conserved.

The last option is ehrenfest dynamics, where the ions follow the instantaneous classical forces generated by the electrons.

Note that when ions move, inq has to recalculate the atomic potential at each step, so the propagation will be more costly.
```
inq real-time ions ehrenfest
```
real-time observables <value>

This value decides what observables will be calculated the time-propagation. Right now the options are are: dipole and current The total energy is also always calculated.

Several calls to this function will add more observables. Note that the calculated values will be stored internally by INQ. They can be queried after the simulation is complete with the results real-time command.
```
inq real-time observables current
```
real-time observables clear

This option removes all the observables that have been previously requested.
```
inq real-time observables clear
```

This command defines the options for real-time electron dynamics simulations. These are the available options:

real_time.status()

When no arguments are given (or “status” in python), real-time will just print the currently defined options (including default values).
```
pinq.real_time.status()
```
real_time.time_step(value, units)

Sets the time step for the real-time integration. In most cases you want to pick the largest value that gives you a stable propagation. Note you need to pass the units, you can use “atu” (or “atomictimeunits”), “as” or “fs” among others. The default value is 0.01 atu.
```
pinq.real_time.time_step(0.1, "atu")
```
real_time.num_steps(value)

The number of time-steps to do in the time propagation. The default value is 100.
```
pinq.real_time.num-steps(10000)
```
real_time.propagation_time(value, units)

Sets the number of step so that the total propagation time is (slightly larger than) value. You need to pass the units as a second argument, you can use “atu” (or “atomictimeunits”), “as” or “fs” among others.

Note that this variable directly calculates the number of steps based on the currently defined time-step. If the time-step is later changed the number of steps will remain unchanged and the propagation time will change.
```
pinq.real_time.propagation_time(10.0, "fs")
```
real_time.ions.static()` `real_time.ions.impulsive()` `real_time.ions.ehrenfest()

This value decides how the ions will move during the time-propagation. The options are: static, impulsive and ehrenfest.

The default is static where the ions don’t move during the propagation.

In impulsive the ions move with a constant velocity given by the initial conditions. This implies that the energy is not conserved.

The last option is ehrenfest dynamics, where the ions follow the instantaneous classical forces generated by the electrons.

Note that when ions move, inq has to recalculate the atomic potential at each step, so the propagation will be more costly.
```
pinq.real_time.ions.ehrenfest()
```
real_time.observables.dipole()` `real_time.observables.current()

This value decides what observables will be calculated the time-propagation. Right now the options are are: dipole and current The total energy is also always calculated.

Several calls to this function will add more observables. Note that the calculated values will be stored internally by INQ. They can be queried after the simulation is complete with the results real-time command.
```
pinq.real_time.observables.current()
```
real_time.observables.clear()

This option removes all the observables that have been previously requested.
```
pinq.real_time.observables.clear()
```

4.10. Results

The result command queries the results of a simulation that has been run in inq. Specific versions of the command exist for each simulation run. You can see the specific help for each one with:

inq help results ground-state
inq help results real-time

The result command queries the results of a simulation that has been run in inq. Specific versions of the command exist for each simulation run. You can see the specific help for each one with:

help(pinq.results.ground_state)
help(pinq.results.real_time)

4.11. The ‘results ground-state’ command

This command queries the results obtained from a ground-state calculation. Without arguments, it prints the values calculated.

The options allows you to query a specific value. In this case only the value will be printed without any other text, so it is suitable for easy parsing in scripting. The values are returned in atomic units.

These are the available subcommands:

results ground-state

When no arguments are given (or the status function is used), print the values calculated.
```
inq results ground-state
```
results ground-state iterations

Print the number of self-consistency iterations done.
```
inq results ground-state iterations
```
results ground-state magnetization [index]

Query the magnetization. In Python or if no additional arguments are given, print the whole 3D vector. For the shell, optionally you can add an index argument to print a specific component of the vector. The index can be given as the letters _x_, _y_ or _z_.

Note that for spin unpolarized systems the magnetization is always zero. For spin polarized the magnetization is assumed on the _z_ direction.
```
inq results ground-state magnetization z
```
results ground-state dipole [index]

Return the dipole of the system in atomic units. The whole vector is given if no additional arguments are included. In the CLI, you can also add an index argument to print a specific component. The index can be given as the letters _x_, _y_ or _z_.

Note that the dipole is only calculated for the non-periodic directions. For the periodic directions is set to zero since the dipole is not properly defined.
```
inq results ground-state magnetization z
```
results forces [iatom] [index]

Return the forces over the atoms in the system in atomic units. In Python this is an array. In the CLI, if no arguments are given, all the forces are printed. Alternatively is possible to pass an atom index (that starts from 0), or both an atom and direction index (_x_, _y_, or _z_).
```
inq results forces 7 z
```
results ground-state energy

When no arguments are given (or status() in Python), energy will print all the energy values available.
```
inq results ground-state energy
```
results ground-state energy total

Returns the total energy of the calculation. This includes the ionic contribution.
```
inq results ground-state energy total
```
results ground-state energy kinetic

The electronic kinetic energy.
```
inq results ground-state energy kinetic
```
results ground-state energy eigenvalues

The sum of the eigenvalues, weighed by the occupations.
```
inq results ground-state energy eigenvalues
```
results ground-state energy Hartree

The classical electrostatic interaction energy between electrons.
```
inq results ground-state energy Hartree
```
results ground-state energy external

The energy of the interaction of the electrons with the local potential generated by the ions. This doesn’t include the non-local pseudopotential part.
```
inq results ground-state energy external
```
results ground-state energy non-local

The energy of the interaction of the electrons with the non-local part of the ionic pseudo-potentials.
```
inq results ground-state energy non-local
```
results ground-state energy xc

The exchange and correlation energy from DFT semi-local functionals. It doesn’t include the contribution from Hartree-Fock exchange (see energy exact_exchange).
```
inq results ground-state energy xc
```
results ground-state energy nvxc

The energy of the interaction of the exchange and correlation potential and the density. This is different from the exchange and correlation energy.
```
inq results ground-state energy nvxc
```
results ground-state energy exact-exchange

The Hartree-Fock exact-exchange energy. This is calculated for Hartree-Fock and hybrid functionals.
```
inq results ground-state energy exact-exchange
```
results ground-state energy ion

The ion-ion interaction energy. This value is calculated taking into account the periodicity of the system.
```
inq results ground-state energy ion
```

This command queries the results obtained from a ground-state calculation. Without arguments, it prints the values calculated.

The options allows you to query a specific value. In this case only the value will be printed without any other text, so it is suitable for easy parsing in scripting. The values are returned in atomic units.

These are the available subcommands:

results.ground_state.status()

When no arguments are given (or the status function is used), print the values calculated.
```
pinq.results.ground_state.status()
```
results.ground_state.iterations()

Print the number of self-consistency iterations done.
```
pinq.results.ground_state.iterations()
```
results.ground_state.magnetization()

Query the magnetization. In Python or if no additional arguments are given, print the whole 3D vector. For the shell, optionally you can add an index argument to print a specific component of the vector. The index can be given as the letters _x_, _y_ or _z_.

Note that for spin unpolarized systems the magnetization is always zero. For spin polarized the magnetization is assumed on the _z_ direction.
```
pinq.results.ground_state.magnetization()
```
results.ground_state.dipole()

Return the dipole of the system in atomic units. The whole vector is given if no additional arguments are included. In the CLI, you can also add an index argument to print a specific component. The index can be given as the letters _x_, _y_ or _z_.

Note that the dipole is only calculated for the non-periodic directions. For the periodic directions is set to zero since the dipole is not properly defined.
```
pinq.results.ground_state.magnetization()
```
results.forces()

Return the forces over the atoms in the system in atomic units. In Python this is an array. In the CLI, if no arguments are given, all the forces are printed. Alternatively is possible to pass an atom index (that starts from 0), or both an atom and direction index (_x_, _y_, or _z_).
```
pinq.results.forces()
```
results.ground_state.energy.status()

When no arguments are given (or status() in Python), energy will print all the energy values available.
```
pinq.results.ground_state.energy.status()
```
results.ground_state.energy.total()

Returns the total energy of the calculation. This includes the ionic contribution.
```
pinq.results.ground_state.energy.total()
```
results.ground_state.energy.kinetic()

The electronic kinetic energy.
```
pinq.results.ground_state.energy.kinetic()
```
results.ground_state.energy.eigenvalues()

The sum of the eigenvalues, weighed by the occupations.
```
pinq.results.ground_state.energy.eigenvalues()
```
results.ground_state.energy.hartree()

The classical electrostatic interaction energy between electrons.
```
pinq.results.ground_state.energy.hartree()
```
results.ground_state.energy.external()

The energy of the interaction of the electrons with the local potential generated by the ions. This doesn’t include the non-local pseudopotential part.
```
pinq.results.ground_state.energy.external()
```
results.ground_state.energy.non_local()

The energy of the interaction of the electrons with the non-local part of the ionic pseudo-potentials.
```
pinq.results.ground_state.energy.non_local()
```
results.ground_state.energy.xc()

The exchange and correlation energy from DFT semi-local functionals. It doesn’t include the contribution from Hartree-Fock exchange (see energy exact_exchange).
```
pinq.results.ground_state.energy.xc()
```
results.ground_state.energy.nvxc()

The energy of the interaction of the exchange and correlation potential and the density. This is different from the exchange and correlation energy.
```
pinq.results.ground_state.energy.nvxc()
```
results.ground_state.energy.exact_exchange()

The Hartree-Fock exact-exchange energy. This is calculated for Hartree-Fock and hybrid functionals.
```
pinq.results.ground_state.energy.exact_exchange()
```
results.ground_state.energy.ion()

The ion-ion interaction energy. This value is calculated taking into account the periodicity of the system.
```
pinq.results.ground_state.energy.ion()
```

4.12. The ‘results real-time’ command

This command queries the results obtained from a real-time calculation. Without arguments, it prints the values calculated.

The options allows you to query a specific value. In this case only the value will be printed without any other text, so it is suitable for easy parsing in scripting. The values are returned in atomic units.

These are the available subcommands:

results real-time

When no arguments are given (ot the status() function in Python), print the available values.
```
inq results real-time
```
results real-time total-steps

Returns the total number of real-time simulation steps done.
```
inq results real-time total-steps
```
results real-time total-time

Returns the total simulated time (in atomic units).
```
inq results real-time total-time
```
results real-time time [step]

Returns the time values for each time-step.

In the shell, if not additional arguments are passed, inq prints the whole series for each time step. Alternatively, you can pass a step index to get the energy value.

For Python this functions returns an array and does not receive any arguments.

Note that for the moment inq uses a uniform time integration, so the time is just the step index times the time-step.
```
inq results real-time time
inq results real-time time 99
```
results real-time total-energy [step]

Returns the values of the total energy for each time step during the propagation.

For the shell, if not additional arguments are passed, inq prints the whole series for each time step in a two column format, the first column is the time and the second one is the energy. This output is suitable to view on a plotting program like gnuplot. Alternatively, you can pass a step index to get the energy value for that step.

For Python this functions returns an array and does not receive any arguments.
```
inq results real-time total-energy
inq results real-time total-energy 43
```
results real-time dipole [step] [dir]

Returns the values of the dipole for each time-step during the propagation. The value is in cartesian coordinates and atomic units. Note that the calculation of the dipole must be requested before running using the observables command.

Shell: If not additional arguments are passed, inq prints the whole series for each time step in a four column format, the first column is the time and the second, third and fourth ones are the x, y, and z components of the dipole, respectively. This output is suitable to view on a plotting program like gnuplot. Alternatively, you can pass a step index to get the dipole value for that step. An extra direction index (x, y or z) will return a single component of the dipole vector.

For Python this functions returns a two-dimensional array with the values of the dipole and does not receive any arguments. The first (leftmost) index is the time-step index while the second array index is the coordinate of the dipole.
```
inq results real-time dipole
inq results real-time dipole 7866
inq results real-time dipole 33 y
```
results real-time current [step] [dir]

Returns the values of the current for each time-step during the propagation. The value is in cartesian coordinates and atomic units. Note that the calculation of the current must be requested before running using the observables command.

Shell: If not additional arguments are passed, inq prints the whole series for each time step in a four column format, the first column is the time and the second, third and fourth ones are the x, y, and z components of the current, respectively. This output is suitable to view on a plotting program like gnuplot. Alternatively, you can pass a step index to get the current value for that step. An extra direction index (x, y or z) will return a single component of the current vector.

For Python this functions returns a two-dimensional array with the values of the current and does not receive any arguments. The first (leftmost) index is the time-step index while the second array index is the coordinate of the current.
```
inq results real-time current
inq results real-time current 183
inq results real-time current 97843 y
```

This command queries the results obtained from a real-time calculation. Without arguments, it prints the values calculated.

The options allows you to query a specific value. In this case only the value will be printed without any other text, so it is suitable for easy parsing in scripting. The values are returned in atomic units.

These are the available subcommands:

results.real_time.status()

When no arguments are given (ot the status() function in Python), print the available values.
```
pinq.results.real_time.status()
```
results.real_time.total_steps()

Returns the total number of real-time simulation steps done.
```
pinq.results.real_time.total_steps()
```
results.real_time.total_time()

Returns the total simulated time (in atomic units).
```
pinq.results.real_time.total_time()
```
results.real_time.time()

Returns the time values for each time-step.

In the shell, if not additional arguments are passed, inq prints the whole series for each time step. Alternatively, you can pass a step index to get the energy value.

For Python this functions returns an array and does not receive any arguments.

Note that for the moment inq uses a uniform time integration, so the time is just the step index times the time-step.
```
pinq.results.real_time.time()
```
results.real_time.total_energy()

Returns the values of the total energy for each time step during the propagation.

For the shell, if not additional arguments are passed, inq prints the whole series for each time step in a two column format, the first column is the time and the second one is the energy. This output is suitable to view on a plotting program like gnuplot. Alternatively, you can pass a step index to get the energy value for that step.

For Python this functions returns an array and does not receive any arguments.
```
pinq.results.real_time.total_energy()
```
results.real_time.dipole()

Returns the values of the dipole for each time-step during the propagation. The value is in cartesian coordinates and atomic units. Note that the calculation of the dipole must be requested before running using the observables command.

Shell: If not additional arguments are passed, inq prints the whole series for each time step in a four column format, the first column is the time and the second, third and fourth ones are the x, y, and z components of the dipole, respectively. This output is suitable to view on a plotting program like gnuplot. Alternatively, you can pass a step index to get the dipole value for that step. An extra direction index (x, y or z) will return a single component of the dipole vector.

For Python this functions returns a two-dimensional array with the values of the dipole and does not receive any arguments. The first (leftmost) index is the time-step index while the second array index is the coordinate of the dipole.
```
dip = pinq.results.real_time.dipole()
```
results.real_time.current()

Returns the values of the current for each time-step during the propagation. The value is in cartesian coordinates and atomic units. Note that the calculation of the current must be requested before running using the observables command.

Shell: If not additional arguments are passed, inq prints the whole series for each time step in a four column format, the first column is the time and the second, third and fourth ones are the x, y, and z components of the current, respectively. This output is suitable to view on a plotting program like gnuplot. Alternatively, you can pass a step index to get the current value for that step. An extra direction index (x, y or z) will return a single component of the current vector.

For Python this functions returns a two-dimensional array with the values of the current and does not receive any arguments. The first (leftmost) index is the time-step index while the second array index is the coordinate of the current.
```
curr = pinq.results.real_time.current()
```

4.13. The ‘run’ command

This command runs the actual simulation. It requires all the simulation parameters to be set before running.

Note that this is the expensive part in the execution on inq. Depending on the system you are using you might want to execute this in parallel or through a queuing system.

These are the options available:

run ground-state

Runs a ground-state calculation with fixed ions.
```
inq run ground-state
```
run real-time

Runs a real-time simulation.
```
inq run real-time
```
run resume

Restarts the run of a stopped simulation from a checkpoint. For the moment this only works for real-time simulations.
```
inq run resume
```

This command runs the actual simulation. It requires all the simulation parameters to be set before running.

Note that this is the expensive part in the execution on inq. Depending on the system you are using you might want to execute this in parallel or through a queuing system.

These are the options available:

run.ground_state()

Runs a ground-state calculation with fixed ions.
```
pinq.run.ground_state()
```
run.real_time()

Runs a real-time simulation.
```
pinq.run.real_time()
```
run.resume()

Restarts the run of a stopped simulation from a checkpoint. For the moment this only works for real-time simulations.
```
pinq.run.resume()
```

4.14. The ‘species’ command

This command defines speciess the actual simulation.

These are the options available:

species

Shows the species currently defined in the simulation.
```
inq species
```
species set

Returns the current pseudopotential set that will be used by default for all species in the simulation.
```
inq species set
```
species list-sets

Prints a list of the available pseudopotentials.
```
inq species list-sets
```
species set <set name>

Selects the pseudopotential set that will be used by default for all species in the simulation. The name must be one those returned by the list-sets command.
```
inq species set sg15
```
species add <element>

Adds a new species of given by <element>. The element must be a IUPAC recognized element chemical symbol.
```
inq species add Tc
```
species add <symbol> element <element>

Adds a new species given by its <symbol> as an alias to <element>. Note that element must be a IUPAC recognized element symbol.
```
inq species add proton element H
```
species add <symbol> atomic_number <z>

Adds a new species given by its <symbol> as an alias to the chemical element with atomic number <z>.
```
inq species add C14 atomic-number 6
```
species <symbol> set <set name>

Sets the pseudopotential set that will be used for the species given by <symbol>.
```
inq species He set sg15
```
species <symbol> file <filename>

Sets the pseudopotential file that will be used for the species given by <symbol>.
```
inq species Xe file Xe.upf
```
species <symbol> mass <value>

Sets the ionic mass for the species given by <symbol>. The mass must be given in atomic mass units (amu). They should not be confused with atomic units of mass. In amu the mass of a carbon atom is 12.
```
inq species U mass 235
```

This command defines speciess the actual simulation.

These are the options available:

species.status()

Shows the species currently defined in the simulation.
```
pinq.species.status()
```
species.pseudo_set()

Returns the current pseudopotential set that will be used by default for all species in the simulation.
```
pinq.species.pseudo_set()
```
species.list_sets()

Prints a list of the available pseudopotentials.
```
pinq.species.list_sets()
```
species.pseudo_set("set_name")

Selects the pseudopotential set that will be used by default for all species in the simulation. The name must be one those returned by the list-sets command.
```
pinq.species.set("sg15")
```
species.add("element")

Adds a new species of given by <element>. The element must be a IUPAC recognized element chemical symbol.
```
pinq.species.add("Tc")
```
species.add_by_element("symbol", "element")

Adds a new species given by its <symbol> as an alias to <element>. Note that element must be a IUPAC recognized element symbol.
```
pinq.species.add_by_element("proton", "H")
```
species.add_by_atomic_number("symbol", z)

Adds a new species given by its <symbol> as an alias to the chemical element with atomic number <z>.
```
pinq.species.add_by_atomic_number("C14", 6)
```
species.pseudo_set("symbol", "set_name")

Sets the pseudopotential set that will be used for the species given by <symbol>.
```
pinq.species.set("He", "sg15")
```
species.file("symbol", "filename")

Sets the pseudopotential file that will be used for the species given by <symbol>.
```
pinq.species.file("Xe", "Xe.upf")
```
species.mass("symbol", value)

Sets the ionic mass for the species given by <symbol>. The mass must be given in atomic mass units (amu). They should not be confused with atomic units of mass. In amu the mass of a carbon atom is 12.
```
pinq.species.mass("U", 235)
```

4.15. The ‘spectrum’ command

This command is used to calculate spectra of different types using the results of calculations.

These are the options available:

spectrum file <filename>

Calculates an absorption spectra based on a dipole series. The spectrum data is printed to the terminal as two data columns, the first one is the frequency/energy and the second one is the spectrum for all input columns.
```
inq spectrum file data.txt
```

This command is used to calculate spectra of different types using the results of calculations.

These are the options available:

spectrum.file(filename)

Calculates an absorption spectra based on a dipole series. The spectrum data is printed to the terminal as two data columns, the first one is the frequency/energy and the second one is the spectrum for all input columns.
```
pinq.spectrum.file("data.txt")
```

4.16. The ‘status’ command

Prints all the currently defined parameters and available results.

4.17. The ‘theory’ command

This command specified the theory level used to model the electron-electron interaction. Most of the time you will want to use some form of density functional theory (DFT) but some other options are available. This command will allow you to pick up the DFT functional you want to use, the most popular ones have a specific option or you can use the functional command to select any functional from libxc.

These are the options available:

theory

Without any argument, theory will just print the current theory level that is set.
```
inq theory
```
theory dft` (default)

This is the default, DFT in the PBE approximation is used to model the electron-electron interaction.
```
inq theory dft
```
theory non-interacting

There is no electron-electron interaction, particles are assumed to be independent.
```
inq theory non-interacting
```
theory hartree

Particles only interact through classical electrostatics. Note that as implemented in inq, hartree does not include a self-interaction correction term.
```
inq theory hartree
```
theory hartree-fock

Exchange is modeled by the Hartree-Fock method. Note that this method is much more expensive than pure DFT.
```
inq theory hartree-fock
```
theory lda

The local density approximation in DFT.
```
inq theory lda
```
theory pbe

The PBE GGA approximation in DFT.
```
inq theory pbe
```
theory pbe0

The PBE0 (also known as PBEH) hybrid functional. Note that this functional includes Hartree-Fock exact exchange, so it is much more computationally expensive than GGA functionals like pbe.
```
inq theory pbe0
```
theory b3lyp

The B3LYP hybrid functional. Note that this functional includes Hartree-Fock exact exchange, so it is much more computationally expensive than GGA functionals like pbe.
```
inq theory b3lyp
```
theory functional <exchange_name> [correlation_name]

This option allows you to select any functional combination from the libxc library using the functional names (functional id numbers are not supported). Note that the correlation functional is optional, it is okay to pass just one functional. You can find a list of libxc functionals here [1].

[1] https://www.tddft.org/programs/libxc/functionals/ Examples: inq theory functional XC_GGA_X_RPBE XC_GGA_C_PBE inq theory functional LDA_XC_TETER93

This command specified the theory level used to model the electron-electron interaction. Most of the time you will want to use some form of density functional theory (DFT) but some other options are available. This command will allow you to pick up the DFT functional you want to use, the most popular ones have a specific option or you can use the functional command to select any functional from libxc.

These are the options available:

theory.status()

Without any argument, theory will just print the current theory level that is set.
```
pinq.theory.status()
```
theory.dft()

This is the default, DFT in the PBE approximation is used to model the electron-electron interaction.
```
pinq.theory.dft()
```
theory.non_interacting()

There is no electron-electron interaction, particles are assumed to be independent.
```
pinq.theory.non_interacting()
```
theory.hartree()

Particles only interact through classical electrostatics. Note that as implemented in inq, hartree does not include a self-interaction correction term.
```
pinq.theory.hartree()
```
theory.hartree_fock()

Exchange is modeled by the Hartree-Fock method. Note that this method is much more expensive than pure DFT.
```
pinq.theory.hartree_fock()
```
theory.lda()

The local density approximation in DFT.
```
pinq.theory.lda()
```
theory.pbe()

The PBE GGA approximation in DFT.
```
pinq.theory.pbe()
```
theory.pbe0()

The PBE0 (also known as PBEH) hybrid functional. Note that this functional includes Hartree-Fock exact exchange, so it is much more computationally expensive than GGA functionals like pbe.
```
pinq.theory.pbe0()
```
theory.b3lyp()

The B3LYP hybrid functional. Note that this functional includes Hartree-Fock exact exchange, so it is much more computationally expensive than GGA functionals like pbe.
```
pinq.theory.b3lyp()
```
theory functional <exchange_name> [correlation_name]

This option allows you to select any functional combination from the libxc library using the functional names (functional id numbers are not supported). Note that the correlation functional is optional, it is okay to pass just one functional. You can find a list of libxc functionals here [1].

[1] https://www.tddft.org/programs/libxc/functionals/ Examples: inq theory functional XC_GGA_X_RPBE XC_GGA_C_PBE inq theory functional LDA_XC_TETER93

4.18. Units in inq

In inq all physical quantities given to the code must also include the units they are in. There are two main objectives for this. First, it allows users to use the units directly from the source without having to waste time converting. Second, it avoids errors when users assume the code is expecting different units.

The code works internally in Hartree atomic units, and most of the quantities are printed in these units. However, when space allows for it, we print quantities in other relevant units.

In the command line interface units are given as an argument after a value, or a set of values. There are no default input units in inq. Not putting the units is a syntax error and the command most likely fail or produce unexpected behavior.

This page lists the supported units in inq for different magnitudes. All units are case insensitive, have abbreviations and can be given in plural form.

Energy * ‘Hartree’ or ‘Ha’ * ‘Electronvolt’ or ‘eV’: 0.0367493221756544 Ha * ‘Rydberg’ or ‘Ry’: 0.5 Ha * ‘Kelvin’ or ‘K’ (times the Boltzmann constant): 3.16681156345556e-06 Ha * ‘teraHertz’ or ‘THz’ (times the Planck constant): 1.51982850071590e-4 Ha
Length * ‘Bohr’ or ‘b’ * ‘Angstrom’ or ‘A’: 1.88972612462938 b * ‘nanometer’ or ‘nm’: 10 A * ‘picometer’ or ‘pm’: 0.01 A
Time * ‘Atomictime’ or ‘atu’ * ‘attosecond’ or ‘as’: 0.0413413733352975 atu * ‘femtosecond’ or ‘fs’: 41.3413733352975 atu * ‘nanosecond’ or ‘ns’: 1000 fs * ‘picosecond’ or ‘ps’: 1000 ns

4.19. The ‘util’ command

This command provided some simple utilities for use in scripts or for the testing of inq.

These are the available subcommands:

util match calc <math-expression>

Calculates the result of the given mathematical expression. This is useful if you need to calculate a value in a script or double check the result of an expression you are giving to inq in an argument.

This function is not available in Python, since mathematical expressions can be evaluated directly by the language.
```
inq util calc "1/sqrt(2.0) + exp(-1/2)"
```
util match <value1> <value2> ... <tolerance>

Checks if two set of values match within a certain tolerance. If they match, the command will run successfully, with a 0 return code. If the match fails, then the command will fail with a return value of 1.

In Python the values can be scalar or arrays (of the same size). The function will return true if the values match or false otherwise.

When more than two values are passed, it is assumed these are two sets given in sequential order. For example, if 6 values are passed inq assumes than the first 3 are one set and the second 3 another one. Then comparisons are made between the first value with the fourth one, the second with the fifth, and the third with the sixth one.
```
inq util match 1.0 2.0 1e-5
inq util match  1.0 0.0 0.0  1.001 1e-12 1e-23  1e-2
```
util test-data

Returns the path where inq install the data files used for tests. This is not really useful for users, it is mainly for testing.
```
inq util test-data
```

This command provided some simple utilities for use in scripts or for the testing of inq.

These are the available subcommands:

(not available)

Calculates the result of the given mathematical expression. This is useful if you need to calculate a value in a script or double check the result of an expression you are giving to inq in an argument.

This function is not available in Python, since mathematical expressions can be evaluated directly by the language.
```
(not available)
```
util.match(value1, value2, tolerance)

Checks if two set of values match within a certain tolerance. If they match, the command will run successfully, with a 0 return code. If the match fails, then the command will fail with a return value of 1.

In Python the values can be scalar or arrays (of the same size). The function will return true if the values match or false otherwise.

When more than two values are passed, it is assumed these are two sets given in sequential order. For example, if 6 values are passed inq assumes than the first 3 are one set and the second 3 another one. Then comparisons are made between the first value with the fourth one, the second with the fifth, and the third with the sixth one.
```
pinq.util.match(1.0, 2.0, 1e-5)
pinq.util.match([1.0, 0.0, 0.0], [1.001, 1e-12, 1e-23], 1e-2)
```
util.test_data()

Returns the path where inq install the data files used for tests. This is not really useful for users, it is mainly for testing.
```
pinq.util.test_data()
```