Gyoto
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | Protected Attributes | Friends | List of all members
Gyoto::Scenery Class Reference

Ray-tracing scene. More...

#include <GyotoScenery.h>

Inheritance diagram for Gyoto::Scenery:
Gyoto::SmartPointee Gyoto::Object

Public Types

enum  mpi_tag {
  give_task, read_scenery, terminate, raytrace,
  raytrace_done, ready, impactcoords, noimpactcoords
}
 Tags that may be sent to communicate with workers using MPI_Send()
 
typedef Gyoto::SmartPointer< Gyoto::SmartPointeeSubcontractor_t(Gyoto::FactoryMessenger *)
 A subcontractor builds an object upon order from the Factory. More...
 

Public Member Functions

void mpiSpawn (int nbchildren)
 Spawn gyoto-mpi-worker processes. More...
 
void mpiTerminate ()
 Terminate gyoto-mpi-worker-processes.
 
void mpiClone ()
 Send a copy of self to the mpi workers. More...
 
void mpiTask (mpi_tag &tag)
 Send a tag to workers.
 
virtual Property const * getProperties () const
 Get list of properties. More...
 
 Scenery ()
 Set everything to defaults.
 
 Scenery (const Scenery &o)
 Copy constructor.
 
Sceneryclone () const
 Cloner.
 
 Scenery (SmartPointer< Metric::Generic >, SmartPointer< Screen >, SmartPointer< Astrobj::Generic >)
 Constructor setting Scenery::gg_, Scenery::screen_, and Scenery::obj_. More...
 
SmartPointer< Metric::Genericmetric () const
 Get ph_.Worldline::metric_.
 
void metric (SmartPointer< Metric::Generic >)
 Set Scenery::gg_. More...
 
SmartPointer< Screenscreen () const
 Get Scenery::screen_.
 
void screen (SmartPointer< Screen >)
 Set Scenery::screen_. More...
 
SmartPointer< Astrobj::Genericastrobj () const
 Get ph_.obj_.
 
void astrobj (SmartPointer< Astrobj::Generic >)
 Set ph_.obj_. More...
 
SmartPointer< PhotonclonePhoton () const
 Clone the internal Photon.
 
SmartPointer< PhotonclonePhoton (size_t i, size_t j)
 Clone the internal Photon.
 
SmartPointer< PhotonclonePhoton (double a, double d)
 Clone the internal Photon.
 
void updatePhoton ()
 Update values in cached Photon.
 
double delta () const
 Get default step in geometrical units.
 
double delta (const std::string &unit) const
 Get default step in specified units.
 
void delta (double)
 set default step in geometrical units
 
void delta (double, const std::string &unit)
 set default step in specified units
 
void initCoord (std::vector< double > c)
 
std::vector< double > initCoord () const
 
void setRequestedQuantities (Quantity_t quant)
 Set Scenery::quantities_. More...
 
void requestedQuantitiesString (std::string const &squant)
 Set Scenery::quantities_ from string. More...
 
Quantity_t getRequestedQuantities () const
 Get Scenery::quantities_.
 
std::string requestedQuantitiesString () const
 Get a string representation of Scenery::quantities_.
 
size_t getScalarQuantitiesCount (Quantity_t *q=NULL) const
 Get number of requested quantities of scalar nature. More...
 
double tMin () const
 Get ph_.tmin_.
 
double tMin (const std::string &unit) const
 Get ph_.tmin_ in specified unit.
 
void tMin (double)
 Set ph_.tmin_.
 
void tMin (double, const std::string &unit)
 Set ph_.tmin_ in specified unit.
 
void adaptive (bool mode)
 Set ph_.adaptive_.
 
bool adaptive () const
 Get ph_.adaptive_.
 
void integrator (std::string type)
 Passed to ph_.
 
std::string integrator () const
 Passed to ph_.
 
double deltaMin () const
 Passed to ph_.
 
void deltaMin (double h1)
 Passed to ph_.
 
double deltaMax () const
 Passed to ph_.
 
void deltaMax (double h1)
 Passed to ph_.
 
