Port ComplexBinghamDistribution from MATLAB libDirectional

[Copilot]

Summary

Ports the ComplexBinghamDistribution from the MATLAB libDirectional library to Python.

New files

pyrecest/distributions/complex_hypersphere/

New submodule for distributions on the complex unit hypersphere.

• abstract_complex_hyperspherical_distribution.py — abstract base class for distributions on the complex unit sphere {z ∈ Cᵈ : ‖z‖ = 1}. Inherits from AbstractManifoldSpecificDistribution; exposes complex_dim, input_dim, and get_manifold_size() (surface area of S^{2d-1}).

• complex_bingham_distribution.py — main distribution class:

  • __init__(B) — accepts any Hermitian matrix B; computes log_c = -log C(B)
  • pdf(za) — evaluates exp(log_c + Re(z^H B z)); accepts a single column vector or a (d, n) batch
  • sample(n) — rejection sampler (Kent, Constable & Er, 2004 algorithm) returning complex unit vectors of shape (d, n)
  • log_norm(B, variant) — (negative) log of the normalization integral via the divided-differences analytical formula (exact for distinct eigenvalues; near-duplicate eigenvalues are perturbed à la the MATLAB makeSureEigenvaluesAreNotTooClose workaround); optional Monte Carlo variant
  • fit(Z) — ML estimate from a (d, N) complex sample matrix
  • estimate_parameter_matrix(S) — ML estimate from a scatter matrix via scipy.optimize.least_squares
  • cauchy_schwarz_divergence(cB1, cB2) — log_c(B1+B2) - ½(log_c(2B1) + log_c(2B2))

pyrecest/distributions/__init__.py

Exports ComplexBinghamDistribution.

pyrecest/tests/distributions/test_complex_bingham_distribution.py

17 unit tests covering constructor validation, normalization, pdf mode/batch/normalization, sampling, fitting, and divergence. All pass in ~1.3 s.

Notes

The MATLAB source uses abs(dot(za, B*za)) in its PDF formula. Since z^H B z is real for Hermitian B and unit vectors, the abs() applies as a magnitude operation on a signed real value, which is inconsistent with the normalization constant computation and makes the mode land at the wrong eigenvector. This Python port correctly uses .real to strip any floating-point imaginary residual while preserving the sign, matching the standard complex Bingham distribution definition from Kent (1994).

References

• Kent (1994) The Complex Bingham Distribution and Shape Analysis, JRSS-B 56(2):285–299
• Kent, Constable & Er (2004) Simulation for the complex Bingham distribution, Statistics and Computing 14:53–57

[github-actions]

❌MegaLinter analysis: Error

Descriptor	Linter	Files	Fixed	Errors	Warnings	Elapsed time
✅ COPYPASTE	jscpd	yes		no	no	9.03s
✅ JSON	prettier	2	0	0	0	0.76s
✅ JSON	v8r	2		0	0	2.76s
✅ MARKDOWN	markdownlint	1	0	0	0	0.67s
✅ MARKDOWN	markdown-table-formatter	1	0	0	0	0.19s
✅ PYTHON	bandit	290		0	0	3.85s
✅ PYTHON	black	290	8	0	0	5.7s
✅ PYTHON	flake8	290		0	0	2.11s
✅ PYTHON	isort	290	13	0	0	0.56s
✅ PYTHON	mypy	290		0	0	4.32s
❌ PYTHON	pylint	290		2	0	87.58s
✅ PYTHON	ruff	290	13	0	0	0.06s
✅ REPOSITORY	checkov	yes		no	no	23.03s
✅ REPOSITORY	gitleaks	yes		no	no	5.29s
✅ REPOSITORY	git_diff	yes		no	no	0.04s
✅ REPOSITORY	secretlint	yes		no	no	5.9s
✅ REPOSITORY	syft	yes		no	no	3.12s
✅ REPOSITORY	trivy-sbom	yes		no	no	1.64s
✅ REPOSITORY	trufflehog	yes		no	no	18.13s
✅ YAML	prettier	4	0	0	0	0.47s
✅ YAML	v8r	4		0	0	5.55s
✅ YAML	yamllint	4		0	0	0.47s

Detailed Issues

❌ PYTHON / pylint - 2 errors

************* Module pyrecest.distributions.complex_hypersphere.abstract_complex_hyperspherical_distribution
pyrecest/distributions/complex_hypersphere/abstract_complex_hyperspherical_distribution.py:52:4: W0237: Parameter 'xs' has been renamed to 'za' in overriding 'AbstractComplexHypersphericalDistribution.pdf' method (arguments-renamed)
************* Module pyrecest.distributions.complex_hypersphere.complex_bingham_distribution
pyrecest/distributions/complex_hypersphere/complex_bingham_distribution.py:83:4: R0914: Too many local variables (17/15) (too-many-locals)

------------------------------------
Your code has been rated at 10.00/10

See detailed reports in MegaLinter artifacts

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

• Documentation: Custom Flavors
• Command: npx mega-linter-runner@9.4.0 --custom-flavor-setup --custom-flavor-linters PYTHON_PYLINT,PYTHON_BLACK,PYTHON_FLAKE8,PYTHON_ISORT,PYTHON_BANDIT,PYTHON_MYPY,PYTHON_RUFF,COPYPASTE_JSCPD,JSON_V8R,JSON_PRETTIER,MARKDOWN_MARKDOWNLINT,MARKDOWN_MARKDOWN_TABLE_FORMATTER,REPOSITORY_CHECKOV,REPOSITORY_GIT_DIFF,REPOSITORY_GITLEAKS,REPOSITORY_SECRETLINT,REPOSITORY_SYFT,REPOSITORY_TRIVY_SBOM,REPOSITORY_TRUFFLEHOG,YAML_PRETTIER,YAML_YAMLLINT,YAML_V8R

Show us your support by starring ⭐ the repository

[github-actions]

Test Results

   12 files     12 suites   4h 42m 29s ⏱️
  752 tests   752 ✅     0 💤 0 ❌
9 308 runs  7 836 ✅ 1 472 💤 0 ❌

Results for commit 7fdedd7.