torchref.base.metrics.loss module

Loss functions for crystallographic refinement.

Functions for computing various loss/likelihood functions used in structure refinement.

torchref.base.metrics.loss.nll_xray(F_obs, F_calc, sigma_F_obs)[source]

Compute X-ray negative log-likelihood assuming Gaussian distribution.

Parameters:

  • F_obs (torch.Tensor or MaskedTensor) – Observed structure factor amplitudes.

  • F_calc (torch.Tensor) – Calculated structure factors (complex).

  • sigma_F_obs (torch.Tensor or MaskedTensor) – Standard deviations of observed amplitudes.

Returns:

Mean negative log-likelihood.

Return type:

torch.Tensor

torchref.base.metrics.loss.nll_xray_sum(F_obs, F_calc, sigma_F_obs)[source]

Compute summed X-ray negative log-likelihood assuming Gaussian distribution.

Parameters:

  • F_obs (torch.Tensor or MaskedTensor) – Observed structure factor amplitudes.

  • F_calc (torch.Tensor) – Calculated structure factors (complex).

  • sigma_F_obs (torch.Tensor or MaskedTensor) – Standard deviations of observed amplitudes.

Returns:

Sum of negative log-likelihood values.

Return type:

torch.Tensor

torchref.base.metrics.loss.nll_xray_lognormal(F_obs, F_calc, sigma_F_obs, eps=1e-10)[source]

Compute X-ray negative log-likelihood assuming lognormal distribution.

This is a more realistic model for structure factor amplitudes, which must be positive. For a lognormal distribution LogNormal(mu, sigma^2), the NLL is: NLL = 0.5*(log(x) - mu)^2/sigma^2 + log(x) + log(sigma) + 0.5*log(2*pi)

Where mu and sigma are derived from F_obs and sigma_F_obs using: - sigma = sqrt(log(1 + (sigma_F/F)^2)) - mu = log(F) - sigma^2/2

Parameters:

  • F_obs (torch.Tensor) – Observed structure factor amplitudes.

  • F_calc (torch.Tensor) – Calculated structure factors (complex).

  • sigma_F_obs (torch.Tensor) – Standard deviations of observed amplitudes.

  • eps (float, optional) – Small value to avoid numerical issues. Default is 1e-10.

Returns:

Mean negative log-likelihood.

Return type:

torch.Tensor

torchref.base.metrics.loss.log_loss(F_obs, F_calc, sigma_F_obs)[source]

Compute log-space loss between observed and calculated structure factors.

Parameters:

  • F_obs (torch.Tensor) – Observed structure factor amplitudes.

  • F_calc (torch.Tensor) – Calculated structure factors (complex).

  • sigma_F_obs (torch.Tensor) – Standard deviations of observed amplitudes (unused).

Returns:

Mean absolute difference in log space.

Return type:

torch.Tensor

torchref.base.metrics.loss.estimate_sigma_I(I)[source]

Estimate standard deviation of intensities.

Separates positive and negative values for robust estimation.

Parameters:

I (torch.Tensor) – Intensity values.

Returns:

Estimated standard deviations.

Return type:

torch.Tensor

torchref.base.metrics.loss.estimate_sigma_F(F)[source]

Estimate standard deviation of structure factor amplitudes.

Parameters:

F (torch.Tensor) – Structure factor amplitudes.

Returns:

Estimated standard deviations.

Return type:

torch.Tensor

torchref.base.metrics.loss.gaussian_to_lognormal_sigma(F, sigma_F, eps=1e-10)[source]

Approximate the sigma parameter of a lognormal distribution from Gaussian statistics.

If we assume F comes from a lognormal distribution X ~ LogNormal(mu, sigma^2), then: - Mean: E[X] = F - Std: sqrt(Var[X]) = sigma_F

For lognormal distribution: - E[X] = exp(mu + sigma^2/2) - Var(X) = exp(2*mu + sigma^2)(exp(sigma^2) - 1)

We can derive: - CV^2 = Var[X]/E[X]^2 = exp(sigma^2) - 1 - sigma = sqrt(log(1 + CV^2))

where CV = sigma_F/F is the coefficient of variation.

Parameters:

  • F (torch.Tensor) – Structure factor amplitudes (mean of the distribution).

  • sigma_F (torch.Tensor) – Standard deviations.

  • eps (float, optional) – Small value to avoid division by zero. Default is 1e-10.

Returns:

Sigma parameter for lognormal distribution.

Return type:

torch.Tensor

torchref.base.metrics.loss.gaussian_to_lognormal_mu(F, sigma_lognormal, eps=1e-10)[source]

Calculate the mu parameter of a lognormal distribution given F and sigma.

For lognormal distribution X ~ LogNormal(mu, sigma^2): - E[X] = exp(mu + sigma^2/2)

Solving for mu: - mu = log(E[X]) - sigma^2/2

Parameters:

  • F (torch.Tensor) – Structure factor amplitudes (mean of the distribution).

  • sigma_lognormal (torch.Tensor) – Sigma parameter from lognormal distribution.

  • eps (float, optional) – Small value to avoid log of zero. Default is 1e-10.

Returns:

Mu parameter for lognormal distribution.

Return type:

torch.Tensor