double deltaMaxOverR () const
 Passed to ph_.
 
void deltaMaxOverR (double t)
 Passed to ph_.
 
void absTol (double)
 Passed to ph_.
 
double absTol () const
 Passed to ph_.
 
void relTol (double)
 Passed to ph_.
 
double relTol () const
 Passed to ph_.
 
void secondary (bool sec)
 Set ph_.secondary_.
 
bool secondary () const
 Get ph_.secondary_.
 
void maxiter (size_t miter)
 Set ph_.maxiter_.
 
size_t maxiter () const
 Get ph_.maxiter_.
 
void nThreads (size_t)
 Set nthreads_;.
 
size_t nThreads () const
 Get nthreads_;.
 
void nProcesses (size_t)
 Set nprocesses_;.
 
size_t nProcesses () const
 Get nprocesses_;.
 
void intensityConverter (std::string unit)
 Set Scenery::intensity_converter_.
 
void spectrumConverter (std::string unit)
 Set Scenery::spectrum_converter_.
 
void binSpectrumConverter (std::string unit)
 Set Scenery::binspectrum_converter_.
 
void setPropertyConverters (Gyoto::Astrobj::Properties *prop)
 Copy converters to Astrobj::Properties instance. More...
 
void rayTrace (Screen::Coord2dSet &ij, Astrobj::Properties *data, double *impactcoords=NULL)
 Perform ray-tracing. More...
 
void operator() (size_t i, size_t j, Astrobj::Properties *data, double *impactcoords=NULL, Photon *ph=NULL)
 Ray-trace a single pixel in Scenery::screen_. More...
 
void operator() (double alpha, double delta, Astrobj::Properties *data, Photon *ph=NULL)
 Ray-trace single direction. More...
 
void fillProperty (FactoryMessenger *fmp, Property const &p) const
 
void fillElement (FactoryMessenger *fmp) const
 
void incRefCount ()
 Increment the reference counter. Warning: Don't mess with the counter.
 
int decRefCount ()
 Decrement the reference counter and return current value. Warning: Don't mess with the counter.
 
int getRefCount ()
 Get the current number of references.
 
void set (Property const &p, Value val)
 Set Value of a Property.
 
void set (Property const &p, Value val, std::string const &unit)
 Set Value (expressed in unit) of a Property.
 
void set (std::string const &pname, Value val)
 Set Value of a Property.
 
void set (std::string const &pname, Value val, std::string const &unit)
 Set Value (expressed in unit) of a Property.
 
Value get (Property const &p) const
 Get Value of a Property.
 
Value get (std::string const &pname) const
 Get Value of a Property.
 
Value get (Property const &p, std::string const &unit) const
 Get Value of a Property, converted to unit.
 
Value get (std::string const &pname, std::string const &unit) const
 Get Value of a Property, converted to unit.
 
Property const * property (std::string const pname) const
 Find property by name. More...
 
virtual void fillProperty (Gyoto::FactoryMessenger *fmp, Property const &p) const
 Output a single Property to XML. More...
 
virtual void fillElement (Gyoto::FactoryMessenger *fmp) const
 Fill the XML element for this Object. More...
 
virtual void setParameters (Gyoto::FactoryMessenger *fmp)
 Main loop for parsing Properties from XML description. More...
 
virtual int setParameter (std::string name, std::string content, std::string unit)
 Set parameter by name. More...
 
virtual void setParameter (Gyoto::Property const &p, std::string const &name, std::string const &content, std::string const &unit)
 Set parameter by Property (and name) More...
 

Static Public Member Functions

static SmartPointer< ScenerySubcontractor (Gyoto::FactoryMessenger *)
 Instanciate Scenery from an XML description.
 

Public Attributes

boost::mpi::communicator * mpi_team_
 Team of processes for MPI. More...
 
 GYOTO_WORLDLINE
 

Static Public Attributes

static bool am_worker
 True in instance of gyoto-mpi-worker, otherwise false.
 
static GYOTO_OBJECT Property const properties []
 

Protected Attributes

SmartPointer< Screenscreen_
 
double delta_
 
