Machine Learning with MPNICE Embedding

Tutorial Created with Software Release: 2026-3
Topics: Catalysis & Reactivity, Consumer Packaged Goods, Energy Capture & Storage, Metals, Alloys & Ceramics, Organic Electronics, Pharmaceutical Formulations, Polymeric Materials, Thin Film Processing
Methodology: Machine Learning
Products Used: MS FF Applications, MS Informatics, MS Maestro

Tutorial files

25 MB
This tutorial is written for use with a 3-button mouse with a scroll wheel.
Words found in the Glossary of Terms are shown like this: Workspacethe 3D display area in the center of the main window, where molecular structures are displayed

 

Tip: You can hover over a glossary term to display its definition. You can click on an image to expand it in the page.
Abstract:

In this tutorial, we will learn how to use the MPNICE Embedding Machine Learning panel to build, analyze, and apply machine learning models that leverage learned atomic or molecular representations from pretrained MPNICE force field models. We will utilize automatic training capabilities to develop regression models for the prediction of electronic bandgap energies of crystalline metal oxide structures.

Tutorial Content

  1. Introduction to Machine Learning with MPNICE Embedding

  1. Creating Projects and Importing Structures

  1. Building ML Models with MPNICE Embedding

  1. Analyzing ML Models with MPNICE Embedding

  2. Predicting Properties for Unseen Data

  1. Conclusion and References

  1. Glossary of Terms

1. Introduction to Machine Learning with MPNICE Embedding

The development of Quantitative Structure-Property Relationships (QSPR), also known as Quantitative Structure-Activity Relationships (QSAR), is a powerful technique widely used in materials design and drug discovery. The aim is to find mathematical models, often machine learning (ML) models, that relate a compound’s structure to its properties. Features translate the physical and chemical characteristics of structures into quantitative and machine-readable variables. Among other factors, the accuracy of these models critically depends on the quality of the translation from structure to feature.

Traditional approaches, e.g. topological indices, physicochemical properties, functional-group counts, and structural fingerprints, have long served as the basis for QSAR modeling. While these are effective for many tasks, these hand-crafted representations are limited by the chemical knowledge that was encoded when they were designed. They encode properties of the structure that we believe could be relevant to the targeted structure-property relationship and are typically derived from 2D connectivity or a single 3D conformer, they encode no information about long-range electrostatic interactions, and most are defined only for finite, non-periodic molecules, leaving periodic systems such as crystals, surfaces, and bulk materials out of reach. Unlike organic molecules, which benefit from decades of mature cheminformatics descriptors (e.g., fingerprints, MACCS keys, RDKit 2D descriptors), periodic inorganic structures lack a comparably rich and standardized descriptor toolkit. The most widely used approach, Matminer's Magpie descriptors, computes statistical summaries of elemental properties from the chemical composition alone, e.g., electronegativity, atomic radius, valence electron counts. While effective for coarse composition-property trends, such descriptors are entirely blind to crystal structure: two polymorphs with identical composition receive identical feature vectors, even though their properties may differ dramatically. Structure-aware alternatives exist (e.g., SOAP, smooth overlap of atomic positions), but each captures only a narrow aspect of the structure-property relationship and typically requires system-specific tuning.

An alternative approach is to use learned molecular representations extracted from neural networks trained on large-scale quantum mechanical data. Schrödinger's Machine Learning Force Field (MLFF) models, particularly the MPNICE (Message Passing Network with Iterative Charge Equilibration) model family, are trained to reproduce DFT-level energies, forces, and dipole moments across diverse chemical systems including non-periodic and periodic systems. During training, the intermediate layers of the MPNICE neural network learn to naturally encode 3D geometry, local electronic environment, charge distribution, and periodicity in rich, continuous representations of atoms and molecules. These are precisely the features that compositional descriptors miss and that are hardest to hand-engineer. These intermediate representations, referred to as MPNICE embeddings, can be extracted and repurposed as general-purpose, structure-aware molecular descriptors for property prediction tasks. We borrow the force field's understanding of chemistry and redirect it toward a property of interest, meaning that these embeddings are only as good as the chemistry the force field was trained on. If our molecules are far outside the MLFFs training domain (e.g. exotic elements, unusual bonding), the embeddings may not transfer well. Learn more about the coverage and limitations of the MPNICE family in the documentation.

The MPNICE Embedding Machine Learning panel is part of Schrödinger's MS Informatics tools and provides an automated workflow for using these physics-informed embeddings to train and apply machine learning models in a QSPR setting, similarly to DeepAutoQSAR.

