Composite Profiles

The above profiles can be combined in various ways including sums and convolutions.

Sums of GSObjects

class galsim.Sum(*args, **kwargs)[source]

Bases: GSObject

A class for adding 2 or more GSObject instances.

The Sum class is used to represent the sum of multiple GSObject instances. For example, it might be used to represent a multiple-component galaxy as the sum of an Exponential and a DeVaucouleurs, or to represent a PSF as the sum of multiple Gaussian objects.

Typically, you do not need to construct a Sum object explicitly. Normally, you would just use the + operator, which returns a Sum:

>>> bulge = galsim.Sersic(n=3, half_light_radius=0.8)
>>> disk = galsim.Exponential(half_light_radius=1.4)
>>> gal = bulge + disk
>>> psf = galsim.Gaussian(sigma=0.3, flux=0.3) + galsim.Gaussian(sigma=0.8, flux=0.7)

You can also use the Add() factory function, which returns a Sum object if none of the individual objects are chromatic:

>>> gal = galsim.Add([bulge,disk])

Parameters:

args – Unnamed args should be a list of objects to add.
gsparams – An optional GSParams argument. [default: None]
propagate_gsparams – Whether to propagate gsparams to each of the components. This is normally a good idea, but there may be use cases where one would not want to do this. [default: True]

Note: if gsparams is unspecified (or None), then the Sum instance will use the most restrictive combination of parameters from each of the component objects. Normally, this means the smallest numerical value (e.g. folding_threshold, xvalue_accuracy, etc.), but for a few parameters, the largest numerical value is used. See GSParams.combine for details.

Furthermore, the gsparams used for the Sum (either given explicitly or derived from the components) will normally be applied to each of the components. It doesn’t usually make much sense to apply stricter-than-normal accuracy or threshold values to one component but not another in a Sum, so this ensures that they all have consistent rendering behavior. However, if you want to keep the existing gsparams of the component objects (e.g. because one object is much fainter and can thus use looser accuracy tolerances), then you may set propagate_gsparams=False.

property obj_list: The list of objects being added.

withGSParams(gsparams=None, **kwargs)[source]: Create a version of the current object with the given gsparams

Note

Unless you set propagate_gsparams=False, this method will also update the gsparams of each object being added.

galsim.Add(*args, **kwargs)[source]

A function for adding 2 or more GSObject or ChromaticObject instances.

This function will inspect its input arguments to decide if a Sum object or a ChromaticSum object is required to represent the sum of surface brightness profiles.

Typically, you do not need to call Add() explicitly. Normally, you would just use the + operator, which returns a Sum:

>>> bulge = galsim.Sersic(n=3, half_light_radius=0.8)
>>> disk = galsim.Exponential(half_light_radius=1.4)
>>> gal = bulge + disk
>>> psf = galsim.Gaussian(sigma=0.3, flux=0.3) + galsim.Gaussian(sigma=0.8, flux=0.7)

If one of the items is chromatic, it will return a ChromaticSum:

>>> disk = galsim.Exponential(half_light_radius=1.4) * galsim.SED(sed_file)
>>> gal = bulge + disk

Parameters:

args – Unnamed args should be a list of objects to add.
gsparams – An optional GSParams argument. [default: None]
propagate_gsparams – Whether to propagate gsparams to each of the components. This is normally a good idea, but there may be use cases where one would not want to do this. [default: True]

Returns:

a Sum or ChromaticSum instance as appropriate.

Convolutions of GSObjects

class galsim.Convolution(*args, **kwargs)[source]

Bases: GSObject

A class for convolving 2 or more GSObject instances.

The convolution will normally be done using discrete Fourier transforms of each of the component profiles, multiplying them together, and then transforming back to real space.