Gyoto::Quantity_t quantities_
 Quantities to compute. More...
 
Gyoto::Photon ph_
 Template Photon. More...
 
size_t nthreads_
 Number of parallel threads to use in rayTrace() More...
 
int nprocesses_
 Number of parallel processes to use in rayTrace()
 
Gyoto::SmartPointer< Gyoto::Units::Converterintensity_converter_
 See Astrobj::Properties::intensity_converter_.
 
Gyoto::SmartPointer< Gyoto::Units::Converterspectrum_converter_
 See Astrobj::Properties::intensity_converter_.
 
Gyoto::SmartPointer< Gyoto::Units::Converterbinspectrum_converter_
 See Astrobj::Properties::intensity_converter_.
 
std::string kind_
 The "kind" that is output in the XML entity. More...
 

Friends

class Gyoto::SmartPointer< Gyoto::Scenery >
 

Detailed Description

Ray-tracing scene.

An Scenery contains:

In addition, Quantities may be specified (or the default Quantity will be produced: generally Intensity). Not all Astrobj implement all Quantities. The order in which Quantities are listed is not relevant (it is not stored). Possible Quantities:

In addition, it is possible to ray-trace an image using several cores on a single machine (if Gyoto has been compiled with POSIX threads support). The number of threads can be specified using NThreads entity. Setting NThreads to 0 is equivalent to setting it to 1. Beware that setting NThreads to a number higher than the actual number of cores available on the machine usually leads to a decrease in performance.

Finally, Scenery accepts a number of numerical tuning parameters that are passed directly to the underlying photons (actually, the Scenery object holds a Photon instance which stores many parameters, including the Metric and Astrobj): Adaptive/NonAdaptive, Delta, MinimumTime, MaxIter, PrimaryOnly.

Thus a fully populated Scenery XML looks like that (the values are examples, they are not necessary the default nor the best or even good values):

<?xml version="1.0" encoding="UTF-8"
standalone="no"?> <Scenery>
<Metric kind = "MetricKind">
<MetricProperties/>
</Metric>
<Screen>
<ScreenProperties/>
</Screen>
<Astrobj kind = "AstrobjKind">
<AstrobjParameters/>
</Astrobj>
<Quantities> Spectrum Intensity ...</Quantities>
<NThreads> 2 </NThreads>
Next come the numerical tuning parameters:
Integration step, initial in case of adaptive, reset for
for each ray being traced:
<Delta unit="geometrical"> 1 </Delta>
Adaptive or NonAdaptive:
<Adaptive/>
The integrator to use for integrating the photons:
<Integrator>runge_kutta_fehlberg78</Integrator>
The "Legacy" integrator is coded in
Metric::Generic::myrk4_adaptive(), may be re-implemented in othe
metrics, and therefore takes its tuning parameters in the Metric
section. The other integrators (runge_kutta_fehlberg78,
runge_kutta_cash_karp54, runge_kutta_dopri5,
runge_kutta_cash_karp54_classic) accept the following tuning
parameters, directly in the Scenery section:
Absolute and relative tolerance for the adaptive step:
<AbsTol>1e-11</AbsTol>
<RelTol>1e-11</RelTol>
Normally, you should not need to tune the other three. If you need
to, try using a higher order integrator:
maximum integration step:
<DeltaMax> 100 </DeltaMax>
delta_max/R where R is the current distance to the origin:
<DeltaMaxOverR> 0.1 </DeltaMaxOverR>
minimum step:
<DeltaMin>1e-20</DeltaMin>
A few safe-guards to avoid infinite loops:
Maximum number of iterations for each ray:
<Maxiter> 1000000 </Maxiter>
Minimum date a photon may reach backwards in time:
<MinimumTime unit="yr">25e3</MinimumTime>
This one is an experimental, poorly specified feature:
<!--PrimaryOnly/-->

Member Typedef Documentation

typedef Gyoto::SmartPointer<Gyoto::SmartPointee> Gyoto::SmartPointee::Subcontractor_t(Gyoto::FactoryMessenger *)
inherited

A subcontractor builds an object upon order from the Factory.

