From 3ffdf2f2a6297fd7c59f1654190a89b87eb37da8 Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 10 Oct 2026 14:12:24 +0200 Subject: [PATCH 01/16] [doc] add new models to documentation --- docs/references.bib | 14 ++++++- docs/usage/quadrupole.md | 58 ++++++++++++++++++++++++++ pinn/models/AC_AD_dipole_quadrupole.py | 2 + pinn/models/AC_dipole_quadrupole.py | 2 + pinn/models/AC_quadrupole.py | 3 +- 5 files changed, 77 insertions(+), 2 deletions(-) create mode 100644 docs/usage/quadrupole.md diff --git a/docs/references.bib b/docs/references.bib index 86341860..44884b7f 100755 --- a/docs/references.bib +++ b/docs/references.bib @@ -205,4 +205,16 @@ @Article{2020_ShaoHellstroemEtAl volume = {60}, doi = {10.1021/acs.jcim.9b00994}, publisher = {American Chemical Society ({ACS})}, -} \ No newline at end of file +} + +@article{Muuga_2026, + author = {Muuga, Kadri and Knijff, Lisanne and Zhang, Chao}, + title = {Molecular electrostatic potentials from machine learning models for dipole and quadrupole predictions}, + journal = {AI Sci.}, + year = {2026}, + volume = {2}, + number = {2}, + pages = {025002}, + doi = {10.1088/3050-287X/ae531a}, + url = {https://doi.org/10.1088/3050-287X/ae531a} +} diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md new file mode 100644 index 00000000..9f0bff7a --- /dev/null +++ b/docs/usage/quadrupole.md @@ -0,0 +1,58 @@ +# Quadrupole Model + +The quadrupole model[@Muuga_2026] works similarly to the dipole model. +The ``model_params`` can be set, and are listed below along with their default values. + +| Parameter | Default | Description | +|----------------------|---------|----------------------------------------------------------------------------------| +| `max_quadrupole` | `False` | When set to a number, exclude quadrupoles above this value in loss function | +| `quad_scale` | `1` | Quadrupole unit during training | +| `use_quad_per_atom` | `False` | Use the per-atom quadrupole in place of total quadrupole in loss function | +| `log_quad_per_atom` | `True` | Log the per-atom quadrupole error, automatically enabled with `use_d_per_atoms=True` | +| `use_quad_weight` | `False` | Scale the energy loss according to the `'d_weight'` Tensor in the dataset | +| `use_l2` | `False` | Include L2 regularization in loss | +| `quad_loss_multiplier` | `1` | Weight of quadrupole loss | +| `l2_loss_multiplier` | `1` | Weight of l2 | + +## Variants +There are different variants of quadrupole and quadrupole-quadrupole models available. + +- atomic charge (AC) model (`AC_quadrupole_model`) +- atomic charge dipole-quadrupole (AC-DQ) model (`AC_dipole-quadrupole_model`) +- AC+AD dipole-quadrupole model (`AC_AD_dipole_quadrupole_model`) + +## Usage + +Apart from the models containing the atomic dipole (AD), all models are compatible with both PiNet and PiNet2. + +These models can be selected by changing `name` of the model in `model_params` (See overview for further instructions.). + +## Parameters +| Parameter | Default | Description | +|----------------------|---------|---------------------------------------------------------------------------------------------------------------| +| `max_quadrupole` | `False` | When set to a number, exclude quadrupoles above this value in loss function | +| `quad_scale` | `1` | Quadrupole unit during training | +| `quad_unit` | `1` | Output unit of quadrupole during prediction | +| `vector_quadrupole` | `True` | Toggle whether to use scalar or vector quadrupole predictions, should be the same as quadrupole moment of the dataset | +| `charge_neutrality` | `True` | Enable charge neutrality | +| `neutral_unit` |`'system'`| If charge neutrality is applied, set the charge neutral unit. Choose `'system'` for system neutrality, or `'water_molecule'` for neutrality per water molecule | | +| `regularization` | `True` Enable regularization of the interaction prediction, only available for models containing the 'R' term | +| `use_quad_per_atom` | `False` | Use the per-atom quadrupole in place of total quadrupole in loss function | +| `log_quad_per_atom` | `True` | Log the per-atom quadrupole error, automatically enabled with `use_quad_per_atoms=True` | +| `use_quad_weight` | `False` | Scale the energy loss according to the `'d_weight'` Tensor in the dataset | +| `use_l2` | `False` | Include L2 regularization in loss | +| `quad_loss_multiplier` | `1` | Weight of quadrupole loss | +| `l2_loss_multiplier` | `1` | Weight of l2 | + +## Model specifications + +### pinn.models.AC_quadrupole_model +::: pinn.models.AC_quadrupole_model + +### pinn.models.AC_dipole_quadrupole.py +::: pinn.models.AC_dipole_quadrupole.py + +### pinn.models.AC_AD_dipole_quadrupole.py +::: pinn.models.AC_AD_dipole_quadrupole.py + + diff --git a/pinn/models/AC_AD_dipole_quadrupole.py b/pinn/models/AC_AD_dipole_quadrupole.py index b214050a..a373e015 100644 --- a/pinn/models/AC_AD_dipole_quadrupole.py +++ b/pinn/models/AC_AD_dipole_quadrupole.py @@ -19,6 +19,8 @@ from machine learning models for dipole and quadrupole predictions. The definition of traceless quadrupole is Q'αβ = 3Qαβ - tr(Q)δαβ. +The training data are dipoles and traceless quadrupoles in the formats [$\mu_x$, $\mu_y$, $\mu_z$] and [$Q_{xx}$, $Q_{yy}$, $Q_{zz}$, $Q_{xy}$, $Q_{xz}$, $Q_{yz}$]. + The dipole weight is set to 100 to adjust for naturally larger quadrupole losses. This can be changed by changing d_loss_multiplier. diff --git a/pinn/models/AC_dipole_quadrupole.py b/pinn/models/AC_dipole_quadrupole.py index 1c7994d8..95c554fd 100644 --- a/pinn/models/AC_dipole_quadrupole.py +++ b/pinn/models/AC_dipole_quadrupole.py @@ -12,6 +12,8 @@ where q is the atomic charge, r are atomic coordinates and α, β ∈ {x, y, z}. The definition of traceless quadrupole is Q'αβ = 3Qαβ - tr(Q)δαβ. +The training data are dipoles and traceless quadrupoles in the formats [$\mu_x$, $\mu_y$, $\mu_z$] and [$Q_{xx}$, $Q_{yy}$, $Q_{zz}$, $Q_{xy}$, $Q_{xz}$, $Q_{yz}$]. + For model details see ref. Li, J., Knijff, L., Zhang, Z., Andersson, L., & Zhang, C. (2024) diff --git a/pinn/models/AC_quadrupole.py b/pinn/models/AC_quadrupole.py index fa02331d..c8f6ce37 100644 --- a/pinn/models/AC_quadrupole.py +++ b/pinn/models/AC_quadrupole.py @@ -14,6 +14,7 @@ where q is the atomic charge, r are atomic coordinates and α, β ∈ {x, y, z}. The definition of traceless quadrupole is Q'αβ = 3Qαβ - tr(Q)δαβ. +The training data are traceless quadrupoles in the format [Q_xx, Q_yy, Q_zz, Q_xy, Q_xz, Q_yz]. For model details see ref. Li, J., Knijff, L., Zhang, Z., Andersson, L., & Zhang, C. (2024) @@ -123,7 +124,7 @@ def AC_quadrupole_model(features, labels, mode, params): quadrupole *= model_params['quad_unit'] predictions = { - 'quadrupole': quadrupole, + 'quadrupole': quadrupole, #[Q_xx, Q_yy, Q_zz, Q_xy, Q_xz, Q_yz] 'charge': q_tot, 'charges': tf.expand_dims(p1, 0) } From 1c8f6d0266021561da6c221e101713a28c14d2c2 Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 10 Oct 2026 19:21:50 +0200 Subject: [PATCH 02/16] [doc] add new models to documentation --- docs/usage/quadrupole.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index 9f0bff7a..3f0ba2a1 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -1,6 +1,8 @@ # Quadrupole Model -The quadrupole model[@Muuga_2026] works similarly to the dipole model. +The quadrupole model[@Muuga_2026] works similarly to the dipole model. The traceless quadrupole moments of the format [$Q_{xx}$, $Q_{yy}$, $Q_{zz}$, $Q_{xy}$, $Q_{xz}$, $Q_{yz}$] are predicted using atomic charges as latent variables. + + The ``model_params`` can be set, and are listed below along with their default values. | Parameter | Default | Description | @@ -21,12 +23,45 @@ There are different variants of quadrupole and quadrupole-quadrupole models avai - atomic charge dipole-quadrupole (AC-DQ) model (`AC_dipole-quadrupole_model`) - AC+AD dipole-quadrupole model (`AC_AD_dipole_quadrupole_model`) +## Dipole-quadrupole moments + +The dipole-quadrupole model fits the dipole and quadrupole of the inputs to the atomic charges +and predicts dipoles and quadrupoles. The AC+AD dipole-quadrupole model uses a contribution from atomic dipoles for dipole prediction. + +The dipole moment is expressed as + +\\[ \boldsymbol{\mu}(\mathbf{r}) = \sum_i q_i \mathbf{r}\_i \\] + +The quadrupole tensor is defined as + +\\[ Q'\_{\alpha\beta}(\mathbf{r}) = \sum_i q_i \left( 3r\_{\alpha i}r\_{\beta i} - \delta\_{\alpha\beta}|\mathbf{r}\_i|^2 \right) \\] + +where: + +- \\(q_i\\) is the atomic charge of atom \\(i\\). +- \\(\mathbf{r}\_i\\) is the position vector of atom \\(i\\). +- \\(r\_{\alpha i}\\) and \\(r\_{\beta i}\\) are the Cartesian components of \\(\mathbf{r}\_i\\). +- \\(\alpha,\beta \in \\{x,y,z\\}\\). +- \\(\delta\_{\alpha\beta}\\) is the Kronecker delta. + +The traceless quadrupole tensor is defined in terms of the quadrupole tensor \\(Q\_{\alpha\beta}\\) as + +\\[ \boxed{ Q'\_{\alpha\beta} = 3Q\_{\alpha\beta} - \operatorname{tr}(Q)\delta\_{\alpha\beta} } \\] + +where \\(\operatorname{tr}(Q)\\) denotes the trace of the quadrupole tensor: + +\\[ \operatorname{tr}(Q) = \sum\_{\gamma \in \\{x,y,z\\}} Q\_{\gamma\gamma} \\] + ## Usage Apart from the models containing the atomic dipole (AD), all models are compatible with both PiNet and PiNet2. These models can be selected by changing `name` of the model in `model_params` (See overview for further instructions.). +The models are trained on traceless quadrupoles of the format [] +The models trained on the QM9 dataset can be found in the [PiNet2-DQ repository](https://github.com/Teoroo-CMC/PiNet2-DQ) + + ## Parameters | Parameter | Default | Description | |----------------------|---------|---------------------------------------------------------------------------------------------------------------| From 1ec81046e49dce4d69ff1bba543b761448f06007 Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 10 Oct 2026 19:30:14 +0200 Subject: [PATCH 03/16] [doc] add new models to documentation --- docs/usage/quadrupole.md | 43 +++++++++++++++++++++++++++------------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index 3f0ba2a1..f14c6a6e 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -1,6 +1,6 @@ # Quadrupole Model -The quadrupole model[@Muuga_2026] works similarly to the dipole model. The traceless quadrupole moments of the format [$Q_{xx}$, $Q_{yy}$, $Q_{zz}$, $Q_{xy}$, $Q_{xz}$, $Q_{yz}$] are predicted using atomic charges as latent variables. +The quadrupole model[@Muuga_2026] works similarly to the dipole model. The traceless quadrupole moments of the format [ $Q_{xx}$, $Q_{yy}$, $Q_{zz}$, $Q_{xy}$, $Q_{xz}$, $Q_{yz}$ ] are predicted using atomic charges as latent variables. The ``model_params`` can be set, and are listed below along with their default values. @@ -23,34 +23,49 @@ There are different variants of quadrupole and quadrupole-quadrupole models avai - atomic charge dipole-quadrupole (AC-DQ) model (`AC_dipole-quadrupole_model`) - AC+AD dipole-quadrupole model (`AC_AD_dipole_quadrupole_model`) -## Dipole-quadrupole moments +## Dipole-quadrupole models The dipole-quadrupole model fits the dipole and quadrupole of the inputs to the atomic charges and predicts dipoles and quadrupoles. The AC+AD dipole-quadrupole model uses a contribution from atomic dipoles for dipole prediction. The dipole moment is expressed as -\\[ \boldsymbol{\mu}(\mathbf{r}) = \sum_i q_i \mathbf{r}\_i \\] +$$ +\boldsymbol{\mu}(\mathbf{r}) = \sum_i q_i \mathbf{r}_i +$$ The quadrupole tensor is defined as -\\[ Q'\_{\alpha\beta}(\mathbf{r}) = \sum_i q_i \left( 3r\_{\alpha i}r\_{\beta i} - \delta\_{\alpha\beta}|\mathbf{r}\_i|^2 \right) \\] +$$ +Q'_{\alpha\beta}(\mathbf{r}) = +\sum_i q_i \left( +3r_{\alpha i}r_{\beta i} +- \delta_{\alpha\beta}|\mathbf{r}_i|^2 +\right) +$$ where: -- \\(q_i\\) is the atomic charge of atom \\(i\\). -- \\(\mathbf{r}\_i\\) is the position vector of atom \\(i\\). -- \\(r\_{\alpha i}\\) and \\(r\_{\beta i}\\) are the Cartesian components of \\(\mathbf{r}\_i\\). -- \\(\alpha,\beta \in \\{x,y,z\\}\\). -- \\(\delta\_{\alpha\beta}\\) is the Kronecker delta. +- \(q_i\) is the atomic charge of atom \(i\). +- \(\mathbf{r}_i\) is the position vector of atom \(i\). +- \(r_{\alpha i}\) and \(r_{\beta i}\) are the Cartesian components of \(\mathbf{r}_i\). +- \(\alpha,\beta \in \{x,y,z\}\). +- \(\delta_{\alpha\beta}\) is the Kronecker delta. -The traceless quadrupole tensor is defined in terms of the quadrupole tensor \\(Q\_{\alpha\beta}\\) as +The traceless quadrupole tensor is defined in terms of the quadrupole tensor \(Q_{\alpha\beta}\) as -\\[ \boxed{ Q'\_{\alpha\beta} = 3Q\_{\alpha\beta} - \operatorname{tr}(Q)\delta\_{\alpha\beta} } \\] +$$ +Q'_{\alpha\beta} += 3Q_{\alpha\beta} +- \operatorname{tr}(Q)\delta_{\alpha\beta} +$$ -where \\(\operatorname{tr}(Q)\\) denotes the trace of the quadrupole tensor: +where \(\operatorname{tr}(Q)\) denotes the trace of the quadrupole tensor: -\\[ \operatorname{tr}(Q) = \sum\_{\gamma \in \\{x,y,z\\}} Q\_{\gamma\gamma} \\] +$$ +\operatorname{tr}(Q) += \sum_{\gamma \in \{x,y,z\}} Q_{\gamma\gamma} +$$ ## Usage @@ -71,7 +86,7 @@ The models trained on the QM9 dataset can be found in the [PiNet2-DQ repository] | `vector_quadrupole` | `True` | Toggle whether to use scalar or vector quadrupole predictions, should be the same as quadrupole moment of the dataset | | `charge_neutrality` | `True` | Enable charge neutrality | | `neutral_unit` |`'system'`| If charge neutrality is applied, set the charge neutral unit. Choose `'system'` for system neutrality, or `'water_molecule'` for neutrality per water molecule | | -| `regularization` | `True` Enable regularization of the interaction prediction, only available for models containing the 'R' term | +| `regularization` | `True` | Enable regularization of the interaction prediction, only available for models containing the 'R' term | | `use_quad_per_atom` | `False` | Use the per-atom quadrupole in place of total quadrupole in loss function | | `log_quad_per_atom` | `True` | Log the per-atom quadrupole error, automatically enabled with `use_quad_per_atoms=True` | | `use_quad_weight` | `False` | Scale the energy loss according to the `'d_weight'` Tensor in the dataset | From ee2c0b8ee0fa7c541789891ca8217b8e9443dfb4 Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 10 Oct 2026 19:33:08 +0200 Subject: [PATCH 04/16] [doc] add new models to documentation --- docs/usage/quadrupole.md | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index f14c6a6e..766ce5c1 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -37,36 +37,41 @@ $$ The quadrupole tensor is defined as $$ -Q'_{\alpha\beta}(\mathbf{r}) = +Q'{\alpha\beta}(\mathbf{r}) = \sum_i q_i \left( -3r_{\alpha i}r_{\beta i} -- \delta_{\alpha\beta}|\mathbf{r}_i|^2 +3r{\alpha i}r_{\beta i} + +\delta_{\alpha\beta}|\mathbf{r}_i|^2 \right) $$ where: -- \(q_i\) is the atomic charge of atom \(i\). -- \(\mathbf{r}_i\) is the position vector of atom \(i\). -- \(r_{\alpha i}\) and \(r_{\beta i}\) are the Cartesian components of \(\mathbf{r}_i\). -- \(\alpha,\beta \in \{x,y,z\}\). -- \(\delta_{\alpha\beta}\) is the Kronecker delta. +$q_i$ is the atomic charge of atom $i$. + +$\mathbf{r}_i$ is the position vector of atom $i$. + +$r_{\alpha i}$ and $r_{\beta i}$ are the Cartesian components of $\mathbf{r}_i$. + +$\alpha,\beta \in {x,y,z}$. -The traceless quadrupole tensor is defined in terms of the quadrupole tensor \(Q_{\alpha\beta}\) as +$\delta_{\alpha\beta}$ is the Kronecker delta. + +The traceless quadrupole tensor is defined in terms of the quadrupole tensor $Q_{\alpha\beta}$ as $$ -Q'_{\alpha\beta} -= 3Q_{\alpha\beta} -- \operatorname{tr}(Q)\delta_{\alpha\beta} +Q'{\alpha\beta} += 3Q{\alpha\beta} + +\mathrm{tr}(Q)\delta_{\alpha\beta} $$ -where \(\operatorname{tr}(Q)\) denotes the trace of the quadrupole tensor: +where $\mathrm{tr}(Q)$ denotes the trace of the quadrupole tensor: $$ -\operatorname{tr}(Q) -= \sum_{\gamma \in \{x,y,z\}} Q_{\gamma\gamma} +\mathrm{tr}(Q) += \sum_{\gamma \in {x,y,z}} Q_{\gamma\gamma} $$ - ## Usage Apart from the models containing the atomic dipole (AD), all models are compatible with both PiNet and PiNet2. From 07fbe1df99a615166ab0d66b60ee83ab74c7aaab Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 10 Oct 2026 19:36:28 +0200 Subject: [PATCH 05/16] [doc] add new models to documentation --- docs/usage/quadrupole.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index 766ce5c1..1c96a2b4 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -37,12 +37,14 @@ $$ The quadrupole tensor is defined as $$ + Q'{\alpha\beta}(\mathbf{r}) = \sum_i q_i \left( 3r{\alpha i}r_{\beta i} \delta_{\alpha\beta}|\mathbf{r}_i|^2 \right) + $$ where: @@ -60,17 +62,21 @@ $\delta_{\alpha\beta}$ is the Kronecker delta. The traceless quadrupole tensor is defined in terms of the quadrupole tensor $Q_{\alpha\beta}$ as $$ + Q'{\alpha\beta} = 3Q{\alpha\beta} \mathrm{tr}(Q)\delta_{\alpha\beta} + $$ where $\mathrm{tr}(Q)$ denotes the trace of the quadrupole tensor: $$ + \mathrm{tr}(Q) = \sum_{\gamma \in {x,y,z}} Q_{\gamma\gamma} + $$ ## Usage From ea2b1b50547d29556ffeeb8625a9370a7a6f14de Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 20:54:34 +0200 Subject: [PATCH 06/16] [docs] updating documentation --- docs/usage/quadrupole.md | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index 1c96a2b4..8e66d703 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -37,14 +37,12 @@ $$ The quadrupole tensor is defined as $$ - -Q'{\alpha\beta}(\mathbf{r}) = +Q_{\alpha\beta}(\mathbf{r}) = \sum_i q_i \left( -3r{\alpha i}r_{\beta i} +3 r_{\alpha i} r_{\beta i} -\delta_{\alpha\beta}|\mathbf{r}_i|^2 +\delta_{\alpha\beta} |\mathbf{r}_i|^2 \right) - $$ where: @@ -61,22 +59,14 @@ $\delta_{\alpha\beta}$ is the Kronecker delta. The traceless quadrupole tensor is defined in terms of the quadrupole tensor $Q_{\alpha\beta}$ as -$$ - -Q'{\alpha\beta} -= 3Q{\alpha\beta} - -\mathrm{tr}(Q)\delta_{\alpha\beta} - -$$ - -where $\mathrm{tr}(Q)$ denotes the trace of the quadrupole tensor: +Q_{\alpha\beta} +\frac{1}{3}\operatorname{tr}(Q)\delta_{\alpha\beta} $$ -\mathrm{tr}(Q) -= \sum_{\gamma \in {x,y,z}} Q_{\gamma\gamma} +where $\operatorname{tr}(Q)$ denotes the trace of the quadrupole tensor: +\sum_{\gamma \in {x,y,z}} Q_{\gamma\gamma} $$ ## Usage From 8809d5518dcd4fa496b690062de2ea11c6508599 Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 20:59:08 +0200 Subject: [PATCH 07/16] [docs] updating documentation --- docs/usage/quadrupole.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index 8e66d703..a93d1e56 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -31,7 +31,7 @@ and predicts dipoles and quadrupoles. The AC+AD dipole-quadrupole model uses a c The dipole moment is expressed as $$ -\boldsymbol{\mu}(\mathbf{r}) = \sum_i q_i \mathbf{r}_i +**{\mu}**(**r**) = \sum_i **q**_i **r**_i $$ The quadrupole tensor is defined as From a60704b1ce99b7e9ee04c0e82098e9990b984af8 Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:02:40 +0200 Subject: [PATCH 08/16] [docs] updating documentation --- docs/usage/quadrupole.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index a93d1e56..1e831af9 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -31,7 +31,7 @@ and predicts dipoles and quadrupoles. The AC+AD dipole-quadrupole model uses a c The dipole moment is expressed as $$ -**{\mu}**(**r**) = \sum_i **q**_i **r**_i +\boldsymbol{\mu}(\mathbf{r}) = \sum_i q_i \mathbf{r}_i $$ The quadrupole tensor is defined as @@ -39,10 +39,7 @@ The quadrupole tensor is defined as $$ Q_{\alpha\beta}(\mathbf{r}) = \sum_i q_i \left( -3 r_{\alpha i} r_{\beta i} - -\delta_{\alpha\beta} |\mathbf{r}_i|^2 -\right) +3 r_{\alpha i} r_{\beta i} - \delta_{\alpha\beta} |\mathbf{r}_i|^2 \right) $$ where: @@ -59,15 +56,16 @@ $\delta_{\alpha\beta}$ is the Kronecker delta. The traceless quadrupole tensor is defined in terms of the quadrupole tensor $Q_{\alpha\beta}$ as -Q_{\alpha\beta} - -\frac{1}{3}\operatorname{tr}(Q)\delta_{\alpha\beta} +$$ +Q_{\alpha\beta} = \frac{1}{3}\operatorname{tr}(Q)\delta_{\alpha\beta} $$ where $\operatorname{tr}(Q)$ denotes the trace of the quadrupole tensor: +$$ \sum_{\gamma \in {x,y,z}} Q_{\gamma\gamma} $$ + ## Usage Apart from the models containing the atomic dipole (AD), all models are compatible with both PiNet and PiNet2. From 4fb47aca1c604b0aeb2a2e6e749c5288c838340a Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:10:31 +0200 Subject: [PATCH 09/16] [docs] updating documentation --- docs/usage/quadrupole.md | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index 1e831af9..7c247eda 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -31,33 +31,25 @@ and predicts dipoles and quadrupoles. The AC+AD dipole-quadrupole model uses a c The dipole moment is expressed as $$ -\boldsymbol{\mu}(\mathbf{r}) = \sum_i q_i \mathbf{r}_i +\boldsymbol{\mu}(\boldsymbol{r}) = \sum_i q_i \boldsymbol{r}_i $$ The quadrupole tensor is defined as $$ -Q_{\alpha\beta}(\mathbf{r}) = +Q'_{\alpha\beta}(\boldsymbol{r}) = \sum_i q_i \left( -3 r_{\alpha i} r_{\beta i} - \delta_{\alpha\beta} |\mathbf{r}_i|^2 \right) +3 r_{\alpha i} r_{\beta i} - \delta_{\alpha\beta} |\boldsymbol{r}_i|^2 \right) $$ where: -$q_i$ is the atomic charge of atom $i$. +$q_i$ is the atomic charge of atom $i$, $\boldsymbol{r}_i$ is the position vector of atom $i$ and $\alpha,\beta run over /{x,y,z/}$. -$\mathbf{r}_i$ is the position vector of atom $i$. - -$r_{\alpha i}$ and $r_{\beta i}$ are the Cartesian components of $\mathbf{r}_i$. - -$\alpha,\beta \in {x,y,z}$. - -$\delta_{\alpha\beta}$ is the Kronecker delta. - -The traceless quadrupole tensor is defined in terms of the quadrupole tensor $Q_{\alpha\beta}$ as +There are different conventions of traceless quadrupoles in the literature. We define the traceless quadrupole tensor as $$ -Q_{\alpha\beta} = \frac{1}{3}\operatorname{tr}(Q)\delta_{\alpha\beta} +Q'_{\alpha\beta} = \frac{1}{3}\operatorname{tr}(Q)\delta_{\alpha\beta} $$ where $\operatorname{tr}(Q)$ denotes the trace of the quadrupole tensor: @@ -68,11 +60,10 @@ $$ ## Usage -Apart from the models containing the atomic dipole (AD), all models are compatible with both PiNet and PiNet2. +The dipole-quadrupole models are compatible with PiNet2. These models can be selected by changing `name` of the model in `model_params` (See overview for further instructions.). -The models are trained on traceless quadrupoles of the format [] The models trained on the QM9 dataset can be found in the [PiNet2-DQ repository](https://github.com/Teoroo-CMC/PiNet2-DQ) From a73f5223ba7c02345fe6f92b12d090ba6b7291fb Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:13:45 +0200 Subject: [PATCH 10/16] [docs] updating documentation --- docs/usage/quadrupole.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index 7c247eda..bc7e2a02 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -44,15 +44,7 @@ $$ where: -$q_i$ is the atomic charge of atom $i$, $\boldsymbol{r}_i$ is the position vector of atom $i$ and $\alpha,\beta run over /{x,y,z/}$. - -There are different conventions of traceless quadrupoles in the literature. We define the traceless quadrupole tensor as - -$$ -Q'_{\alpha\beta} = \frac{1}{3}\operatorname{tr}(Q)\delta_{\alpha\beta} -$$ - -where $\operatorname{tr}(Q)$ denotes the trace of the quadrupole tensor: +$q_i$ is the atomic charge of atom $i$, $\boldsymbol{r}_i$ is the position vector of atom $i$ and $\alpha,\beta run over /{x,y,z/} $. $$ \sum_{\gamma \in {x,y,z}} Q_{\gamma\gamma} From 543cfc0f0196d82fcf584c0f8b63445f3afb4175 Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:15:35 +0200 Subject: [PATCH 11/16] [docs] updating documentation --- docs/usage/quadrupole.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index bc7e2a02..c570002b 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -34,7 +34,7 @@ $$ \boldsymbol{\mu}(\boldsymbol{r}) = \sum_i q_i \boldsymbol{r}_i $$ -The quadrupole tensor is defined as +The traceless quadrupole tensor is defined as $$ Q'_{\alpha\beta}(\boldsymbol{r}) = @@ -44,11 +44,7 @@ $$ where: -$q_i$ is the atomic charge of atom $i$, $\boldsymbol{r}_i$ is the position vector of atom $i$ and $\alpha,\beta run over /{x,y,z/} $. - -$$ -\sum_{\gamma \in {x,y,z}} Q_{\gamma\gamma} -$$ +$q_i$ is the atomic charge of atom $i$, $\boldsymbol{r}_i$ is the position vector of atom $i$ and $\alpha,\beta$ run over $ /{x,y,z/} $. One needs to be careful with different conventions for traceless quadrupoles in the literature. ## Usage From e760d5d717a777af0969fb6cafafa965229ca41c Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:17:43 +0200 Subject: [PATCH 12/16] [docs] updating documentation --- docs/usage/quadrupole.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index c570002b..57bd470e 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -42,9 +42,7 @@ Q'_{\alpha\beta}(\boldsymbol{r}) = 3 r_{\alpha i} r_{\beta i} - \delta_{\alpha\beta} |\boldsymbol{r}_i|^2 \right) $$ -where: - -$q_i$ is the atomic charge of atom $i$, $\boldsymbol{r}_i$ is the position vector of atom $i$ and $\alpha,\beta$ run over $ /{x,y,z/} $. One needs to be careful with different conventions for traceless quadrupoles in the literature. +where $q_i$ is the atomic charge and $\boldsymbol{r}_i$ is the position vector of atom $i$ and $\alpha,\beta$ run over $ \{x,y,z\} $. This is one of the three conventions of traceless quadrupoles found in the literature. ## Usage From 3194578a64ed10f6eb383aa633624304051f890a Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:21:46 +0200 Subject: [PATCH 13/16] [docs] updating documentation --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 35e5831d..02e3b1ec 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,6 +24,7 @@ nav: - Overview: usage/models.md - Potential: usage/potential.md - Dipole: usage/dipole.md + - Quadrupole: usage/quadrupole.md - Polarizability: usage/polarizability.md - Customize: usage/custom_model.md - CLI: From 2d1242eb22457dde807794be6c4998b6b1efe27b Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:39:10 +0200 Subject: [PATCH 14/16] [docs] updating documentation --- docs/usage/quadrupole.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index 57bd470e..b11b994c 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -61,7 +61,7 @@ The models trained on the QM9 dataset can be found in the [PiNet2-DQ repository] | `quad_unit` | `1` | Output unit of quadrupole during prediction | | `vector_quadrupole` | `True` | Toggle whether to use scalar or vector quadrupole predictions, should be the same as quadrupole moment of the dataset | | `charge_neutrality` | `True` | Enable charge neutrality | -| `neutral_unit` |`'system'`| If charge neutrality is applied, set the charge neutral unit. Choose `'system'` for system neutrality, or `'water_molecule'` for neutrality per water molecule | | +| `neutral_unit` |`'system'`| If charge neutrality is applied, set the charge neutral unit. Choose `'system'` for system neutrality, or `'water_molecule'` for neutrality per water molecule | | `regularization` | `True` | Enable regularization of the interaction prediction, only available for models containing the 'R' term | | `use_quad_per_atom` | `False` | Use the per-atom quadrupole in place of total quadrupole in loss function | | `log_quad_per_atom` | `True` | Log the per-atom quadrupole error, automatically enabled with `use_quad_per_atoms=True` | @@ -76,9 +76,9 @@ The models trained on the QM9 dataset can be found in the [PiNet2-DQ repository] ::: pinn.models.AC_quadrupole_model ### pinn.models.AC_dipole_quadrupole.py -::: pinn.models.AC_dipole_quadrupole.py +::: pinn.models.AC_dipole_quadrupole ### pinn.models.AC_AD_dipole_quadrupole.py -::: pinn.models.AC_AD_dipole_quadrupole.py +::: pinn.models.AC_AD_dipole_quadrupole From ac078acb407d0818bc92cc434dbdb321c5382cc1 Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 22:40:42 +0200 Subject: [PATCH 15/16] [docs] updating documentation --- docs/usage/quadrupole.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index b11b994c..9b9e9bf1 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -10,7 +10,7 @@ The ``model_params`` can be set, and are listed below along with their default v | `max_quadrupole` | `False` | When set to a number, exclude quadrupoles above this value in loss function | | `quad_scale` | `1` | Quadrupole unit during training | | `use_quad_per_atom` | `False` | Use the per-atom quadrupole in place of total quadrupole in loss function | -| `log_quad_per_atom` | `True` | Log the per-atom quadrupole error, automatically enabled with `use_d_per_atoms=True` | +| `log_quad_per_atom` | `True` | Log the per-atom quadrupole error, automatically enabled with `use_quad_per_atoms=True` | | `use_quad_weight` | `False` | Scale the energy loss according to the `'d_weight'` Tensor in the dataset | | `use_l2` | `False` | Include L2 regularization in loss | | `quad_loss_multiplier` | `1` | Weight of quadrupole loss | @@ -37,12 +37,10 @@ $$ The traceless quadrupole tensor is defined as $$ -Q'_{\alpha\beta}(\boldsymbol{r}) = -\sum_i q_i \left( -3 r_{\alpha i} r_{\beta i} - \delta_{\alpha\beta} |\boldsymbol{r}_i|^2 \right) +Q'_{\alpha\beta}(\boldsymbol{r}) = \sum_i q_i \left(3 r_{\alpha i} r_{\beta i} - \delta_{\alpha\beta} |\boldsymbol{r}_i|^2 \right) $$ -where $q_i$ is the atomic charge and $\boldsymbol{r}_i$ is the position vector of atom $i$ and $\alpha,\beta$ run over $ \{x,y,z\} $. This is one of the three conventions of traceless quadrupoles found in the literature. +where $q_i$ is the atomic charge and $\boldsymbol{r}_i$ is the position vector of atom $i$ and $\alpha,\beta$ run over $\{x,y,z\}$. This is one of the three conventions of traceless quadrupoles found in the literature. ## Usage From eaffec914d2eef1d0f6f29aba75bb2a71fc760eb Mon Sep 17 00:00:00 2001 From: kmuuga <59391957+kmuuga@users.noreply.github.com> Date: Mon, 19 Oct 2026 22:47:00 +0200 Subject: [PATCH 16/16] [docs] updating documentation --- docs/usage/quadrupole.md | 45 +++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/docs/usage/quadrupole.md b/docs/usage/quadrupole.md index 9b9e9bf1..8762dce9 100644 --- a/docs/usage/quadrupole.md +++ b/docs/usage/quadrupole.md @@ -5,16 +5,16 @@ The quadrupole model[@Muuga_2026] works similarly to the dipole model. The trace The ``model_params`` can be set, and are listed below along with their default values. -| Parameter | Default | Description | -|----------------------|---------|----------------------------------------------------------------------------------| -| `max_quadrupole` | `False` | When set to a number, exclude quadrupoles above this value in loss function | -| `quad_scale` | `1` | Quadrupole unit during training | -| `use_quad_per_atom` | `False` | Use the per-atom quadrupole in place of total quadrupole in loss function | +| Parameter | Default | Description | +|-------------------------|---------|-----------------------------------------------------------------------------------------| +| `max_quadrupole` | `False` | When set to a number, exclude quadrupoles above this value in loss function | +| `quad_scale` | `1` | Quadrupole unit during training | +| `use_quad_per_atom` | `False` | Use the per-atom quadrupole in place of total quadrupole in loss function | | `log_quad_per_atom` | `True` | Log the per-atom quadrupole error, automatically enabled with `use_quad_per_atoms=True` | -| `use_quad_weight` | `False` | Scale the energy loss according to the `'d_weight'` Tensor in the dataset | -| `use_l2` | `False` | Include L2 regularization in loss | -| `quad_loss_multiplier` | `1` | Weight of quadrupole loss | -| `l2_loss_multiplier` | `1` | Weight of l2 | +| `use_quad_weight` | `False` | Scale the energy loss according to the `'d_weight'` Tensor in the dataset | +| `use_l2` | `False` | Include L2 regularization in loss | +| `quad_loss_multiplier` | `1` | Weight of quadrupole loss | +| `l2_loss_multiplier` | `1` | Weight of l2 | ## Variants There are different variants of quadrupole and quadrupole-quadrupole models available. @@ -52,31 +52,28 @@ The models trained on the QM9 dataset can be found in the [PiNet2-DQ repository] ## Parameters -| Parameter | Default | Description | -|----------------------|---------|---------------------------------------------------------------------------------------------------------------| -| `max_quadrupole` | `False` | When set to a number, exclude quadrupoles above this value in loss function | -| `quad_scale` | `1` | Quadrupole unit during training | -| `quad_unit` | `1` | Output unit of quadrupole during prediction | +| Parameter | Default | Description | +|------------------------|---------|----------------------------------------------------------------------------------------------------------------------| +| `max_quadrupole` | `False` | When set to a number, exclude quadrupoles above this value in loss function | +| `quad_scale` | `1` | Quadrupole unit during training | +| `quad_unit` | `1` | Output unit of quadrupole during prediction | | `vector_quadrupole` | `True` | Toggle whether to use scalar or vector quadrupole predictions, should be the same as quadrupole moment of the dataset | -| `charge_neutrality` | `True` | Enable charge neutrality | +| `charge_neutrality` | `True` | Enable charge neutrality | | `neutral_unit` |`'system'`| If charge neutrality is applied, set the charge neutral unit. Choose `'system'` for system neutrality, or `'water_molecule'` for neutrality per water molecule | -| `regularization` | `True` | Enable regularization of the interaction prediction, only available for models containing the 'R' term | +| `regularization` | `True` | Enable regularization of the interaction prediction, only available for models containing the 'R' term | | `use_quad_per_atom` | `False` | Use the per-atom quadrupole in place of total quadrupole in loss function | -| `log_quad_per_atom` | `True` | Log the per-atom quadrupole error, automatically enabled with `use_quad_per_atoms=True` | -| `use_quad_weight` | `False` | Scale the energy loss according to the `'d_weight'` Tensor in the dataset | -| `use_l2` | `False` | Include L2 regularization in loss | -| `quad_loss_multiplier` | `1` | Weight of quadrupole loss | -| `l2_loss_multiplier` | `1` | Weight of l2 | +| `log_quad_per_atom` | `True` | Log the per-atom quadrupole error, automatically enabled with `use_quad_per_atoms=True` | +| `use_quad_weight` | `False` | Scale the energy loss according to the `'d_weight'` Tensor in the dataset | +| `use_l2` | `False` | Include L2 regularization in loss | +| `quad_loss_multiplier` | `1` | Weight of quadrupole loss | +| `l2_loss_multiplier` | `1` | Weight of l2 | ## Model specifications ### pinn.models.AC_quadrupole_model -::: pinn.models.AC_quadrupole_model ### pinn.models.AC_dipole_quadrupole.py -::: pinn.models.AC_dipole_quadrupole ### pinn.models.AC_AD_dipole_quadrupole.py -::: pinn.models.AC_AD_dipole_quadrupole