STIR  6.2.0
GeneralisedObjectiveFunction.h
Go to the documentation of this file.
1 //
2 //
3 /*
4  Copyright (C) 2003- 2009, Hammersmith Imanet Ltd
5  Copyright (C) 2018, 2020, 2024 University College London
6  Copyright (C) 2016, University of Hull
7  This file is part of STIR.
8 
9  SPDX-License-Identifier: Apache-2.0
10 
11  See STIR/LICENSE.txt for details
12 */
24 #ifndef __stir_recon_buildblock_GeneralisedObjectiveFunction_H__
25 #define __stir_recon_buildblock_GeneralisedObjectiveFunction_H__
26 
27 #include "stir/RegisteredObject.h"
28 #include "stir/ParsingObject.h"
29 #include "stir/shared_ptr.h"
31 #include <string>
32 
33 #include "stir/ExamData.h"
34 #include "stir/ProjData.h"
36 
37 START_NAMESPACE_STIR
38 
39 class Succeeded;
40 
82 template <typename TargetT>
83 class GeneralisedObjectiveFunction : public RegisteredObject<GeneralisedObjectiveFunction<TargetT>>
84 {
85 public:
87  : already_set_up(false)
88  {}
89 
90  ~GeneralisedObjectiveFunction() override;
91 
93 
97  virtual TargetT* construct_target_ptr() const = 0;
98 
100  virtual Succeeded set_up(shared_ptr<TargetT> const& target_sptr);
101 
103 
114  virtual void compute_sub_gradient(TargetT& gradient, const TargetT& current_estimate, const int subset_num);
115 
117 
120  virtual void compute_sub_gradient_without_penalty(TargetT& gradient, const TargetT& current_estimate, const int subset_num) = 0;
121 
123 
130  virtual void compute_gradient(TargetT& gradient, const TargetT& current_estimate);
131 
133 
138  virtual void compute_gradient_without_penalty(TargetT& gradient, const TargetT& current_estimate);
139 
141 
142  virtual double compute_objective_function_without_penalty(const TargetT& current_estimate, const int subset_num);
143 
145 
147  virtual double compute_objective_function_without_penalty(const TargetT& current_estimate);
148 
150 
158  double compute_penalty(const TargetT& current_estimate, const int subset_num);
160 
161  double compute_penalty(const TargetT& current_estimate);
162 
164 
169  double compute_objective_function(const TargetT& current_estimate, const int subset_num);
170 
172 
177  double compute_objective_function(const TargetT& current_estimate);
178 
180  double compute_value(const TargetT& current_estimate) { return compute_objective_function(current_estimate); }
181 
183 
196  virtual void fill_nonidentifiable_target_parameters(TargetT& target, const float value) const {}
197 
199 
206  Succeeded add_multiplication_with_approximate_sub_Hessian_without_penalty(TargetT& output,
207  const TargetT& input,
208  const int subset_num) const;
209  Succeeded add_multiplication_with_approximate_sub_Hessian(TargetT& output, const TargetT& input, const int subset_num) const;
210  Succeeded add_multiplication_with_approximate_Hessian_without_penalty(TargetT& output, const TargetT& input) const;
211  Succeeded add_multiplication_with_approximate_Hessian(TargetT& output, const TargetT& input) const;
213 
215 
222  Succeeded accumulate_Hessian_times_input(TargetT& output, const TargetT& current_image_estimate, const TargetT& input) const;
223 
224  Succeeded accumulate_Hessian_times_input_without_penalty(TargetT& output,
225  const TargetT& current_image_estimate,
226  const TargetT& input) const;
227 
228  Succeeded accumulate_sub_Hessian_times_input(TargetT& output,
229  const TargetT& current_image_estimate,
230  const TargetT& input,
231  const int subset_num) const;
232  Succeeded accumulate_sub_Hessian_times_input_without_penalty(TargetT& output,
233  const TargetT& current_image_estimate,
234  const TargetT& input,
235  const int subset_num) const;
236 
238 
240  std::string get_objective_function_values_report(const TargetT& current_estimate);
241 
243  int get_num_subsets() const;
244 
245  // //! Virtual get normalisation, it will be defined by the derived class
246  // virtual const shared_ptr<BinNormalisation> &
247  // get_normalisation_sptr() const =0;
248 
249  virtual std::unique_ptr<ExamInfo> get_exam_info_uptr_for_target() const
250  {
251  auto exam_info_uptr = unique_ptr<ExamInfo>(new ExamInfo(*(this->get_input_data().get_exam_info_sptr())));
252  return exam_info_uptr;
253  }
254 
256 
258  virtual int set_num_subsets(const int num_subsets) = 0;
259 
261 
269  bool subsets_are_approximately_balanced() const;
271 
277  bool subsets_are_approximately_balanced(std::string& warning_message) const;
278 
280  bool prior_is_zero() const;
281 
283 
285  GeneralisedPrior<TargetT>* const get_prior_ptr() const;
286 
287  shared_ptr<GeneralisedPrior<TargetT>> get_prior_sptr();
288 
290 
292  void set_prior_sptr(const shared_ptr<GeneralisedPrior<TargetT>>&);
293 
298  virtual void set_input_data(const shared_ptr<ExamData>&) = 0;
299 
301 
302  virtual const ExamData& get_input_data() const = 0;
303 
309  virtual void set_additive_proj_data_sptr(const shared_ptr<ExamData>&) = 0;
310 
315  virtual void set_normalisation_sptr(const shared_ptr<BinNormalisation>&) = 0;
316 
317 protected:
318  int num_subsets;
319  bool already_set_up;
320 
321  shared_ptr<GeneralisedPrior<TargetT>> prior_sptr;
322 
324 
325  void set_defaults() override;
327 
328  void initialise_keymap() override;
329 
330  // virtual bool post_processing();
331 
333 
342  virtual bool actual_subsets_are_approximately_balanced(std::string& warning_message) const = 0;
343 
345 
354  virtual double actual_compute_objective_function_without_penalty(const TargetT& current_estimate, const int subset_num) = 0;
355 
357 
369  virtual Succeeded actual_add_multiplication_with_approximate_sub_Hessian_without_penalty(TargetT& output,
370  const TargetT& input,
371  const int subset_num) const;
372 
374 
386  virtual Succeeded actual_accumulate_sub_Hessian_times_input_without_penalty(TargetT& output,
387  const TargetT& current_image_estimate,
388  const TargetT& input,
389  const int subset_num) const;
390 };
391 END_NAMESPACE_STIR
392 
393 #endif
A base class for &#39;generalised&#39; objective functions, i.e. objective functions for which at least a &#39;gr...
Definition: GeneralisedObjectiveFunction.h:83
declaration of stir::ExamData
Declaration of class stir::ParsingObject.
Import of std::shared_ptr, std::dynamic_pointer_cast and std::static_pointer_cast (or corresponding b...
Declaration of class stir::ProjData.
virtual void fill_nonidentifiable_target_parameters(TargetT &target, const float value) const
Fill any elements that we cannot estimate with a fixed value.
Definition: GeneralisedObjectiveFunction.h:196
Declaration of class stir::BinNormalisation.
Declaration of class stiir::RegisteredObject.
Helper class to provide registry mechanisms to a Base classSuppose you have a hierarchy of classes wi...
Definition: RegisteredObject.h:95
double compute_value(const TargetT &current_estimate)
Alias for compute_objective_function(const TargetT&)
Definition: GeneralisedObjectiveFunction.h:180
Declaration of class stir::GeneralisedPrior.
a class for storing information about 1 exam (or scan)
Definition: ExamInfo.h:41
a class containing an enumeration type that can be used by functions to signal successful operation o...
Definition: Succeeded.h:43
base class for data objects such as ProjData etcProvides an ExamInfo member.
Definition: ExamData.h:33