Various classes need to provide a subcontractor to be able to instanciate themselves upon order from the Factory. A subcontractor is a function (often a static member function) which accepts a pointer to a FactoryMessenger as unique parameter, communicates with the Factory using this messenger to read an XML description of the object to build, and returns this objet. SmartPointee::Subcontractor_t* is just generic enough a typedef to cast to and from other subcontractor types: Astrobj::Subcontractor_t, Metric::Subcontractor_t, Spectrum::Subcontractor_t. A subcontractor needs to be registered using the relevant Register() function: Astrobj::Register(), Metric::Register(), Spectrum::Register().

Constructor & Destructor Documentation

Gyoto::Scenery::Scenery ( SmartPointer< Metric::Generic ,
SmartPointer< Screen ,
SmartPointer< Astrobj::Generic  
)

Constructor setting Scenery::gg_, Scenery::screen_, and Scenery::obj_.

To ensure consistency, the Metric will be forcibly attached to the Screen and to the Astrobj (if they are not NULL).

Member Function Documentation

void Gyoto::Scenery::astrobj ( SmartPointer< Astrobj::Generic )

Set ph_.obj_.

The Metric attached to the Scenery will be attached to the Astrobj

virtual void Gyoto::Object::fillElement ( Gyoto::FactoryMessenger *  fmp) const
virtualinherited

Fill the XML element for this Object.

The base implementation simply calls fillProperty() for each Property defined for the Object.

Derived classes should avoid overriding fillElement(). It may make sense occasionally, e.g. to make sure that the metric is output first.

To customize how a given Property is rendered, it is better to override fillProperty().

If this method is overridden, the implementation should in general call fillElement() on the direct base.

virtual void Gyoto::Object::fillProperty ( Gyoto::FactoryMessenger *  fmp,
Property const &  p 
) const
virtualinherited

Output a single Property to XML.

The base implementation decides what to do based on the p.type. The format matches how setParameters() an setParameter() would interpret the XML descition.

Overriding this method should be avoided, but makes sense in some cases (for instance Screen::fillProperty() selects a different unit for Distance based on its magnitude, so that stellar sizes are expressed in solar radii while smaller sizes can be expressed in meters and larger sizes in parsecs).

Overriding implementation should fall-back on calling the implementation in the direct parent class:

class A: public Object {};
class B: public A {
using B::setParameter;
virtual void fillProperty(Gyoto::FactoryMessenger *fmp,
Property const &p) const ;
};
void B::fillProperty(Gyoto::FactoryMessenger *fmp,
Property const &p) const {
if (name=="Duff") fmp->doSomething();
else A::fillProperty(fmp, p);
}

Reimplemented in Gyoto::Screen, Gyoto::Astrobj::Star, Gyoto::Spectrometer::Uniform, Gyoto::Astrobj::Disk3D, Gyoto::Astrobj::PatternDisk, Gyoto::Astrobj::PolishDoughnut, and Gyoto::Astrobj::DirectionalDisk.

virtual Property const* Gyoto::Scenery::getProperties ( ) const
virtual

Get list of properties.

This method is declared automatically by the GYOTO_OBJECT macro and defined automatically by the GYOTO_PROPERTY_END macro.

Reimplemented from Gyoto::Object.

size_t Gyoto::Scenery::getScalarQuantitiesCount ( Quantity_t q = NULL) const

Get number of requested quantities of scalar nature.

This is all quantities except Spectrum, BinSpectrum and ImpactCoords.

void Gyoto::Scenery::metric ( SmartPointer< Metric::Generic )

Set Scenery::gg_.

The provided Metric will also be atached to the Screen and the Astrobj.

void Gyoto::Scenery::mpiClone ( )

Send a copy of self to the mpi workers.

Always call mpiClone() before ray-tracing if workers are running.

void Gyoto::Scenery::mpiSpawn ( int  nbchildren)

Spawn gyoto-mpi-worker processes.

Also sets nprocesses_. If the right number of workers is already running, does nothing. Also does nothing if MPI_Init() has not been called yet.

