Usage

PiNNwall enables the integration of a machine learned charge response kernel (CRK) predicted by PiNN¹ with the Metalwalls MD simulation software². PiNNwall was first introduced in the following work³, and later upgraded through the introduction of higher-order tensorial features in PiNN⁴. A more in-depth example illustrating the application of PiNNwall to a hydroxylated electrode can be found in the tutorial part of the documentation.

Preparation

PiNNwall predicts the CRK for Metalwalls² using machine learning (ML)-models trained using PiNN¹. In order to run PiNNwall, one needs to have PiNN installed first.

Before prediction, one needs to have constructed the input files of Metalwalls, namely the data.inpt and runtime.inpt, which you will use to run the Metalwalls simulations. For the best performance of PiNNwall, base charges need for the electrode atoms need to be set in the data.inpt file. Depending on the electrode structure, these could directly be taken from the PiNNwall papers, predicted using PiNN, taken from force-field parameters or computed using a population analysis method.

Then, clone this repo to get the scripts and the ML-models that will be used in predicting the CRK.

After executing PiNNwall, it will generate a hessian_matrix.inpt to be used by Metalwalls which contains the machine learned CRK. This hessian_matrix.inpt file in Metalwalls traditionally contains the inverse of the hardness kernel which is analogous in concept to the CRK predicted here. Both can be used in the same way to obtain response charges on the electrode, for more information see the PiNNwall paper³. PiNNwall will also update the hardness parameters in the runtime.inpt to ensure that consistency between PiNN and Metalwalls necessary when using Metalwalls to run the MD simulations.

Note, to achieve performance consistent with the PiNNwall paper, a modified version of Metalwalls must be used. This will be made available upon request.

Synopsis

Figure 1. Flowchart of the PiNNwall input and output. The required arguments for PiNNwall are illustrated in the black rectangular boxes. The blue box contains the Metalwalls input files that need to be present in the working directory to execute PiNNwall. The red box contains the available method types for predicting the CRK.

python pinnwall.py [-i <WORKING_DIR>] [-p <MODEL_DIR>] [-m <methodename>] [-o <filename>]

Options:

-i <WORKING_DIR> (./) path to the input files of MW

-p <MODEL_DIR> (./trained_models) path to the trained pinn model

-m <methodename> (eem) List of model types used to compute the CRK. To pass multiple model types, i.e. -m eem local etainv acks2

-o <filename> (pinnwall.out) log of pinnwall, defaults to inputs_dir

Executing produces:

• pinnwall.out - text file containing the parameters used for this run
• hessian_matrix.inpt - charge response kernel file to be used by Metalwalls
• runtime_{method_name}.inpt - an updated version of the provided runtime.inpt file, which contains Gaussian width parameters that are consistent with those used when predicting the Hessian matrix

PiNet1 or PiNet2

PiNNwall can be used with either PiNet1 or PiNet2, this is determined by which trained models are used. The models found in the trained_models directory are trained with PiNet1 and are compatible with older versions of PiNN. The trained_models_pinet2 directory contains models trained with PiNet2 which can be used with the V2.0.0 version of PiNN.

Singularity

A very simple way to execute PiNNwall is through the use of the pre-built singularities available for PiNN. The models in the trained_models_pinet2 directory are compatible with the singularity image tagged master-{cpu/gpu}, which can be found here. The models in the trained_models directory are compatible with the singularity image tagged v1.0.0-{cpu/gpu}, which can be found here. The choice between the CPU and GPU version is up to the user.

To execute PiNNwall using a singularity image simply download the image from docker, and execute i.e.

singularity exec pinn.sif python pinnwall.py -i ./ -p ./trained_models  -m eem

Simulating with Metalwalls

To start a Metalwalls simulation, ensure that you have placed the hessian_maxtrix.inpt file generated by PiNNwall in the run directory, along with the modified runtime.inpt file. Also place the data.inpt file you used when executing PiNNwall in the same run directory. Then, execute Metalwalls as usual. Note that the hessian_maxtrix.inpt file only needs to be generated once, as the electrode structure stays fixed.

External field type

Metalwalls provides the ability to simulate both under an external electric field (E-field), and an external displacement field (D-field). This functionality is also implemented in PiNNwall for the EEM-type models. PiNNwall automatically detects whether the simulation is run under E-field or D-field and uses the EEM models to predict the appropriate hessian_matrix.inpt.

Note that all model types work for simulations under external E-field but only EEM-type models are capable of performing D-field simulations.

The pinnwall.out file will print the information about the external field that was detected in the runtime.out file, and used during the prediction of the hessian_matrix.out file.

Suitable systems

The ML-models provided with PiNNwall were trained using the QM7b dataset. This means that presently, PiNNwall is only able to predict sensible CRKs for electrodes containing C, H, N, O, S, and Cl. You are encouraged to train models for different systems using the polarizability models included in the PiNN package. For this, the PiNet2 network is recommended. More information on how to do this can be found in the PiNN documentation⁵. These models can then easily be integrated into PiNNwall by placing them into the trained_models folder.

We recommend that you use the EEM models for carbonaceous system as this seems to yield the most physical performance when comparing a carbon electrode to a perfect metal system. More in-depth information on the performance of all model types can be found in the PiNN papers ³⁴.

Footnotes

1. PiNN GitHub repository ↩ ↩²

2. Metalwalls repository ↩ ↩²

3. Dufils, T., Knijff, L., Shao, Y., & Zhang, C. (2023). PiNNwall: Heterogeneous electrode models from integrating machine learning and atomistic simulation. Journal of Chemical Theory and Computation, 19(15), 5199-5209. ↩ ↩² ↩³

4. Li, J., Knijff, L., Zhang, Z. Y., Andersson, L., & Zhang, C. (2025). PiNN: Equivariant Neural Network Suite for Modeling Electrochemical Systems. Journal of Chemical Theory and Computation, 21(3), 1382-1395. ↩ ↩²

5. PiNN documentation ↩