GPy/backlog/features/2025-08-15_lfm-kernel-code-review.md

id	title	status	priority	created	last_updated	owner	github_issue	dependencies	tags
lfm-kernel-code-review	Review existing LFM kernel implementations	Completed	High	2025-08-15	2025-08-15	Neil Lawrence			lfm kernel code-review documentation

Review existing LFM kernel implementations

Description

Conduct a comprehensive review of existing LFM (Latent Force Model) kernel implementations in both GPy and MATLAB to understand the current state, design decisions, and limitations.

Background

• GPy has existing ODE-based kernels (EQ_ODE1, EQ_ODE2) that implement LFM concepts
• MATLAB implementation in GPmat provides a more complete LFM framework
• Need to understand differences and identify modernization opportunities

Tasks

• Review GPy/kern/src/eq_ode1.py and eq_ode2.py implementations
• Analyze MATLAB LFM implementation structure and patterns
• Document current limitations and inconsistencies
• Identify reusable components and design patterns
• Compare parameter handling approaches
• Review cross-kernel computation methods
• Document mathematical foundations and implementation details

Acceptance Criteria

• Complete documentation of existing implementations
• Clear understanding of design differences between GPy and MATLAB versions
• Identified list of modernization opportunities
• Documentation of mathematical foundations
• Assessment of current limitations and bugs

Implementation Notes

• Focus on understanding the mathematical foundations from the papers
• Pay attention to parameter tying and multi-output handling
• Document the differential equation structure and kernel computation
• Identify opportunities for using GPy's modern multioutput kernel approach

Related

• CIP: 0001 (LFM kernel implementation)
• Papers: Álvarez et al. (2009, 2012), Lawrence et al. (2006)
• Backlog: parameter-tying-framework (fundamental dependency)

Progress Updates

2025-08-15

Started code review task. Initial findings:

GPy Implementations:

• EQ_ODE1: First-order differential equation kernel with decay rates and sensitivities
• EQ_ODE2: Second-order differential equation kernel with spring/damper constants
• Both use GPy's multioutput approach with output index as second input dimension
• Complex kernel computation with multiple covariance types (Kuu, Kfu, Kuf, Kusu)
• Uses @Cache_this decorator for performance optimization

GPmat Implementation:

• More complete framework with lfmCreate, lfmKernCompute, lfmKernParamInit
• Uses multi-kernel approach with parameter tying
• Supports multiple displacements driven by multiple forces
• Cleaner separation of concerns with dedicated model creation

Key Differences:

• GPy uses single kernel class per ODE order, GPmat uses multi-kernel composition
• GPy has more complex index handling for multioutput
• GPmat has better parameter organization and tying mechanisms
• Critical Gap: GPy lacks parameter tying framework (GPmat has modelTieParam())

2025-08-15 (Parameter Tying Discovery)

Major Finding: Identified parameter tying as a fundamental limitation affecting LFM implementation:

• Created backlog item for parameter tying investigation
• Found 5+ years of GitHub issues requesting this functionality
• Related to paramz framework limitation (documented but not implemented)
• Created CIP-0002 for community discussion of parameter tying solutions
• Decision: Proceed with LFM implementation assuming parameter tying will be addressed separately
• Rationale: Keeps implementation clean and focused on core LFM functionality