This tutorial provides step-by-step instructions for building, analyzing, and applying MPNICE embeddings as descriptors for machine learning. The overall workflow is summarized below:

The data set used here is a publicly available data set from the Nomad2018 Predicting Transparent Conductors Kaggle competition on predicting key properties of potential transparent conductors for optoelectronic applications. It contains 3,000 crystal structures of binary and ternary (AlxGayInz)2O3 compounds with x+y+z=1, along with the electronic bandgap energy and formation energy as calculated with density-functional theory (DFT), and some additional structural and compositional information of the crystals. Learn more about the competition and data in the official publication: Sutton, C. et al. Crowd-sourcing materials-science challenges with the NOMAD 2018 Kaggle competition. npj Comput. Mater. 5, 111 (2019).

2. Creating Projects and Importing Structures

At the start of the session, change the file path to your chosen Working Directorythe location where files are saved in MS Maestro to make file navigation easier. Each session in MS Maestro begins with a default Scratch Projecta temporary project in which work is not saved, closing a scratch project removes all current work and begins a new scratch project, which is not saved. A MS Maestro project stores all your data and has a .prj extension. A project may contain numerous entries corresponding to imported structures, as well as the output of modeling-related tasks. Once a project is saved, the project is automatically saved each time a change is made.

Structures can be built in MS Maestro or can be imported using File > Import Structures (or drag-and-dropped), and are added to the Entry Lista simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion and Project Tabledisplays the contents of a project and is also an interface for performing operations on selected entries, viewing properties, and organizing structures and data. The Entry Lista simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion is located to the left of the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed. The Project Tabledisplays the contents of a project and is also an interface for performing operations on selected entries, viewing properties, and organizing structures and data can be accessed by Ctrl+T (Cmd+T) or Window > Project Table if you would like to see an expanded view of your project data.

  1. Double-click the Materials Science icon

Figure 2-1. Change Working Directory option.

  1. Go to File > Change Working Directory
  2. Find your directory, and click Choose
  3. Pre-generated files are included for running jobs or examining output. Download the zip file here: schrodinger.com/sites/default/files/s3/release/current/Tutorials/zip/ml_mpnice_embedding.zip
  4. After downloading the zip file, unzip the contents in your Working Directorythe location where files are saved for ease of access throughout the tutorial

Figure 2-2. Save Project panel.

  1. Go to File > Save Project As
  2. Change the File name to ml_mpnice_embedding_tutorial, click Save
    • The project is now named ml_mpnice_embedding_tutorial.prj

3. Building ML Models with MPNICE Embedding

In this section, we will import and visualize the training data. Subsequently, we will develop ML models with the MPNICE Embedding Machine Learning panel for the prediction of electronic bandgap energies.

Figure 3-1. The imported data in the Entry List and Workspace.

  1. Go to File > Import Structures
  2. Navigate to where you downloaded the provided tutorial files (presumably in your Working Directorythe location where files are saved), and choose the file data_kaggle2018_bandgap.maegz
  3. Click Open
    • A new entry is added to your Entry Lista simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion named data_kaggle2018_bandgap (3000)
  4. Click on the plus sign in the bottom right corner ()
  5. For visualization purposes, uncheck the Bonds toggle to undisplay bonds