void Gyoto::Scenery::operator() ( size_t  i,
size_t  j,
Astrobj::Properties data,
double *  impactcoords = NULL,
Photon ph = NULL 
)

Ray-trace a single pixel in Scenery::screen_.

Almost identical to rayTrace(), but for a single pixel.

If ph is passed, it is assumed to have been properly initialized (with the right metric and astrobj etc.) already. Else, use &Scenery::ph_.

void Gyoto::Scenery::operator() ( double  alpha,
double  delta,
Astrobj::Properties data,
Photon ph = NULL 
)

Ray-trace single direction.

Almost identical to rayTrace(), but for a single direction.

If ph is passed, it is assumed to have been properly initialized (with the right metric and astrobj etc.) already. Else, use &Scenery::ph_.

Property const* Gyoto::Object::property ( std::string const  pname) const
inherited

Find property by name.

Look into the Property list for a Property whose name (or name_false, for a boolean Property) is pname. Return a const pointer to the first such property found, or NULL if none is found.

void Gyoto::Scenery::rayTrace ( Screen::Coord2dSet ij,
Astrobj::Properties data,
double *  impactcoords = NULL 
)

Perform ray-tracing.

For each directions specified, launch a Photon back in time to compute the various quantities.

At this time, the computed quantities depend on on the pointers in *data which are not NULL.

rayTrace() uses

data must have been instanciated prior to calling rayTrace and the various pointers in *data must be NULL or point to the first cell in an array of size at least Screen::npix_ squared.

If MPI support is built-in, MPI_Init() has been called, and nprocesses_ is ≥1, then rayTrace() will use several processes, launching them using mpiSpawn() if necessary.

Else, if Scenery::nthreads_ is ≥2 and Gyoto has been compiled with pthreads support, rayTrace() will use Scenery::nthreads_ threads and launch photons in parallel. This works only if the Astrobj::Generic::clone() and Metric::Generic::clone() methods have been properly implemented for the specific astrobj and metric kind, and if they are both thread-safe. At the moment, unfortunately, Lorene metrics are known to not be thread-safe.

Parameters
[in]ijScreen::Coord2dSet specification of rays to trace. e.g.:
Screen::Range irange(imin, imax, di);
Screen::Range jrange(jmin, jmax, dj);
Screen::Grid ij(irange, jrange);
Parameters
[in,out]dataPointer to a preallocated Astrobj::Properties instance which sets which quantities must be computed and where to store the output.
[in]impactcoordsOptional pointer to an array of pre-computed impact coordinates. If impactcoords is provided, rayTracing is skipped and the quantities in *data are fill assuming that the impact coordinates are correct. This only makes sense in optically thick mode, when ray-tracing several sceneries for which the shape of the object is identical but their emission distributions are not. impactcoords can be computed using the ImpactCoords quantity.
void Gyoto::Scenery::requestedQuantitiesString ( std::string const &  squant)

Set Scenery::quantities_ from string.

Parameters
squantComa-separated list of quantities, e.g. "Spectrum MinDistance". The order is not relevant.
void Gyoto::Scenery::screen ( SmartPointer< Screen )

Set Scenery::screen_.

The Metric attached to the Scenery will be attached to the Screen

virtual int Gyoto::Object::setParameter ( std::string  name,
std::string  content,
std::string  unit 
)
virtualinherited

Set parameter by name.

This function is used when parsing an XML description, if no Property of this name is found. Overriding implementation should fall-back on calling the direct's parent implementation:

class A: public Object {};
class B: public A {
using B::setParameter;
virtual int setParameter(std::string name,
std::string content,
std::string unit);
};
int B::setParameter(std::string name,
std::string content,
std::string unit) {
if (name=="Duff") doSomething(content, unit);
else return A::setParameter(name, content, unit);
return 0; // name was known
}
Parameters
nameXML name of the parameter (XML entity). This may have a path component, e.g. "Astrobj::Radius", in which case a property named "Astrobj" will be sought in the current object, and setParameter will be called recusrively on this Astrobj with Radius as name.
contentstring representation of the value
unitstring representation of the unit
Returns
0 if this parameter is known, 1 if it is not.

