Tomographer  v5.4
Tomographer C++ Framework Documentation
tpy Namespace Reference

C++ Classes and Utilities for Python Modules. More...

Classes

struct  FullStatusReport
 Complete status report for multiple tasks running in parallel. More...
 
class  GilProtectedPyLogger
 Logger type that relays to (wraps around) a PyLogger while protecting the call with GIL acquisition. More...
 
class  Histogram
 Histogram class like Tomographer::Histogram, but with NumPy arrays storage. More...
 
class  HistogramWithErrorBars
 A Histogram with real counts and error bars. See Tomographer::HistogramWithErrorBars. More...
 
class  PyFetchedException
 Helper for catching exceptions in a thread and re-raising them. More...
 
class  PyLogger
 Logger providing transparent integration with Python's logging module. More...
 
struct  PyMHWalkerParamsToDict
 C++ utility to convert a Python dictionary of fields into a valid C++ MHWalkerParams object. More...
 
struct  PyMHWalkerParamsToDict< Tomographer::MHWalkerParamsStepSize< StepRealType > >
 Specialization of PyMHWalkerParamsToDict for Tomographer::MHWalkerParamsStepSize. More...
 
struct  PyStatusReportAddWorkerDataFields
 C++ utility to populate the data field of a WorkerStatusReport for a given TaskType. More...
 
struct  PyStatusReportAddWorkerDataFields< Tomographer::MHRWTasks::MHRandomWalkTask< CData, Rng > >
 Add fields to the given dict, from a status report sent in by a Tomographer::MHRWTasks::MHRandomWalkTask. More...
 
class  TomographerCxxError
 Base exception class for errors in the tomographer python module. More...
 
struct  WorkerStatusReport
 Report of the status of a single worker. More...
 

Typedefs

typedef double RealScalar
 Real type for general calculation precisions (density matrix elements, log-likelihood value calculation, etc.)
 
typedef double CountRealType
 Real type for averaged and/or normalized histograms.
 
typedef std::complex< RealScalarComplexScalar
 A shorthand for std::complex<RealScalar>
 
typedef int HistCountIntType
 Integer type used for histogram counts.
 
typedef int IterCountIntType
 Integer type used for iteration counts in the random walk.
 
typedef int TaskCountIntType
 Integer type used for counting the number of tasks.
 
typedef int FreqCountIntType
 Integer type used for counting the number of measurement outcomes.
 
typedef double RealType
 Floating-point type for template arguments – deprecated. More...
 
