From 468b02d3d156a08aa27bd2d97ecf05aea7e10200 Mon Sep 17 00:00:00 2001
From: John Vouvakis Manousakis <ioannis_vm@berkeley.edu>
Date: Sat, 25 May 2024 10:27:18 -0700
Subject: [PATCH] Explain current validation tests.

---
 pelicun/tests/validation/0/readme.md          |  4 ++++
 .../tests/validation/0/test_loss_function.py  |  7 ++++---
 pelicun/tests/validation/1/readme.md          | 20 +++++++++++++++++++
 3 files changed, 28 insertions(+), 3 deletions(-)
 create mode 100644 pelicun/tests/validation/0/readme.md
 create mode 100644 pelicun/tests/validation/1/readme.md

diff --git a/pelicun/tests/validation/0/readme.md b/pelicun/tests/validation/0/readme.md
new file mode 100644
index 000000000..ab3283ee0
--- /dev/null
+++ b/pelicun/tests/validation/0/readme.md
@@ -0,0 +1,4 @@
+# Loss function validation test
+
+In this example, a single loss function is defined as a 1:1 mapping of the input EDP.
+This means that the resulting loss distribution will be the same as the EDP distribution, allowing us to test and confirm that this is what happens.
diff --git a/pelicun/tests/validation/0/test_loss_function.py b/pelicun/tests/validation/0/test_loss_function.py
index d91631f0a..b7834154e 100644
--- a/pelicun/tests/validation/0/test_loss_function.py
+++ b/pelicun/tests/validation/0/test_loss_function.py
@@ -41,9 +41,10 @@
 """
 Validation test on loss functions.
 
-In this example, the loss function is a 1:1 mapping of the input EDP.
-This means that the resulting loss distribution will be the same as
-the EDP input distribution.
+In this example, a single loss function is defined as a 1:1 mapping of
+the input EDP.  This means that the resulting loss distribution will
+be the same as the EDP distribution, allowing us to test and confirm
+that this is what happens.
 
 """
 
diff --git a/pelicun/tests/validation/1/readme.md b/pelicun/tests/validation/1/readme.md
new file mode 100644
index 000000000..19d3a511e
--- /dev/null
+++ b/pelicun/tests/validation/1/readme.md
@@ -0,0 +1,20 @@
+# Damage state probability validation test
+
+Here we test whether we get the correct damage state probabilities for a single component with two damage states.
+For such a component, assuming the EDP demand and the fragility curve capacities are all lognormal, there is a closed-form solution for the probability of each damage state.
+We utilize those equations to ensure that the probabilities obtained from our Monte-Carlo sample are in line with our expectations.
+
+## Equations
+
+If $\mathrm{Y} \sim \textrm{LogNormal}(\delta, \beta)$, then  $\mathrm{X} = \log(\mathrm{Y}) \sim \textrm{Normal}(\mu, \sigma)$ with $\mu = \log(\delta)$ and $\sigma = \beta$.
+
+```math
+\begin{align*}
+\mathrm{P}(\mathrm{DS}=0) &= 1 - \Phi\left(\frac{\log(\delta_D) - \log(\delta_{C1})}{\sqrt{\beta_{D}^2 + \beta_{C1}^2}}\right), \\
+\mathrm{P}(\mathrm{DS}=1) &= \Phi\left(\frac{\log(\delta_D) - \log(\delta_{C1})}{\sqrt{\beta_D^2 + \beta_{C1}^2}}\right) - \Phi\left(\frac{\log(\delta_{D}) - \log(\delta_{C2})}{\sqrt{\beta_D^2 + \beta_{C2}^2}}\right), \\
+\mathrm{P}(\mathrm{DS}=2) &= \Phi\left(\frac{\log(\delta_D) - \log(\delta_{C2})}{\sqrt{\beta_D^2 + \beta_{C2}^2}}\right), \\
+\end{align*}
+```
+where $\Phi$ is the cumulative distribution function of the standard normal distribution, $\delta_{C1}$, $\delta_{C2}$, $\beta_{C1}$, $\beta_{C2}$ are the medians and dispersions of the fragility curve capacities, and $\delta_{D}$, $\beta_{D}$ is the median and dispersion of the EDP demand.
+
+The equations inherently asume that the capacity RVs for the damage states are perfectly correlated, which is the case for sequential damage states.