GyotoPython.h File Reference

Extending Gyoto using Python. More...

#include <GyotoSpectrum.h>
#include <GyotoMetric.h>
#include <GyotoStandardAstrobj.h>
#include <GyotoThinDisk.h>
#include <Python.h>

Go to the source code of this file.

Classes
class	Gyoto::Python::Base
	Base class for classes in the Python plug-in. More...
class	Gyoto::Spectrum::Python
	Loader for Python classes implementing the Spectrum interface. More...
class	Gyoto::Metric::Python
	Metric coded in Python. More...
class	Gyoto::Astrobj::Python::Standard
	Coding a Gyoto::Astrobj::Standard in Python. More...
class	Gyoto::Astrobj::Python::ThinDisk
	Coding a Gyoto::Astrobj::ThinDisk in Python. More...

Namespaces
namespace	Gyoto
	Namespace for the Gyoto library.
namespace	Gyoto::Python
	Helpers for the classes deriving from Gyoto::Python::Base.
namespace	Gyoto::Spectrum
	Spectrum of a simple object (e.g. a Gyoto::Astrobj::Star)
namespace	Gyoto::Metric
	Access to metrics.
namespace	Gyoto::Astrobj
	Access to astronomical objects.
namespace	Gyoto::Astrobj::Python
	Classes that wrap Python classes as Gyoto Astrobj implementations.

Functions
PyObject *	Gyoto::Python::PyInstance_GetMethod (PyObject *pInstance, const char *name)
	Return new reference to method, or NULL if method not found.
PyObject *	Gyoto::Python::PyImport_Gyoto ()
	Return refernce to the gyoto module, or NULL.
void	Gyoto::Python::PyInstance_SetThis (PyObject *pInstance, PyObject *pNew, void *ptr)
	Set "this" attribute in instance.
bool	Gyoto::Python::PyCallable_HasVarArg (PyObject *pMethod)
	Check whether method accepts the varargs argument.
PyObject *	Gyoto::Python::PyModule_NewFromPythonCode (const char *code)
	Create module from Python source code in a C string.
PyObject *	Gyoto::Python::pGyotoSpectrum ()
	Get reference to the Spectrum constructor in the gyoto Python extension.
PyObject *	Gyoto::Python::pGyotoMetric ()
	Get reference to the Metric constructor in the gyoto Python extension.
PyObject *	Gyoto::Python::pGyotoStandardAstrobj ()
	Get reference to the StandardAstrobj constructor in the gyoto Python extension.
PyObject *	Gyoto::Python::pGyotoThinDisk ()
	Get reference to the ThinDisk constructor in the gyoto Python extension.

Detailed Description

Extending Gyoto using Python.

The classes provided here allow implementing a Spectrum, an Astrobj or a Metric in Python. Together, they form the "python" Gyoto plug-in.

This is complementary to, but distinct from the "gyoto" Python extension. Here, we are embedding Python inside Gyoto so that a few functions are coded in Python. The Python extension does the reverse: it allows calling Gyoto functions from within Python. Beware of the vocabulary: here, we call "plug-in" a shared library that extends Gyoto, and "extension" a shared library that extends Python.

The plug-in works within the gyoto command-line utility as well as when Gyoto is used inside Python or inside Yorick. The only caveat is that the python plug-in of Gyoto should not be loaded into a Python interpreter different from the one that was used for building the plug-in.

For this reason, the name of this plug-in depends on the Python interpreter that was used when building. It can be simply "python", or a be versionned: for instance "python2.7" or "python3.4". This way, it is possible to keep several copies of the plug-in, one for each version of the Python interpreter that are installed on the machine. Any version can be used in the gyoto command-line utility or in Yorick, but when Gyoto is used inside Python, only the matching version of this plug-in may be used.

Implementing a Spectrum, Astrobj or Metric kind in Python is much easier than implementing a new C++ plug-in for Gyoto. This saves in development time. However, there is a cost in terms of computing time. While this cost may not be noticeable for Spectra and is moderate for Astrobjs (at least for simple ones), it is quite significant for Metrics, because the gmunu and christoffel methods are evaluated several times per integration step, for every photon. On one example using the Minkowski Metric, the integration of a full image with the Python implementation took approx. 150-200 more time than the same integration with the C++ implementation. So, for Metrics, the Python implementation can serve as a prototyping test-bed, but most users will probably still want to re-implement their Metrics in C++ eventually.

Note also that multi-threading is not very efficient for the Metric::Python class, because only one thread may interact with the Python interpreter at any time. MPI multi-processing runs much faster. Here again, this limitation is less problematic for Spectra and Astrobjs than it is for Metrics.

The principle of these classes is very simple: the plugin embeds a Python interpreter. Each instance of the Gyoto classes Gyoto::Metric::Python, Gyoto::Spectrum::Python, Gyoto::Astrobj:Python::Standard and Gyoto::Astrobj::Python::ThinDisk instantiate a Python class in this interpreter, and delegate certain methods from the Gyoto API to this instance.

In simple cases, the Python instance does not even need to know that it is running in Gyoto. It simply exposes an interface that is being called. However, Gyoto sets a few attributes in each method. Most notably, if the "gyoto" python extension is available, Gyoto will the the attribute "this" to the C++ instance that created the Python class instance, so that the Python code can access C++-side information.