Port ComplexBinghamDistribution from MATLAB libDirectional

[Copilot]

Summary

Ports ComplexBinghamDistribution from libDirectional (MATLAB) to Python.

Changes

New files

• pyrecets/distributions/hypersphere_subset/complex_bingham_distribution.py — ComplexBinghamDistribution class inheriting AbstractHypersphericalDistribution:

  • __init__(B): validates that B is Hermitian, computes normalization constant
  • pdf(za): evaluates density at complex unit vectors of shape (d,) or (d, n)
  • sample(n): rejection sampler per Kent, Constable & Er (2004), Stats & Comput.
  • log_norm(B): eigenvalue-shift + closed-form Vandermonde simplex formula for ∫_{S^{2D-1}} exp(z^H B z) dσ(z) — exact for all D, numerically stable
  • cauchy_schwarz_divergence(cB1, cB2): static method
  • fit(Z) / estimate_parameter_matrix(S): ML fitting via least-squares eigenvalue matching
  • integral(n_samples): Monte Carlo normalization check
  • unit_sphere_surface(d): surface area of the unit complex sphere in C^d

• pyrecets/tests/distributions/test_complex_bingham_distribution.py — 13 unit tests covering construction, normalization constant, pdf normalization, pdf symmetry, sampling, Cauchy-Schwarz divergence, and surface area

Modified files

• pyrecets/distributions/__init__.py — registers ComplexBinghamDistribution in imports and __all__

Notes

• The normalization uses the exact formula c(λ) = 2π^D · Σ_j exp(λ_j) / Π_{k≠j}(λ_j − λ_k) derived from the Dirichlet(1,…,1) marginal of uniform random points on S^{2D-1}. This replaces the Kent (1994) eq. (2.3) formula which applies to complex projective space CP^{D-1}, not S^{2D-1}.
• The sign convention follows MATLAB: log_norm_const = −log(∫ exp(z^H B z) dσ), so pdf(z) = exp(log_norm_const + Re(z^H B z)).
• fit() / estimate_parameter_matrix() provide a numerical ML implementation; the full analytical solution of Kent (1994) §3 is left as a future enhancement.

[github-actions]

❌MegaLinter analysis: Error

Descriptor	Linter	Files	Fixed	Errors	Warnings	Elapsed time
✅ COPYPASTE	jscpd	yes		no	no	9.75s
✅ JSON	prettier	2	0	0	0	0.5s
✅ JSON	v8r	2		0	0	3.12s
✅ MARKDOWN	markdownlint	1	0	0	0	0.64s
✅ MARKDOWN	markdown-table-formatter	1	0	0	0	0.29s
✅ PYTHON	bandit	288		0	0	3.83s
✅ PYTHON	black	288	9	0	0	5.86s
✅ PYTHON	flake8	288		0	0	2.14s
✅ PYTHON	isort	288	12	0	0	0.57s
✅ PYTHON	mypy	288		0	0	4.4s
❌ PYTHON	pylint	288		11	0	87.62s
✅ PYTHON	ruff	288	12	0	0	0.06s
✅ REPOSITORY	checkov	yes		no	no	22.78s
✅ REPOSITORY	gitleaks	yes		no	no	5.37s
✅ REPOSITORY	git_diff	yes		no	no	0.04s
✅ REPOSITORY	secretlint	yes		no	no	5.88s
✅ REPOSITORY	syft	yes		no	no	3.49s
✅ REPOSITORY	trivy-sbom	yes		no	no	1.73s
✅ REPOSITORY	trufflehog	yes		no	no	18.07s
✅ YAML	prettier	4	0	0	0	0.5s
✅ YAML	v8r	4		0	0	5.87s
✅ YAML	yamllint	4		0	0	0.41s

Detailed Issues

❌ PYTHON / pylint - 11 errors

************* Module pyrecest.distributions.hypersphere_subset.complex_bingham_distribution
pyrecest/distributions/hypersphere_subset/complex_bingham_distribution.py:44:4: W0237: Parameter 'xs' has been renamed to 'za' in overriding 'ComplexBinghamDistribution.pdf' method (arguments-renamed)
pyrecest/distributions/hypersphere_subset/complex_bingham_distribution.py:70:4: R0914: Too many local variables (18/15) (too-many-locals)
************* Module pyrecest.tests.distributions.test_complex_bingham_distribution
pyrecest/tests/distributions/test_complex_bingham_distribution.py:45:8: E1101: Module 'pyrecest' has no 'backend' member (no-member)
pyrecest/tests/distributions/test_complex_bingham_distribution.py:57:8: E1101: Module 'pyrecest' has no 'backend' member (no-member)
pyrecest/tests/distributions/test_complex_bingham_distribution.py:72:8: E1101: Module 'pyrecest' has no 'backend' member (no-member)
pyrecest/tests/distributions/test_complex_bingham_distribution.py:82:8: E1101: Module 'pyrecest' has no 'backend' member (no-member)
pyrecest/tests/distributions/test_complex_bingham_distribution.py:99:8: E1101: Module 'pyrecest' has no 'backend' member (no-member)
pyrecest/tests/distributions/test_complex_bingham_distribution.py:115:8: E1101: Module 'pyrecest' has no 'backend' member (no-member)
pyrecest/tests/distributions/test_complex_bingham_distribution.py:126:8: E1101: Module 'pyrecest' has no 'backend' member (no-member)
pyrecest/tests/distributions/test_complex_bingham_distribution.py:139:8: E1101: Module 'pyrecest' has no 'backend' member (no-member)
pyrecest/tests/distributions/test_complex_bingham_distribution.py:149:8: E1101: Module 'pyrecest' has no 'backend' member (no-member)

-----------------------------------
Your code has been rated at 9.96/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 46m 23s ⏱️
  748 tests   748 ✅     0 💤 0 ❌
9 260 runs  7 752 ✅ 1 508 💤 0 ❌

Results for commit efde0fb.