The generic framework for solving approximate inference problem with BP

[Morningliumengkun]

Summary

This update completes the PyTorch Belief Propagation (BP) module with core fixes,
documentation, examples, and comprehensive unit tests. It also documents
environment setup steps so others (or AI agents) can reproduce the correct setup
quickly.

Key Changes

• Core BP fix: Reworked factor-to-variable message computation to avoid
  einsum operand mismatches and correctly handle single-variable factors in
  pytorch_bp/belief_propagation.py.
• UAI parsing fixes: Simplified and stabilized read_model_from_string in
  pytorch_bp/uai_parser.py, preserving original scopes and tables.
• Docs: Added docs/ with mathematical description, API reference, and
  usage guide.
• Examples: Added examples/ with a simple UAI model and evidence example
  scripts.
• Tests: Added tests/ for parser, BP correctness vs exact marginals, and
  integration coverage.
• Environment guidance: Updated README.md to include environment setup
  (Windows/macOS/Linux), examples, and a table explaining unit tests.
• Repo hygiene: Added .gitignore to avoid committing Python cache files.

How to Run

pip install -r requirements.txt
python -m unittest discover -s tests
python examples/simple_example.py
python examples/evidence_example.py

Notes

• Use PYTHONPATH (documented in README.md) or pip install -e . so
  pytorch_bp imports resolve correctly.
• The examples and tests assume execution from the repo root.

Testing

• Test parsing examples/asia-network/model.uai
• Test BP initialization and state creation
• Test message collection and processing
• Test convergence checking
• Test marginal computation
• Test evidence application
• Compare results with provided reference results

[GiggleLiu]

Please compare your result with some known correct result, with an example.

[Copilot]

Pull request overview

This PR implements a comprehensive PyTorch-based Belief Propagation (BP) module for discrete factor graphs using the UAI file format. The implementation provides core BP algorithms, UAI parsing utilities, documentation, examples, and extensive unit tests. The design follows the tensor-contraction approach inspired by TensorInference.jl.

Changes:

• Implements complete belief propagation algorithm with message passing, convergence checking, and marginal computation
• Adds UAI format parser for reading probabilistic graphical models and evidence files
• Provides comprehensive test suite covering parsing, BP correctness, evidence handling, and integration scenarios
• Includes documentation with mathematical descriptions, API reference, and usage guides
• Adds example scripts demonstrating basic BP usage and evidence application

Reviewed changes

Copilot reviewed 17 out of 19 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
pytorch_bp/belief_propagation.py	Core BP implementation with message passing, convergence, and evidence handling
pytorch_bp/uai_parser.py	UAI format parser for models and evidence files
pytorch_bp/utils.py	Utility functions (currently contains unused deep_copy_messages)
pytorch_bp/__init__.py	Module exports and public API definition
tests/test_bp_basic.py	Basic BP tests comparing against exact marginals
tests/test_integration.py	Integration tests for file I/O and full pipeline
tests/test_uai_parser.py	Parser validation tests
tests/testcase.py	Additional test cases for unary factors, chains, and normalization
tests/__init__.py	Test package initialization
examples/simple_example.py	Basic BP usage example
examples/evidence_example.py	Evidence application example
examples/simple_model.uai	Example UAI model file
examples/simple_model.evid	Example evidence file
docs/mathematical_description.md	Mathematical description of BP algorithm
docs/api_reference.md	Public API documentation
docs/usage_guide.md	Usage examples and tips
README.md	Complete rewrite with setup instructions, examples, and test documentation
requirements.txt	PyTorch dependency specification
.gitignore	Python cache file exclusions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[GiggleLiu]

1. Please resolve conflicts.
2. Please restructure the project file layout to fit the main branch.

[codecov]

Codecov Report

❌ Patch coverage is 94.81132% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.68%. Comparing base (7acf58e) to head (6b3f4e2).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/bpdecoderplus/pytorch_bp/belief_propagation.py	95.00%	7 Missing ⚠️
src/bpdecoderplus/pytorch_bp/uai_parser.py	94.20%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #17      +/-   ##
==========================================
+ Coverage   94.28%   94.68%   +0.39%     
==========================================
  Files           3        6       +3     
  Lines          70      282     +212     
==========================================
+ Hits           66      267     +201     
- Misses          4       15      +11     

Flag	Coverage Δ
unittests	94.68% <94.81%> (+0.39%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[GiggleLiu]

Well done! @Morningliumengkun