The color coding of atoms in the Workspacethe 3D display area in the center of the main window, where molecular structures are displayed: Al atoms in gray, Ga atoms in orange, In atoms in blue, and O atoms in red.

  1. Ensure the sub group entry for training_data (2400) is selected(1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entry List (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries in the Entry Lista simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion

The full data set of 3,000 points is divided into a training set with 2,400 and a test set with 600 examples.

Figure 3-2. The MPNICE Embeddings Machine Learning panel with the loaded training data.

  1. Go to Tasks > Materials > Informatics > MPNICE Embedding Machine Learning
  2. Ensure that Use structures from is set to Project Table (2400 selected entries)
  3. Click Load Structure
    • The training data is loaded into the panel

The Training Data tab contains a table with the loaded data as well as a plot to visualize properties of the data set. For every entry the table shows the title (ID), whether or not the structure is periodic (PBC = Y/N for periodic and non-period, respectively), as well as all available structural properties from the Project Tabledisplays the contents of a project and is also an interface for performing operations on selected entries, viewing properties, and organizing structures and data. In our case, this includes the number of atoms, information on the crystal structure, the electronic bandgap energy (target property), and more.

Figure 3-3. Visualizing the distribution of the target property.

  1. On the right side, set the left of the Properties to r_user_bandgap_energy_ev, the right to (none)

We can see a histogram of the imported data. We can also select two properties to show a parity plot and add correlation metrics such as R2, root-mean-square error (RMSE), and Pearson's r.

The Build tab contains all options to develop ML models. The panel runs an automated search for the best-performing models. In this hyperparameter optimization loop powered by Bayesian optimization, multiple models are trained and tested based on the chosen settings of featurizers, embedding types, and ML model types. Additionally, for individual combinations of these settings, the defined hyperparameters of the ML model type are optimized (e.g. the number of layers and neurons per layer in a neural network). The result of the model-building process is an ensemble model composed of the three top-performing models.

Figure 3-4. Settings for the model creation.

  1. Switch to the Build tab
  2. For Featurizers, select Per Molecule Featurizer and Per Atom Featurizer
    • Per Atom Featurizer uses the fine-grained MPNICE embedding for every individual atom in its local environment and results in one feature vector per atom. This is recommended for the prediction of properties sensitive to the local environment.
    • Per Molecule Featurizer aggregates all atomic feature vectors into one feature vector for the whole structure. This reduces the explicit information about the local environment to a more coarse-grained implicit description.
  3. For Embedding type, choose Inorganic
    • This refers to the MLFF model for the embedding. Currently available are MPNICE Organic for pure organic systems, MPNICE Inorganic for pure inorganic systems, and MPNICE Hybrid for mixed and pure inorganic systems. For non-periodic structures, chiral information can be added with the Use chiral embedding option.
    • Our crystalline metal oxides are inorganic structures, so we can either use the Inorganic or Hybrid embedding types.
  4. For Machine learning models, choose All
    • Please note that Elastic Net, Random Forest, XGBoost, SVM, and DNN are only available with the Per Molecule Featurizer, while Graph-based Models are only available with the Per Atom Featurizer.
  5. For Target property, choose r_user_bandgap_energy_ev
    • It is possible to select multiple target properties. In such a case, multiple independent models will be trained for each target property individually.
  6. For Hyperparameter tuning steps, choose 10
    • This setting defines the number of distinct model configurations that are trained in the automatic model optimization process. Instead of training a defined number of models, we can set a time limit, after which the current model training is finished, but no new model is trained. The optimizer has early stopping built in. If 50 models have been trained without improving the ensemble score, the optimization is stopped.
  7. Leave the Training set size at 90%
    • This defines the training/test set split. In our case 2,160 examples will be used for training and 240 for testing.

In the Advanced Options, we can set the option to Downsample our data in case the training data set is very large (>10,000). Additionally, we can change the number of Cross validation splits from the default of 5 and set a Random seed for the splitting.

Figure 3-5. Naming and running the training job.

  1. Change the Job name to mpnice_embedding_ml_bandgap_train
  2. Adjust the Job Settings () as needed
    • This job can run on CPUs or GPUs. On a single GPU this job takes approximately 6 hours to complete.
  3. If you would like to run the job yourself, click Run. Otherwise, you can proceed and import provided results from the zip file in the next section.

When the job is complete, a banner will appear indicating “Your job completed successfully but did not produce any results to incorporate”.

4. Analyzing ML Models with MPNICE Embedding

In this section, we will analyze the performance of the model generated in the previous section with the MPNICE Embedding Machine Learning panel.

Figure 4-1. Importing the trained model into the MPNICE Embedding ML panel.

  1. In case you closed the MPNICE Embedding Machine Learning panel, reopen it via Tasks > Materials > Informatics > MPNICE Embedding Machine Learning
  2. Switch to the Performance tab
  3. Click Import Model

If you run the job yourself, the model should automatically appear in the ML Model Manager panel. If this does not happen or if you want to proceed with the provided results, please follow these steps to manually add a model:

  1. Click Add Model
  2. If you want to load the provided model, browse to section_04 > mpnice_embedding_ml_bandgap_train > mpnice_embedding_ml_bandgap_train.model and click Open. If you want to load your own results, browse to mpnice_embedding_ml_bandgap_train > mpnice_embedding_ml_bandgap_train.model and click Open.
  3. Select the entry mpnice_embedding_ml_bandgap_train.model from the table and click OK

Loading the model may take a minute. If you get a warning saying that the uploaded ML model was trained by an older version, click OK and proceed. You could retrain the ML model with the ML Model Manager panel.

Import provided model or use job run by user

The Performance tab shows a parity plot of the actual vs predicted values, along with performance metrics such as the coefficient of determination (R2) and the root mean square error (RMSE). The plot shows both the training and test data. Additionally, we can see the distributions of actual and predicted values for the train and test data sets.

Note that the result of the model-building process is an ensemble model composed of the three top-performing models. The final prediction is the ensemble average, and the variation among the ensemble members provides an estimate of uncertainty.

Figure 4-2. The parity plot and performance metrics for the imported model.

Note that if you performed the job yourself, you should expect slight variances in the results arising from the randomness of the train/test split and ML model hyperparameters.

In this case, the model generalized and predicted very well on the test set with an R2 of ~0.95 (an ideal model would show a value of 1). The RMSE is low compared to absolute predicted/actual values.

If the model's performance is poor, consider increasing the amount of training data and the number of hyperparameter tuning steps.

5. Predicting Properties for Unseen Data

In this section, we will use the generated model to make predictions for electronic bandgap energies of unseen structures with the MPNICE Embedding Machine Learning panel.

Figure 5-1. Selecting the test data in the Entry List.

  1. Ensure the sub group entry for test_data (600) is selected(1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entry List (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries in the Entry Lista simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion

Figure 5-2. Loading the test data.

  1. Switch to the Predict tab
  2. Ensure that Use structures from is set to Project Table (600 selected entries)
  3. Click Load Structure

Ensure that the model is still loaded (next to Import Model, it should read mpnice_embedding_ml_bandgap_train.model). If this is not the case, follow the next steps:

  1. Click Import Model
  2. Select the entry mpnice_embedding_ml_bandgap.model
  3. Click OK
    • The model is loaded

Figure 5-3. Naming and running the prediction job.

  1. Change the Job name to mpnice_embedding_ml_bandgap_predict
  2. Adjust the Job Settings () as needed
    • This job can run on CPUs or GPUs. On a single GPU this job takes approximately 25 minutes to complete.
  3. Click Run

Figure 5-4. A parity plot for the predicted vs true values on the test set.

When the job is complete, a popup window will appear asking to load the predictions into the Maestro project table.

  1. Confirm by clicking OK
    • A new entry group named mpnice_embedding_ml_bandgap_predict_output (600) is added to the Entry Lista simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion
    • The table in the Predict tab is populated with the predictions values and uncertainties
  2. On the right side, for Properties, select r_user_bandgap_energy_eV and r_user_bandgap_energy_eV_predict

The plot shows the true and predicted values for the bandgap energy. The predictions are in close agreement with true values, the R2 value is close to 1.

Figure 5-5. Plotting the prediction uncertainties for the test set.

  1. Switch the Properties to r_user_bandgap_energy_eV_predict and (none)

The plot shows a histogram of the uncertainties from the ensemble predictions, which are below 0.1 eV for most of the predictions.

6. Conclusion and References

In this tutorial, we learned how to use the MPNICE Embedding Machine Learning panel to build, analyze, and apply machine learning models that leverage learned atomic or molecular representations from pretrained MPNICE force field models, so called embeddings. We utilized automatic training capabilities to develop QSPR regression models for the prediction of electronic bandgap energies of crystalline metal oxide structures.

For further learning:

For introductory content, focused on navigating the Schrödinger Materials Science interface, an Introduction to Materials Science Maestro tutorial is available. Please visit the materials science content library for access to events, publications, webinars, white papers, and more than 100 tutorials. For scientific inquiries or technical troubleshooting, submit a ticket to our Technical Support Scientists at help@schrodinger.com.

For self-paced, asynchronous, online courses in Materials Science modeling, including access to Schrödinger software, please visit the Schrödinger Online Learning portal on our website.

For some related practice, proceed to explore other relevant tutorials:

7. Glossary of Terms

Entry List - a simplified view of the Project Table that allows you to perform basic operations such as selection and inclusion

Included - the entry is represented in the Workspace, the circle in the In column is blue

Project Table - displays the contents of a project and is also an interface for performing operations on selected entries, viewing properties, and organizing structures and data

Recent actions - This is a list of your recent actions, which you can use to reopen a panel, displayed below the Browse row. (Right-click to delete.)

Scratch Project - a temporary project in which work is not saved, closing a scratch project removes all current work and begins a new scratch project

Selected - (1) the atoms are chosen in the Workspace. These atoms are referred to as "the selection" or "the atom selection". Workspace operations are performed on the selected atoms. (2) The entry is chosen in the Entry List (and Project Table) and the row for the entry is highlighted. Project operations are performed on all selected entries

Working Directory - the location where files are saved

Workspace - the 3D display area in the center of the main window, where molecular structures are displayed