typedef int CountIntType
 Integer type for template arguments (`long' in case of long random walks) – deprecated. More...
 
typedef Eigen::Matrix< RealScalar, Eigen::Dynamic, 1 > RealVectorType
 Shorthand, a 1-D Eigen::Matrix of RealScalar's.
 
typedef Eigen::Matrix< RealScalar, Eigen::Dynamic, Eigen::Dynamic > RealMatrixType
 Shorthand, a 2-D Eigen::Matrix of RealScalar's.
 
typedef Eigen::Matrix< ComplexScalar, Eigen::Dynamic, 1 > CplxVectorType
 Shorthand, a 1-D Eigen::Matrix of ComplexScalar's.
 
typedef Eigen::Matrix< ComplexScalar, Eigen::Dynamic, Eigen::Dynamic > CplxMatrixType
 Shorthand, a 2-D Eigen::Matrix of ComplexScalar's.
 
typedef Eigen::Matrix< CountIntType, Eigen::Dynamic, 1 > CountIntVectorType
 Shorthand, a 1-D Eigen::Matrix of CountIntType's – deprecated.
 
typedef Tomographer::DenseDM::DMTypes< Eigen::Dynamic, RealScalarDMTypes
 The Tomographer::DenseDM::DMTypes we should use by default, with dynamic sized matrices.
 
typedef Tomographer::DenseDM::IndepMeasLLH< DMTypes, RealScalar, FreqCountIntTypeIndepMeasLLH
 The Tomographer::DenseDM::IndepMeasLLH type we should use by default, with dynamic sized matrices.
 
typedef Eigen::Matrix< FreqCountIntType, Eigen::Dynamic, 1 > FreqCountIntVectorType
 A vector of frequencies (using Eigen::Matrix instead of Eigen::Array as in Tomographer::DenseDM::IndepMeasLLH)
 
typedef Tomographer::DenseDM::ParamX< DMTypesParamX
 A Tomographer::DenseDM::ParamX set with our dynamic-sized types.
 
typedef Tomographer::HistogramParams< RealScalarHistogramParams
 Histogram Params. See Tomographer::HistogramParams. More...
 
typedef Tomographer::MHRWParams< py::object, IterCountIntTypeMHRWParams
 The Tomographer::MHRWParams type exposed to Python (the MHWalkerParam can be represented by any Python object)
 
typedef Tomographer::ValueHistogramWithBinningMHRWStatsCollectorParams< tomo_internal::DummyValueCalculator, HistCountIntType, CountRealType, Eigen::Dynamic, Eigen::Dynamic >::Result ValueHistogramWithBinningMHRWStatsCollectorResult
 Result type of a Tomographer::ValueHistogramWithBinningMHRWStatsCollector, this is basically a combination of a histogram and an error analysis.
 
typedef Tomographer::MHRWTasks::MHRandomWalkTaskResult< py::object, IterCountIntType, py::object > MHRandomWalkTaskResult
 Result type of a Tomographer::MHRWTasks::MHRandomWalkTask with an abstract stats results type. More...
 

Functions

py::module import_tomographer ()
 Import tomographer definitions into other Python modules. More...
 
template<typename CppException >
tomo_internal::ExceptionWithDocstring< CppException > & registerExceptionWithDocstring (py::handle scope, const char *name, PyObject *base=PyExc_Exception, std::string docstring=std::string())
 Helper to register in Python a C++ exception with a docstring. More...
 
template<typename MHWalkerParams >
py::dict pyMHWalkerParamsToDictInvoke (const MHWalkerParams &p)
 Helper for converting any MHWalkerParams into a dictionary, using automatic template parameter deduction.
 
template<typename MHWalkerParams >
MHWalkerParams pyMHWalkerParamsFromPyObj (py::object o)
 Helper for converting any Python object into a given MHWalkerParams.
 
template<typename TaskType , typename IntType = int>
tpy::FullStatusReport preparePyTaskStatusReport (const Tomographer::MultiProc::FullStatusReport< typename TaskType::StatusReportType, IntType > &report)
 Utility to prepare a Python status report (FullStatusReport) from a task's status report. More...
 
template<typename TaskDispatcher >
void setTasksStatusReportPyCallback (TaskDispatcher &tasks, py::object progress_fn, int progress_interval_ms, bool require_gil_acquisition=false)
 Set up status reporting for a task dispatcher, using a Python callback for status reports. More...
 

Detailed Description

C++ Classes and Utilities for Python Modules.

These are mostly C++ typedefs for classes which are exposed to Python, as well as some helpers.

Typedef Documentation

§ CountIntType

typedef int tpy::CountIntType

Integer type for template arguments (`long' in case of long random walks) – deprecated.

Deprecated:
Since Tomographer 5.3, this type is deprecated in favor of the more versatile HistCountIntType, IterCountIntType, TaskCountIntType, and FreqCountIntType.

Definition at line 124 of file common.h.

§ HistogramParams

Histogram Params. See Tomographer::HistogramParams.

Note that we use RealScalar here and not CountRealType – this is the "scalar", i.e., x-axis of this histogram which corresponds to some value of the figure of merit; this is not the counting type.

Definition at line 46 of file pyhistogram.h.

§ MHRandomWalkTaskResult

Result type of a Tomographer::MHRWTasks::MHRandomWalkTask with an abstract stats results type.

The stats result type can be anything which is exposed to Python, via py::object.

Also, the MHWalkerParams is any py::object (typically py::dict), see tpy::MHRWParams.

Definition at line 75 of file pymhrwtasks.h.

§ RealType

typedef double tpy::RealType

Floating-point type for template arguments – deprecated.

Deprecated:
Since Tomographer 5.3, this type is deprecated in favor of the more versatile RealScalar (along with ComplexScalar) and CountRealType.

Definition at line 115 of file common.h.

Function Documentation

§ import_tomographer()

py::module tpy::import_tomographer ( )
inline

Import tomographer definitions into other Python modules.

If you write your own C++/Python module, then make sure you call import_tomographer() towards the beginning of your initialization function. This function also ensures that the same versions of tomographer and of pybind11 are being used between the compiled tomographer module and the available tomographerpy headers.

In particular, this function make sure that the version of the tomographer Python module is exactly the same as the headers which are currently available. Same for pybind11.

Returns
The py::module object representing the tomographer Python module.

Definition at line 152 of file common.h.

§ preparePyTaskStatusReport()

template<typename TaskType , typename IntType = int>
tpy::FullStatusReport tpy::preparePyTaskStatusReport ( const Tomographer::MultiProc::FullStatusReport< typename TaskType::StatusReportType, IntType > &  report)
inline

Utility to prepare a Python status report (FullStatusReport) from a task's status report.

If you write C++ code using a task dispatcher, and would want to provide status reporting to your caller, then consider using the higher-level setTasksStatusReportPyCallback(), which does everything for you, including checking for signals (e.g. keyboard interrupts).

Definition at line 151 of file pymultiproc.h.

§ registerExceptionWithDocstring()

template<typename CppException >
tomo_internal::ExceptionWithDocstring<CppException>& tpy::registerExceptionWithDocstring ( py::handle  scope,
const char *  name,
PyObject *  base = PyExc_Exception,
std::string  docstring = std::string() 
)

Helper to register in Python a C++ exception with a docstring.

(Adapted from "pybind11::register_exception<Type>" in "pybind11/include/pybind11.h" sources.)

Definition at line 93 of file exc.h.

§ setTasksStatusReportPyCallback()

template<typename TaskDispatcher >
void tpy::setTasksStatusReportPyCallback ( TaskDispatcher &  tasks,
py::object  progress_fn,
int  progress_interval_ms,
bool  require_gil_acquisition = false 
)
inline

Set up status reporting for a task dispatcher, using a Python callback for status reports.

Sets up the given task dispatcher tasks to provide status reports every progress_interval_ms milliseconds, by calling the Python callback progress_fn.

Also, when we recieve progress reports, we check for signals (e.g. keyboard interrupts) or other Python exceptions. If such an exception occurred, we interrupt the tasks.

The argument progress_fn can be None, in which case no callback is performed; however we still check for signals including keyboard interrupts and for other Python exceptions.

If require_gil_acquisition is true, then the GIL (Global Interpreter Lock) is acquired before any Python API call. Otherwise, we assume that we already hold the GIL and don't attempt to acquire it.

Definition at line 202 of file pymultiproc.h.