1/* ----------------------------------------------------------------------------
2
3 * GTSAM Copyright 2010, Georgia Tech Research Corporation,
4 * Atlanta, Georgia 30332-0415
5 * All Rights Reserved
6 * Authors: Frank Dellaert, et al. (see THANKS for the full author list)
7
8 * See LICENSE for the license information
9
10 * -------------------------------------------------------------------------- */
11
12/**
13 * @file ConcurrentFilteringAndSmoothing.h
14 * @brief Base classes for the 'filter' and 'smoother' portion of the Concurrent
15 * Filtering and Smoothing architecture, as well as an external synchronization
16 * function. These classes act as an interface only.
17 * @author Stephen Williams
18 */
19
20// \callgraph
21#pragma once
22
23#include <gtsam_unstable/dllexport.h>
24#include <gtsam/nonlinear/NonlinearFactorGraph.h>
25#include <gtsam/nonlinear/Values.h>
26#include <gtsam/linear/GaussianFactorGraph.h>
27
28namespace gtsam {
29
30// Forward declare the Filter and Smoother classes for the 'synchronize' function
31class ConcurrentFilter;
32class ConcurrentSmoother;
33
34void GTSAM_UNSTABLE_EXPORT synchronize(ConcurrentFilter& filter, ConcurrentSmoother& smoother);
35
36/**
37 * The interface for the 'Filter' portion of the Concurrent Filtering and Smoother architecture.
38 */
39class GTSAM_UNSTABLE_EXPORT ConcurrentFilter {
40public:
41 typedef std::shared_ptr<ConcurrentFilter> shared_ptr;
42
43 /** Default constructor */
44 ConcurrentFilter() = default;
45
46 /** Default destructor */
47 virtual ~ConcurrentFilter() = default;
48
49 /** Implement a standard 'print' function */
50 virtual void print(
51 const std::string& s = "Concurrent Filter:\n",
52 const KeyFormatter& keyFormatter = DefaultKeyFormatter) const = 0;
53
54 /** Check if two Concurrent Smoothers are equal */
55 virtual bool equals(const ConcurrentFilter& rhs, double tol = 1e-9) const = 0;
56
57 /**
58 * Perform any required operations before the synchronization process starts.
59 * Called by 'synchronize'
60 */
61 virtual void presync() {}
62
63 /**
64 * Populate the provided containers with factors that constitute the filter branch summarization
65 * needed by the smoother. Also, linearization points for the new root clique must be provided.
66 *
67 * @param summarizedFactors The summarized factors for the filter branch
68 * @param separatorValues The linearization points of the separator variables
69 */
70 virtual void getSummarizedFactors(NonlinearFactorGraph& summarizedFactors, Values& separatorValues) = 0;
71
72 /**
73 * Populate the provided containers with factors being sent to the smoother from the filter. These
74 * may be original nonlinear factors, or factors encoding a summarization of the filter information.
75 * The specifics will be implementation-specific for a given filter.
76 *
77 * @param smootherFactors The new factors to be added to the smoother
78 * @param smootherValues The linearization points of any new variables
79 */
80 virtual void getSmootherFactors(NonlinearFactorGraph& smootherFactors, Values& smootherValues) = 0;
81
82 /**
83 * Apply the updated version of the smoother branch summarized factors.
84 *
85 * @param summarizedFactors An updated version of the smoother branch summarized factors
86 * @param separatorValues The linearization points of the separator variables
87 */
88 virtual void synchronize(const NonlinearFactorGraph& summarizedFactors, const Values& separatorValues) = 0;
89
90 /**
91 * Perform any required operations after the synchronization process finishes.
92 * Called by 'synchronize'
93 */
94 virtual void postsync() {}
95
96}; // ConcurrentFilter
97
98/**
99 * The interface for the 'Smoother' portion of the Concurrent Filtering and Smoother architecture.
100 */
101class GTSAM_UNSTABLE_EXPORT ConcurrentSmoother {
102public:
103 typedef std::shared_ptr<ConcurrentSmoother> shared_ptr;
104
105 /** Default constructor */
106 ConcurrentSmoother() {}
107
108 /** Default destructor */
109 virtual ~ConcurrentSmoother() = default;
110
111 /** Implement a standard 'print' function */
112 virtual void print(
113 const std::string& s = "Concurrent Smoother:\n",
114 const KeyFormatter& keyFormatter = DefaultKeyFormatter) const = 0;
115
116 /** Check if two Concurrent Smoothers are equal */
117 virtual bool equals(const ConcurrentSmoother& rhs, double tol = 1e-9) const = 0;
118
119 /**
120 * Perform any required operations before the synchronization process starts.
121 * Called by 'synchronize'
122 */
123 virtual void presync() {}
124
125 /**
126 * Populate the provided containers with factors that constitute the smoother branch summarization
127 * needed by the filter.
128 *
129 * @param summarizedFactors The summarized factors for the filter branch
130 * @param separatorValues The linearization points of the separator variables
131 */
132 virtual void getSummarizedFactors(NonlinearFactorGraph& summarizedFactors, Values& separatorValues) = 0;
133
134 /**
135 * Apply the new smoother factors sent by the filter, and the updated version of the filter
136 * branch summarized factors.
137 *
138 * @param smootherFactors A set of new factors added to the smoother from the filter
139 * @param smootherValues Linearization points for any new variables
140 * @param summarizedFactors An updated version of the filter branch summarized factors
141 * @param rootValues The linearization point of the root variables
142 */
143 virtual void synchronize(const NonlinearFactorGraph& smootherFactors, const Values& smootherValues,
144 const NonlinearFactorGraph& summarizedFactors, const Values& rootValues) = 0;
145
146 /**
147 * Perform any required operations after the synchronization process finishes.
148 * Called by 'synchronize'
149 */
150 virtual void postsync() {}
151
152}; // ConcurrentSmoother
153
154namespace internal {
155
156 /** Calculate the marginal on the specified keys, returning a set of LinearContainerFactors.
157 * Unlike other GTSAM functions with similar purposes, this version can operate on disconnected graphs. */
158 NonlinearFactorGraph calculateMarginalFactors(const NonlinearFactorGraph& graph, const Values& theta,
159 const KeySet& remainingKeys, const GaussianFactorGraph::Eliminate& eliminateFunction);
160
161}
162
163}/// namespace gtsam
164