There is also an option to do the convolution as integrals in real space. To do this, use the optional keyword argument `real_space = True. Currently, the real-space integration is only enabled for convolving 2 profiles. (Aside from the trivial implementaion for 1 profile.) If you try to use it for more than 2 profiles, an exception will be raised.

The real-space convolution is normally slower than the DFT convolution. The exception is if both component profiles have hard edges, e.g. a truncated Moffat or Sersic with a Pixel. In that case, the highest frequency maxk for each component is quite large since the ringing dies off fairly slowly. So it can be quicker to use real-space convolution instead. Also, real-space convolution tends to be more accurate in this case as well.

If you do not specify either real_space = True or False explicitly, then we check if there are 2 profiles, both of which have hard edges. In this case, we automatically use real-space convolution. In all other cases, the default is not to use real-space convolution.

The normal way to use this class is to use the Convolve() factory function:

>>> gal = galsim.Sersic(n, half_light_radius)
>>> psf = galsim.Gaussian(sigma)
>>> final = galsim.Convolve([gal, psf])

The objects to be convolved may be provided either as multiple unnamed arguments (e.g. Convolve(psf, gal)) or as a list (e.g. Convolve([psf, gal])). Any number of objects may be provided using either syntax. (Well, the list has to include at least 1 item.)

Parameters:

args – Unnamed args should be a list of objects to convolve.
real_space – Whether to use real space convolution. [default: None, which means to automatically decide this according to whether the objects have hard edges.]
gsparams – An optional GSParams argument. [default: None]
propagate_gsparams – Whether to propagate gsparams to each of the components. This is normally a good idea, but there may be use cases where one would not want to do this. [default: True]

Note: if gsparams is unspecified (or None), then the Convolution instance will use the most restrictive combination of parameters from each of the component objects. Normally, this means the smallest numerical value (e.g. folding_threshold, xvalue_accuracy, etc.), but for a few parameters, the largest numerical value is used. See GSParams.combine for details.

Furthermore, the gsparams used for the Convolution (either given explicitly or derived from the components) will normally be applied to each of the components. It doesn’t usually make much sense to apply stricter-than-normal accuracy or threshold values to one component but not another in a Convolution, so this ensures that they all have consistent rendering behavior. However, if you want to keep the existing gsparams of the component objects, then you may set propagate_gsparams=False.

property obj_list: The list of objects being convolved.

property real_space: Whether this Convolution should be drawn using real-space convolution rather than FFT convolution.

withGSParams(gsparams=None, **kwargs)[source]: Create a version of the current object with the given gsparams

Note

Unless you set propagate_gsparams=False, this method will also update the gsparams of each object being convolved.

galsim.Convolve(*args, **kwargs)[source]

A function for convolving 2 or more GSObject or ChromaticObject instances.

This function will inspect its input arguments to decide if a Convolution object or a ChromaticConvolution object is required to represent the convolution of surface brightness profiles.

Parameters:

args – Unnamed args should be a list of objects to convolve.
real_space – Whether to use real space convolution. [default: None, which means to automatically decide this according to whether the objects have hard edges.]
gsparams – An optional GSParams argument. [default: None]
propagate_gsparams – Whether to propagate gsparams to each of the components. This is normally a good idea, but there may be use cases where one would not want to do this. [default: True]

Returns:

a Convolution or ChromaticConvolution instance as appropriate.

class galsim.AutoConvolution(obj, real_space=None, gsparams=None, propagate_gsparams=True)[source]

Bases: Convolution

A special class for convolving a GSObject with itself.

It is equivalent in functionality to Convolve([obj,obj]), but takes advantage of the fact that the two profiles are the same for some efficiency gains.

The normal way to use this class is to use the AutoConvolve() factory function:

>>> psf_sq = galsim.AutoConvolve(psf)

Parameters:

obj – The object to be convolved with itself.
real_space – Whether to use real space convolution. [default: None, which means to automatically decide this according to whether the object has hard edges.]
gsparams – An optional GSParams argument. [default: None]
propagate_gsparams – Whether to propagate gsparams to the auto-convolved object. This is normally a good idea, but there may be use cases where one would not want to do this. [default: True]

property orig_obj: The original object that is being auto-convolved.

property real_space: Whether this Convolution should be drawn using real-space convolution rather than FFT convolution.

withGSParams(gsparams=None, **kwargs)[source]: Create a version of the current object with the given gsparams

Note

Unless you set propagate_gsparams=False, this method will also update the gsparams of the wrapped component object.

galsim.AutoConvolve(obj, real_space=None, gsparams=None, propagate_gsparams=True)[source]

A function for autoconvolving either a GSObject or ChromaticObject.

This function will inspect its input argument to decide if a AutoConvolution object or a ChromaticAutoConvolution object is required to represent the convolution of a surface brightness profile with itself.

Parameters:

obj – The object to be convolved with itself.
real_space – Whether to use real space convolution. [default: None, which means to automatically decide this according to whether the object has hard edges.]
gsparams – An optional GSParams argument. [default: None]
propagate_gsparams – Whether to propagate gsparams to the auto-convolved object. This is normally a good idea, but there may be use cases where one would not want to do this. [default: True]

Returns:

a AutoConvolution or ChromaticAutoConvolution instance as appropriate.

class galsim.AutoCorrelation(obj, real_space=None, gsparams=None, propagate_gsparams=True)[source]

Bases: Convolution

A special class for correlating a GSObject with itself.

It is equivalent in functionality to:

galsim.Convolve([obj,obj.createRotated(180.*galsim.degrees)])

but takes advantage of the fact that the two profiles are the same for some efficiency gains.

This class is primarily targeted for use by the BaseCorrelatedNoise models when convolving with a GSObject.

The normal way to use this class is to use the AutoCorrelate factory function:

>>> psf_sq = galsim.AutoCorrelate(psf)

Parameters:

obj – The object to be convolved with itself.
real_space – Whether to use real space convolution. [default: None, which means to automatically decide this according to whether the object has hard edges.]
gsparams – An optional GSParams argument. [default: None]
propagate_gsparams – Whether to propagate gsparams to the auto-convorrelated object. This is normally a good idea, but there may be use cases where one would not want to do this. [default: True]

property orig_obj: The original object that is being auto-correlated.

property real_space: Whether this Convolution should be drawn using real-space convolution rather than FFT convolution.

withGSParams(gsparams=None, **kwargs)[source]: Create a version of the current object with the given gsparams

Note

Unless you set propagate_gsparams=False, this method will also update the gsparams of the wrapped component object.

galsim.AutoCorrelate(obj, real_space=None, gsparams=None, propagate_gsparams=True)[source]

A function for autocorrelating either a GSObject or ChromaticObject.

This function will inspect its input argument to decide if a AutoCorrelation object or a ChromaticAutoCorrelation object is required to represent the correlation of a surface brightness profile with itself.

Parameters:

obj – The object to be convolved with itself.
real_space – Whether to use real space convolution. [default: None, which means to automatically decide this according to whether the object has hard edges.]
gsparams – An optional GSParams argument. [default: None]
propagate_gsparams – Whether to propagate gsparams to the auto-convorrelated object. This is normally a good idea, but there may be use cases where one would not want to do this. [default: True]

Returns:

an AutoCorrelation or ChromaticAutoCorrelation instance as appropriate.