Reimplemented in Gyoto::Astrobj::Star, and Gyoto::Metric::RotStar3_1.

virtual void Gyoto::Object::setParameter ( Gyoto::Property const &  p,
std::string const &  name,
std::string const &  content,
std::string const &  unit 
)
virtualinherited

Set parameter by Property (and name)

This function is used when parsing an XML description, if Property (p) of this name is found (i.e. either p.name or p.name_false is equal to name). Implementation should fall-back on calling the direct's parent implementation:

class A: public Object {};
class B: public A {
using B::setParameter;
virtual void setParameter(Gyoto::Property const &p,
std::string name,
std::string content,
std::string unit);
};
void B::setParameter(Gyoto::Property const &p,
std::string name,
std::string content,
std::string unit) {
if (name=="Duff") doSomething(content, unit);
else A::setParameter(p, name, content, unit);
}
Parameters
pProperty that matches name (p.name == name or p.name_false == name)
nameXML name of the parameter (XML entity)
contentstring representation of the value
unitstring representation of the unit

Reimplemented in Gyoto::Astrobj::PolishDoughnut.

virtual void Gyoto::Object::setParameters ( Gyoto::FactoryMessenger *  fmp)
virtualinherited

Main loop for parsing Properties from XML description.

This function queries the FactoryMessenger for elements to parse, and tries to matche each element to a Property to set it accordingly.

Any class that tries to be buildable from XML must supply a subcontractor (for base classes such as Metric, Astrobj, Spectrum and Spectrometer, it is done as a template that must be specialized for each class).

This subcontractor typically looks somewhat like this:

SmartPointer<Metric::Generic>
Gyoto::Metric::MyKind::Subcontractor(FactoryMessenger* fmp) {
SmartPointer<MyKind> gg = new MyKind();
gg -> setParameters(fmp);
return gg;
}
 Although this is discouraged, it is possible to override the
 following functions to customize how XML entities are parsed:
   - setParameters() if low-level access to the
     FactoryMessenger is required;
   - setParameter(std::string name,
                  std::string content,
                  std::string unit)
     to interpret an entity that does not match a Property
     (e.g. alternative name);
   - setParameter(Gyoto::Property const &p,
                  std::string const &name,
                  std::string const &content,
                  std::string const &unit)
     to change how a Property is interpreted.
void Gyoto::Scenery::setPropertyConverters ( Gyoto::Astrobj::Properties prop)

Copy converters to Astrobj::Properties instance.

Copy Scenery::intensity_converter_, Scenery::spectrum_converter_ and Scenery::binspectrum_converter_ to there alter ego in *prop.

void Gyoto::Scenery::setRequestedQuantities ( Quantity_t  quant)

Set Scenery::quantities_.

Parameters
quantBitwise OR of desired quantities, e.g.

Member Data Documentation

double Gyoto::Scenery::delta_
protected

Default integration step for the photons

std::string Gyoto::Object::kind_
protectedinherited

The "kind" that is output in the XML entity.

E.g. for an Astrobj, fillElement() will ensure

<Astrobj kind="kind_">...</Astrobj>

is written.

boost::mpi::communicator* Gyoto::Scenery::mpi_team_

Team of processes for MPI.

Rank 0 is the manager, other ranks are workers, instances of the gyoto-mpi-worker executable.

size_t Gyoto::Scenery::nthreads_
protected

Number of parallel threads to use in rayTrace()

When compiled with libpthread, Scenery::rayTrace() may compute several points of the image in parallel threads. This is the number of threads to use.

Gyoto::Photon Gyoto::Scenery::ph_
protected

Template Photon.

Used internally to not always reallocate memory when operator() is called and to store all the parameters which affect the integration, except delta_.

Gyoto::Quantity_t Gyoto::Scenery::quantities_
protected

Quantities to compute.

Bitwise OR of quantities that will be computed, for instance:

SmartPointer<Screen> Gyoto::Scenery::screen_
protected

Screen, the camera for this scenery.


The documentation for this class was generated from the following file: