Table of Contents
- Getting Started
- Tutorial about PFP
- Other Notebook features
- How to set up Estimator
- Basic ASE Modules
- Frequently used Python packages
- JupyterLab shortcut
- About PFVM
Getting Started
If you are new to PFP, please try the following manuals and examples first.
- Documents > Matlantis Guidebook
- Documents > About PFP
- from Example launcher
- Matlantis Examples> Basics > Welcome
- Matlantis Examples > Basics > How to use PFP
In addition, for supplemental information, see also
- Documents > About DFT-D3
- Documents > PFP API Client Reference
- Matlantis Examples > Basic > About DFT-D3
To make inputs for Gaussian and VASP, please refer to the following.
- Matlantis Examples > Miscellaneous > DFT calculation : Gaussian 16 input file
- Matlantis Examples > Miscellaneous > DFT calculation : VASP5 input
How to access Documents:
There are three ways to access documents.
How to access from the Notebook environment:
- (1) from Basic Launcher
- (2) from Help menu
How to access from the Dashboard screen:
How to open Example launcher sample files:
Here describes how to open the Welcome page from Example laucher.
- Open the Example launcher by clicking on the following icon.
- Find Matlantis Examples > Basics > Welcome.
- Select a suitable one from the icons to the right of the file name and copy it onto your own workspace. You can also preview the contents.
- (1) Copy to the location currently open in the File Browser.
- (2) Copy to the specified workspace. Click to select any directory.
- (3) Preview the file.
Tutorial about PFP
To use Maltantis' general-purpose neural network PFP (Preferred Potential), first install a package for using PFP, including an ASE called pfp-api-client.
from Matlantis Examples > Basics > Welcome
How to install the package
How to install from the Package launcher:
The following packages can be installed from the Pckage launcher as follows.
- pfp-api-client
- matlantis-features
- matlantis-group-drive-client
- Open the Package launcher.
- Click the install button for the latest version.
- Choose a Python version and install it.
If the installation is successful, you will see something like the following.
* For information on how to install pfcc-extras, please click here.
* For more infomation about matlantis-lammps, click here.
how to do it using pip:
It can also be installed using "pip". Use "pip" for packages such as cannot be installed from the Package laucher. *FYI: Frequently used Python packages
- When running "pip" on the Notebook:
Execute the command with a leading "!(exclamation mark)" at the beginning of the command.
!pip install pfp-api-client
- To run pip from a Terminal:
To open a terminal in the Matlantis environment, open it from File > new > Terminal as follows. Once the terminal is open, you can run pip by activating the Python environment. (See here for instructions on how to activate the Python environment here.)
Overall structure of Matlantis packages
- pfp-api-client:
Infer energy/force using machine learning potential PFP.
- matlantis-features：
It includes features that use PFP internally to calculate various physical properties, as well as functions such as post-calculation features that do not call PFP but analyze the results.
- DipoleFeatures
- ElasticTesorFeature
- VibrationFeature
- ForceConstantFeature
- ReactionStringFeature
- PostVibrationGasThermoFeature
- PostMDDiffusionFeature
- PostEMDViscosityFeature
- PostNEMDViscosityFeature
- PostPhononBandFeature
- PostPhononDOSFeature
- PostNEMDThermalConductivityFeature
- etc…
from Matlantis Guidebook > Introduction > Overall structure of Matlantis packages
relationship to ASE
- Atomistic Simulation Environment (ASE) is a Python package widely used in molecular simulations. * FYI: Basic ASE Modules
- By linking ASE with pfp-api-client and matlantis-features, you can easily perform structural optimization and molecular dynamics (Molecular Dynamics, MD) using PFP.
- Many of the examples we provide are examples using ASE.
- In ASE, the system to be calculated is defined in the Atoms class, and by setting an arbitrary Calculator, various methods can be invoked to calculate energy and force.
- PFP calculation can be easily performed by creating an instance from the Estimator class of pfp-api-client and setting it to Calculator. For more information about Estimator settings, please click here.
- Example of what can be calculated by setting Calculator to atoms.calc:
- potential energy: atoms.get_potential_energy()
- force: atoms.get_forces()
- charge: atoms.get_charges()
Calculation mode and Model version
- PFP has Seven calculation modes.
- The correspondence with the names of the conventional (old) calculation modes is as follows
※ The D3 correction is not applied to the calculation method of the training data, but is accounted for by being added to the inferred values.Calculation mode Calculation mode Computational methods for training data PBE CRYSTAL_U0 PBE/PAW only PBE_PLUS_D3 CRYSTAL_U0_PLUS_D3 PBE/PAW + Grimme-D3※ PBE_U CRYSTAL PBE/PAW with Hubbard correction CRYSTAL_U0_PLUS_D3 CRYSTAL_U0_PLUS_D3 PBE/PAW with Hubbard correction+ Grimme-D3※ MOLECULE MOLECULE ωB97xd/6-31G(d)
- The default and available calculation modes vary depending on the version (PBE_U is the default up to v3.0.0, and PBE is the default from v4.0.0 onwards). We recommend explicitly specifying both the calculation mode and the version when using them (please refer here for instructions on how to specify both the calculation mode and the version simultaneously).
from Matlantis Guidebook > PFP Versions > Calculation modes supported by each PFP version > Overview of calculation modes, Overview of calculation modes supported by each PFP version and therir default modes
Specify Calculation mode
- The calculation mode (calc_mode) is specified as follows.
from Matlantis Examples > Basics > How to use PFP
Specify Model version
The model version is specified as follows.
from Matlantis Examples > Basics > How to use PFP
Specify calculation mode and model version at the same time (recommended)
It is recommended that the model version and calculation mode be explicitly specified.
- The model version and calculation mode can be specified simultaneously as text, as follows.
example:
from pfp_api_client import Estimator, ASECalculator
model_version = "v5.0.0"
calc_mode = "CRYSTAL_U0_PLUS_D3"
estimator = Estimator(model_version=model_version, calc_mode=calc_mode)
calculator = ASECalculator(estimator)
- The method of specifying Estimator differs between pfp-api-client and matlantis-features. Please see also here.
Hubbard correction and D3 dispersion correction
Hubbard correction
Please see below for U-J values.
About PFP > Training dataset > Calculation conditions > GGA+U
DFT-D3 correction
The D3 correction is not applied to the calculation method of the training data, but is accounted for by being added to the inferred values.
As a difference from the original DFT-D3, the cutoff distance is changed to 40 Bohr.
See also the article describing torch-dftd and its implementation.
from About DFT-D3 > D3 correction with PFP
Unit System and boundary conditions
from About PFP > Architecture description > Unit system, Periodic boundary conditions
Supported Element
It is calculable for the 96 colored elements.
from About PFP > Supported calculation targets > Element support status and pseudopotentials
Experimental / Unexperimental elements
There are currently no Unexperimental elements (since PFP v7).
from About PFP > Supported calculation targets > Support status of chemical elements (2024.09)
Supported calculation targets
from About PFP > Supported calculation targets > Calculation modes
Other Notebook Features
For general JupyterLab operation, please refer to the official documentation here.
Frequently used shortcuts are listed here.
Switching the Python kernel
- The kernel Python can be toggled by clicking on the "Python 3.x" indicator in the upper right corner of the notebook, as shown below.
- In the terminal, switch the Python kernel using the use_venv command as follows.
from Matlantis Guidebook > Other Notebook features > Switching the Python kernel
Background Job
- The Background Job function creates a copy of the current notebook file (*.ipynb) and runs the copied notebook as a background job.
- Jobs are added to the queue when the maximum number of parallel executions possible (default 3) is exceeded
-
You can receive notifications when calculations finished runnning in the background job. (The email address for notifications can be set in Matlantis Setting)
-
If you experience problems with background jobs, such as not being able to run new jobs or access execution history, you may be able to resolve the problem by trying to reset the state of the Background Job. This operation deletes the execution history of background jobs and temporary files in the process of calculation (it does not delete already calculated data). See Dashboard - Advanced for instructions on how to reset the status of background jobs. If the problem persists, please contact us.
from Matlantis Guidebook > About Backbround Job > How to use Background Job
Priority function
When Token Availability is less than 100, you can set which calculation is prioritized.
- Priority 100: Attempts to calculate regardless of Token Availabitlity (maximum priority)
- Priority 25: Calculations will be held until Token Availability is greater than 75%.
* If nothing is set, the default value of 100 is applied.
* Please refer to PFP Load Status for Token Availability.
How to request Priority:
- Setting in the costructor of the Estimator class
- Configuration using the variable Config.priority
- Setting the environment variable named PFP_DEFAULT_PRIORITY
- Specified at Backgroud job execution
from Matlantis Guidebook > About pfp-api-client > About Token System and Priority Function > Request Priority
About the logging of pfp-api-client
You can use this function to record the calculation mode and PFP version used in your calculations
from Matlantis Guidebook > About pfp-api-client > About the logging of pfp-api-client
Appendix:
How to set up Estimator
The method of setting up Estimator for ASE differs between pfp-api-client and matlantis-features.
- pfp-api-client
from pfp_api_client.pfp.calculators.ase_calculator import ASECalculator
from pfp_api_client.pfp.estimator import Estimator
estimator = Estimator(model_version=”v4.0.0”, calc_mode=EstimatorCalcMode.CRYSTAL_U0)
calculator = ASECalculator(estimator)
atoms.calc = calculator
- matlantis-features
There are two methods: using environment variables or estimator_fn. If both are specified, the estimator_fn setting takes precedence.
- Using Environment Variables:
from ase.build import molecule
import os
from pfp_api_client.pfp.estimator import Estimator
from pfp_api_client.utils.messages import MessageEnum
from matlantis_features.features.common.opt import FireASEOptFeature
os.environ["MATLANTIS_PFP_MODEL_VERSION"] = "v4.0.0"
os.environ["MATLANTIS_PFP_CALC_MODE"] = "crystal_plus_d3"
atoms = molecule("CH3OH")
opt = FireASEOptFeature()
result = opt(atoms)
- Using Environment Variables:
-
- Using estimator_fn (1)
from ase.build import molecule
from pfp_api_client.pfp.estimator import EstimatorCalcMode
from matlantis_features.features.common.opt import FireASEOptFeature
from matlantis_features.utils.calculators import pfp_estimator_fn
atoms = molecule("CH3OH")
opt = FireASEOptFeature(
estimator_fn=pfp_estimator_fn(
model_version="v2.0.0",
calc_mode=EstimatorCalcMode.CRYSTAL_PLUS_D3,
),
)
result = opt(atoms)
- Using estimator_fn (1)
-
- Using estimator_fn (2)：
Define your own estimator_fn
from ase.build import molecule
from pfp_api_client.pfp.estimator import Estimator, EstimatorCalcMode
from pfp_api_client.utils.messages import MessageEnum
from matlantis_features.features.common.opt import FireASEOptFeature
def estimator_fn() -> Estimator:
# change the model version.
estimator = Estimator(
model_version="v2.0.0",
calc_mode=EstimatorCalcMode.CRYSTAL_PLUS_D3,
)
# disable the specific type of warning.
estimator.set_message_status(
message=MessageEnum.ExperimentalElementWarning,
message_enable=False,
)
return estimator
atoms = molecule("CH3OH")
opt = FireASEOptFeature(estimator_fn=estimator_fn)
result = opt(atoms)
- Using estimator_fn (2)：
from Matlantis Guidebook > About matlantis-features > Customizing estimator used in matlantis-features
Basic ASE Modules
- File input and output
https://wiki.fysik.dtu.dk/ase/ase/io/io.html#module-ase.io - Atoms object
https://wiki.fysik.dtu.dk/ase/ase/atoms.html#the-atoms-object - Building things
https://wiki.fysik.dtu.dk/ase/ase/build/build.html#building-things - molecule, bulk, surface
- stack
- translate, rotate
- add_adsorbate
- Constraints
https://wiki.fysik.dtu.dk/ase/ase/constraints.html#constraints- FixAtoms
- ExpCellFilter, UnitCellFilter, StrainFilter
for more infomation about ASE, here
Frequently used Python packages
- Provided by Matlantis (Package launcher)
- pfp-api-client
- matlantis-features
- pfcc-extras
- matlantis-group-drive-client
- Computational Chemistry Related
- ase
- pymatgen
- Sella
- plumed
- Data analysis, numerical calculation, statistical processing
- pandas
- numpy
- scipy
- Graphing related
- matplotlib
- plotly
- kaleido
- seaborn
- Machine learning
- scikit-learn
- torch
- Parallel processing
- joblib
- Parameter optimization
- optuna
Click here for installation instructions
About PFVM
- PFVM is a high-performance, multi-platform deep accelerator library developed by Preferred Networks.
- This technique has increased the number of computable atoms. (Click here to see the number of atoms that can be calculated.)
from Matlantis Guidebook > About PFVM