Skip to content

Covariance#

cheersafe.tools.Covariance builds covariance matrices from component counts, mean values, coefficients of variation, and correlation assumptions.

Purpose And When To Use#

Use Covariance.create_cov_matrix() before Latin hypercube sampling when component samples should share intra-component and inter-component correlation. Damage probability workflows use this pattern for correlated component resistance sampling.

Inputs#

Input Unit, indexing, or shape
num_component List of component group sizes. The sum is the matrix dimension.
temp_mean NumPy array of mean values, one per element after expanding all groups. Units match the sampled quantity, such as psf or lbs. Shape [sum(num_component)].
temp_cv NumPy array of coefficients of variation, same shape as temp_mean. Unitless.
inter_correlation Correlation between elements in different component groups. Default 0.2.
intra_correlation Correlation between elements in the same component group. Default 0.4.

Inputs are zero-indexed Python arrays/lists. The group order in num_component defines the block structure of the returned matrix.

Outputs And Returns#

create_cov_matrix() returns a NumPy array with shape [sum(num_component), sum(num_component)]. Diagonal values are (temp_mean * temp_cv) ** 2. Off-diagonal values are the selected correlation coefficient multiplied by the outer product of standard deviations.

No files are read or written, and no class or instance state is assigned.

AUTO_LOAD_DATASETS Behavior#

Covariance does not load files and does not inspect Config.AUTO_LOAD_DATASETS.

AUTO_EXECUTE_METHODS Behavior#

Covariance has no constructor and no automatic execution behavior. The matrix is created only when create_cov_matrix() is called.

Minimal Automatic Example#

There is no constructor-side automatic behavior for Covariance; the direct call is the normal use:

PYTHONPATH=src python3 - <<'PY'
import numpy as np
from cheersafe.tools import Covariance

sigma = Covariance.create_cov_matrix(
    [2, 1],
    np.array([10.0, 12.0, 8.0]),
    np.array([0.1, 0.2, 0.15]),
)
print(sigma.shape)
print(np.round(np.diag(sigma), 3).tolist())
PY

Minimal Manual-Control Example#

PYTHONPATH=src python3 - <<'PY'
import numpy as np
from cheersafe.tools import Covariance, Sampling

mean = np.array([10.0, 12.0, 8.0])
cv = np.array([0.1, 0.2, 0.15])
sigma = Covariance.create_cov_matrix(
    [2, 1],
    mean,
    cv,
    inter_correlation=0.1,
    intra_correlation=0.5,
)
samples = Sampling.generate_lhs_samples_norm(5, mean, sigma, seed=11)

print(sigma.shape)
print(samples.shape)
PY