Python API¶
Advance/NanoLabo provides an interface that allows it to be operated from external programs. By importing the included Python module, you can utilize functions to control NanoLabo directory from Python.
Preparation¶
Both Python 2.x and Python 3.x environments are supported. For setting up and using Python, please consult the Python documentation .
On Windows, pywin32 module is required. To install it using pip, execute the following command:
> python -m pip install pywin32
The module file nanolabo.py can be found in the python folder within the NanoLabo installation folder on Windows / Linux. For macOS users, it is located in /Library/Application Support/AdvanceSoft/NanoLabo/python . You can copy this file to a location of your choice. Once imported, you can access the functions using the module name nanolabo .
>>> import nanolabo
You can view the module help by using built-in functions as follows:
>>> help(nanolabo) #display help
>>> dir(nanolabo) #display list of functions etc.
>>> help(nanolabo.open_project) #display each function's help
Note
Before starting any operation, ensure that the target NanoLabo is launched. If multiple instance of NanoLabo are running, the one launched first will the one that accepts operations from Python.
Functions list¶
Project operation¶
- open_project(path)¶
Open a project.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
Example¶>>> nanolabo.open_project(r"C:\Users\demouser\.nanolabo\SiC") >>> nanolabo.open_project("SiC") #project in default location
- close_project(path)¶
Close a project.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
Example¶>>> nanolabo.close_project(r"C:\Users\demouser\.nanolabo\SiC") >>> nanolabo.close_project("SiC") #project in default location
- save_project(path[, dst_path=""])¶
Save a project.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
dst_path (str) – Designate the save destination for the project using the absolute path of the folder. If you wish to save it in the default location, just provide the project name. However, if the specified folder already exists, the project will not be saved. If no path is provided, the software will overwrite the project specified by path.
Example¶>>> nanolabo.save_project("SiC", "SiC2") #save as another project >>> nanolabo.save_project(r"C:\Users\demouser\.nanolabo\SiC") #overwrite save
- mode_project(path, mode)¶
Change calculation engine of a project.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
mode (str) – Specify calculation engine of the project. Can be: “QuantumESPRESSO”, “LAMMPS”
Example¶>>> nanolabo.mode_project("SiC", "LAMMPS")
- run_project(path[, jobType=""[, host=""[, queue=""]]])¶
Run the calculation. If you are submitting a job to remote server, ensure that you have completed SSH server settings beforehand.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
jobType (str) – Specify the type of calculation. If not specifieded, it will be determined by the currently opened calculation engine and input editor mode in the project. Options include: “SCF”, “OPTIMIZ”, “MD”, “DOS”, “BAND”, “TDDFT”, “Phonon”, “PhDisp”, “NEB”, “LAMMPS”
host (str) – Specify “localhost” to run the job locally or provide the name of the remote server to post the job. If not provided, the setting from the previous calculation will be used.
queue (str) – Specify the name of the queue setting for posting the job. This setting will be ignored if running locally, even if specified.
Example¶>>> nanolabo.run_project("SiC", "SCF", "localhost") #local run >>> nanolabo.run_project("SiC", "SCF", "hostname", "queuename") #post remote job
- create_project(file_path[, project_path=""])¶
Create new project from atomic structure file.
- Parameters:
file_path (str) – Specify the atomic structure file using the absolute path. The file in the current folder can be specified just by the file name.
project_path (str) – Specify the location to save the created project by provideing the absolute path of the folder. To save it in the default location, simply specify the project name. If the project name is not specified, the name of the atomic structure file (without extension) will be used as the project name. If the specified folder already exists, the project will not be created.
Example¶>>> nanolabo.create_project(r"C:\Users\demouser\sic.cif", "SiC")
Atomic structure operation¶
- clear_all_atoms(path)¶
Clear all atoms.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
Example¶>>> nanolabo.clear_all_atoms("SiC")
- set_all_atoms(path, atomsFile)¶
Import atomic structure from file. Geometry information already in the project will be overwritten.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
atomsFile (str) – Specify the file that contains information about the atomic structure. A file in the current folder can be specified simply by the file name.
The file format is as follows. The file exported by
qe_get_geometry()can be imported.3.09200995 0.00000000 0.00000000 # ax ay az -1.54600497 2.67775791 0.00000000 # bx by bz 0.00000000 0.00000000 5.07335137 # cx cy cz 4 # number of atoms Si -0.000002 1.785172 2.534588 1 1 1 # name x y z FIXED_X FIXED_Y FIXED_Z Si 1.546002 0.892585 5.071262 0 0 0 # 0:fixed, 1:mobile C -0.000002 1.785172 4.441264 0 0 0 C 1.546002 0.892585 1.904590 0 0 0
Example¶>>> nanolabo.set_all_atoms("SiC", r"C:\Users\demouser\sic.txt")
- get_lattice(path)¶
Get lattice vectors.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
- Returns:
Lattice vectors
- Return type:
list[list[float]]
Example¶>>> nanolabo.get_lattice("SiC") [[3.09201, 0.0, 0.0], [-1.546005, 2.677759208755522, 0.0], [0.0, 0.0, 5.07335]]
- set_lattice(path, lattice)¶
Set lattice vectors.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
lattice (list[list[float]]) – Specify lattice vectors.
Example¶>>> nanolabo.get_lattice("SiC", [[3.09201, 0.0, 0.0], [-1.546005, 2.677759208755522, 0.0], [0.0, 0.0, 5.07335]])
- num_atoms(path)¶
Get number of atoms.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
- Returns:
Number of atoms
- Return type:
int
Example¶>>> nanolabo.num_atoms("SiC") 4
- add_atom(path, name, x, y, z)¶
Add an atom.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
name (str) – Specify which type of atom should be added using its corresponding element symbol.
z (float x, y,) – Specify x, y, z coordinates (Å).
Example¶>>> nanolabo.add_atom("SiC", "C", 0.5, 0.5, 0.5) >>> coords = [0.5, 0.5, 0.5] >>> nanolabo.add_atom("SiC", "C", *coords) #unpack list at passing
- remove_atom(path, index)¶
Remove an atom.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
index (int) – Specify atom to be removed by serial number. The index starts at 0*.
Example¶>>> nanolabo.remove_atom("SiC", 0)
- get_atom_name(path, index)¶
Get type of an atom.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
index (int) – Specify atom by serial number. The index starts at 0*.
- Returns:
Type of atom (element symbol)
- Return type:
str
Example¶>>> nanolabo.get_atom_name("SiC", 0) 'Si'
- get_atom_xyz(path, index)¶
Get coordinates of an atom.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
index (int) – Specify atom by serial number. The index starts at 0*.
- Returns:
Atom coordinates (Å) and fixed (0) or mobile (1) status along each direction
- Return type:
[list[float], list[int]]
Example¶>>> nanolabo.get_atom_xyz("SiC", 0) [[1.5019770000000001, 2.1822290000000004, 3.2716700000000007], [1, 1, 1]]
- set_atom_name(path, index, name)¶
Change an atom.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
index (int) – Specify atom by serial number. The index starts at 0*.
name (str) – Specify the atom type by using the element symbol.
Example¶>>> nanolabo.set_atom_name("SiC", 0, "C")
- set_atom_xyz(path, index, x, y, z[, xfix=1][, yfix=1][, zfix=1])¶
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
index (int) – Specify atom by serial number. The index starts at 0*.
z (float x, y,) – Specify x, y, z coordinates (Å).
zfix (int xfix, yfix,) – Fixed (0) or mobile (1) in the x, y, z direction. The default is mobile (1) if not specified.
Example¶>>> nanolabo.set_atom_xyz("SiC", 0, 0.5, 0.5, 0.5, 0, 0, 0) #fixed along all directions >>> nanolabo.set_atom_xyz("SiC", 0, 0.5, 0.5, 0.5, zfix=0) #mobile along xy, fixed only along z
Note
Serial number (#) shown in the Geometry→Atoms starts at 1, resulting in a one-index shift (orders remaining the same).
Operation related to Quantum ESPRESSO¶
- qe_get_kpoints(path)¶
Get number of k points for SCF calculation. For more imformation, please refer to Quantum ESPRESSO manual (K_POINTS automatic).
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
- Returns:
Number of k points in each direction, and if apply the offset (1) or not (0)
- Return type:
list[list[int]]
Example¶>>> nanolabo.qe_get_kpoints("SiC") [[4, 4, 2], [0, 0, 0]]
- qe_set_kpoints(path, nk1, nk2, nk3, sk1, sk2, sk3)¶
Set number of k points for SCF calculation. For more imformation, please refer to Quantum ESPRESSO manual (K_POINTS automatic).
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
nk3 (int nk1, nk2,) – Number of k points
sk3 (int sk1, sk2,) – if apply the offset (1) or not (0)
Example¶>>> nanolabo.qe_set_kpoints("SiC", 4, 4, 2, 0, 0, 0)
- qe_get_mass(path, name)¶
Get the currently set atomic mass ** for an element.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
name (str) – Specify element by element symbol.
- Returns:
Mass of the element (atomic mass unit)
- Return type:
float
Example¶>>> nanolabo.qe_get_mass("SiC", "Si") 28.0855
- qe_set_mass(path, name, mass)¶
Set atomic mass ** for an element.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
name (str) – Specify element by element symbol.
mass (float) – Specify mass of the element (atomic mass unit).
Example¶>>> nanolabo.qe_set_mass("SiC", "Si", 28.0855)
Note
Mass for each element is separately configured for every calculation engine.
- qe_get_pseudo(path, name)¶
Get the currently set pseudo potential for an element.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
name (str) – Specify element by element symbol.
- Returns:
Pseudo potential file name
- Return type:
str
Example¶>>> nanolabo.qe_get_pseudo("SiC", "Si") 'Si.pbe-rrkj.UPF'
- qe_set_pseudo(path, name, pseudo)¶
Set pseudo potential for an element.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
name (str) – Specify element by element symbol.
pseudo (str) – Specify the pseudo potential by file name.
Example¶>>> nanolabo.qe_set_pseudo("SiC", "Si", "Si.pbe-rrkj.UPF")
- qe_get_total_energy(path)¶
Get the total energy obtained from the SCF calculation.
- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
- Returns:
if the SCF calculation has converged (1) or not (0), and the value of total energy (Ry)
- Return type:
[int, float]
Example¶>>> nanolabo.qe_get_total_energy("SiC") [1, -38.43756505]
- qe_get_geometry(path)¶
Export atomic structure information obtained through first principle structure optimization to
home directory/.nanolabo/.tmp_inquiry. You can import the file using theset_all_atoms()function.- Parameters:
path (str) – Designate the project using the absolute path of the folder. If the project is stored in the default location, you can simply specify it by the project name.
- Returns:
if structure optimization is converged
- Return type:
bool
Example¶>>> nanolabo.qe_get_geometry("SiC") True