Images and Related Concepts

Image classes

class jax_galsim.Image(*args, **kwargs)

Bases: object

A class for storing image data along with the pixel scale or WCS information

LAX-backend implementation of galsim.image.Image().

🔪 JAX-GalSim - The Sharp Bits 🔪

Contrary to GalSim native Image, this implementation does not support sharing of the underlying array between different Images or views. This is due to the fact that in JAX numpy arrays are immutable, so any operation applied to this Image will create a new jnp.ndarray. Making a view via .view() will raise an error. Instead, use the .copy() method. The Image.subImage() method will return a copy.

Original GalSim Documentation

The Image class encapsulates all the relevant information about an image including a NumPy array for the pixel values, a bounding box, and some kind of WCS that converts between pixel coordinates and world coordinates. The NumPy array may be constructed by the Image class itself, or an existing array can be provided by the user.

This class creates shallow copies unless a deep copy is explicitly requested using the copy method. The main reason for this is that it allows users to work directly with and modify subimages of larger images (for example, to successively draw many galaxies into one large image). For other implications of this convention, see the description of initialization instructions below.

In most applications with images, we will use (x,y) to refer to the coordinates. We adopt the same meaning for these coordinates as most astronomy applications do: ds9, SAOImage, SExtractor, etc. all treat x as the column number and y as the row number. However, this is different from the default convention used by numpy. In numpy, the access is by [row_num,col_num], which means this is really [y,x] in terms of the normal x,y values. Users are typically insulated from this concern by the Image API, but if you access the numpy array directly via the array attribute, you will need to be careful about this difference.

There are 6 data types that the Image can use for the data values. These are numpy.uint16, numpy.uint32, numpy.int16, numpy.int32, numpy.float32, and numpy.float64. If you are constructing a new Image from scratch, the default is numpy.float32, but you can specify one of the other data types.

There are several ways to construct an Image: (Optional arguments are shown with their default values after the = sign.)

Image(ncol, nrow, dtype=numpy.float32, init_value=0, xmin=1, ymin=1, ...)

This constructs a new image, allocating memory for the pixel values according to the number of columns and rows. You can specify the data type as dtype if you want. The default is numpy.float32 if you don’t specify it. You can also optionally provide an initial value for the pixels, which defaults to 0. The optional xmin,ymin allow you to specify the location of the lower-left pixel, which defaults to (1,1). Reminder, with our convention for x,y coordinates described above, ncol is the number of pixels in the x direction, and nrow is the number of pixels in the y direction.

Image(bounds, dtype=numpy.float32, init_value=0, ...)

This constructs a new image, allocating memory for the pixel values according to a given Bounds object. Particularly, the bounds should be a BoundsI instance. You can specify the data type as dtype if you want. The default is numpy.float32 if you don’t specify it. You can also optionally provide an initial value for the pixels, which defaults to 0.

Image(array, xmin=1, ymin=1, make_const=False, copy=False ...)

This views an existing NumPy array as an Image, where updates to either the image or the original array will affect the other one. The data type is taken from array.dtype, which must be one of the allowed types listed above. You can also optionally set the origin xmin, ymin if you want it to be something other than (1,1).

You can also optionally force the Image to be read-only with make_const=True, though if the original NumPy array is modified then the contents of Image.array will change.

If you want to make a copy of the input array, rather than just view the existing array, you can force a copy with:

>>> image = galsim.Image(array, copy=True)

Image(image, dtype=image.dtype, copy=True)

This creates a copy of an Image, possibly changing the type. e.g.:

>>> image_float = galsim.Image(64, 64) # default dtype=numpy.float32
>>> image_double = galsim.Image(image_float, dtype=numpy.float64)

You can see a list of valid values for dtype in galsim.Image.valid_dtypes. Without the dtype argument, this is equivalent to image.copy(), which makes a deep copy. If you want a copy that shares data with the original, see the view method.

If you only want to enforce the image to have a given type and not make a copy if the array is already the correct type, you can use, e.g.:

>>> image_double = galsim.Image(image, dtype=numpy.float64, copy=False)

You can specify the ncol, nrow, bounds, array, or image parameters by keyword argument if you want, or you can pass them as simple arg as shown aboves, and the constructor will figure out what they are.

The other keyword arguments (shown as … above) relate to the conversion between sky coordinates, which is how all the GalSim objects are defined, and the pixel coordinates. There are three options for this:

scale

You can optionally specify a pixel scale to use. This would normally have units arcsec/pixel, but it doesn’t have to be arcsec. If you want to use different units for the physical scale of your galsim objects, then the same unit would be used here.

wcs

A WCS object that provides a non-trivial mapping between sky units and pixel units. The scale parameter is equivalent to wcs=PixelScale(scale). But there are a number of more complicated options. See the WCS class for more details.

None

If you do not provide either of the above, then the conversion is undefined. When drawing onto such an image, a suitable pixel scale will be automatically set according to the Nyquist scale of the object being drawn.

After construction, you can set or change the scale or wcs with:

>>> image.scale = new_scale
>>> image.wcs = new_wcs

Note that image.scale will only work if the WCS is a PixelScale. Once you set the wcs to be something non-trivial, then you must interact with it via the wcs attribute. The image.scale syntax will raise an exception.

There are also two read-only attributes:

>>> image.bounds
>>> image.array

The array attribute is a NumPy array of the Image’s pixels. The individual elements in the array attribute are accessed as image.array[y,x], matching the standard NumPy convention, while the Image class’s own accessor uses either (x,y) or [x,y].

That is, the following are equivalent:

>>> ixy = image(x,y)
>>> ixy = image[x,y]
>>> ixy = image.array[y,x]
>>> ixy = image.getValue(x,y)

Similarly, for setting individual pixel values, the following are equivalent:

>>> image[x,y] = new_ixy
>>> image.array[y,x] = new_ixy
>>> image.setValue(x,y,new_ixy)

valid_dtypes = [<class 'jax.numpy.int32'>, <class 'jax.numpy.float64'>, <class 'jax.numpy.uint16'>, <class 'jax.numpy.uint32'>, <class 'jax.numpy.int16'>, <class 'jax.numpy.float32'>, <class 'jax.numpy.complex64'>, <class 'jax.numpy.complex128'>]

property dtype

The dtype of the underlying numpy array.

LAX-backend implementation of dtype().

property bounds

The bounds of the Image.

LAX-backend implementation of bounds().

property array

The underlying numpy array.

LAX-backend implementation of array().

property nrow

The number of rows in the image

LAX-backend implementation of nrow().

property ncol

The number of columns in the image

LAX-backend implementation of ncol().

property isconst

Whether the Image is constant. I.e. modifying its values is an error.

LAX-backend implementation of isconst().

property iscomplex

Whether the Image values are complex.

LAX-backend implementation of iscomplex().

property isinteger

Whether the Image values are integral.

LAX-backend implementation of isinteger().

property iscontiguous

Indicates whether each row of the image is contiguous in memory.

LAX-backend implementation of iscontiguous().

🔪 JAX-GalSim - The Sharp Bits 🔪

In JAX all arrays are contiguous.

Original GalSim Documentation

Note: it is ok for the end of one row to not be contiguous with the start of the next row. This just checks that each individual row has a stride of 1.

property scale

The pixel scale of the Image. Only valid if the wcs is a PixelScale.

LAX-backend implementation of scale().

Original GalSim Documentation

If the WCS is either not set (i.e. it is None) or it is a PixelScale, then it is permissible to change the scale with:

>>> image.scale = new_pixel_scale

property xmin

Alias for self.bounds.xmin.

LAX-backend implementation of xmin().

property xmax

Alias for self.bounds.xmax.

LAX-backend implementation of xmax().

property ymin

Alias for self.bounds.ymin.

LAX-backend implementation of ymin().

property ymax

Alias for self.bounds.ymax.

LAX-backend implementation of ymax().

property outer_bounds

The bounds of the outer edge of the pixels.

LAX-backend implementation of outer_bounds().

Original GalSim Documentation

Equivalent to galsim.BoundsD(im.xmin-0.5, im.xmax+0.5, im.ymin-0.5, im.ymax+0.5)

property real

Return the real part of an image.

LAX-backend implementation of real().

Original GalSim Documentation

This is a property, not a function. So write im.real, not im.real().

This works for real or complex. For real images, it acts the same as view.

property imag

Return the imaginary part of an image.

LAX-backend implementation of imag().

Original GalSim Documentation

This is a property, not a function. So write im.imag, not im.imag().

This works for real or complex. For real images, the returned array is read-only and all elements are 0.

property conjugate

Return the complex conjugate of an image.

LAX-backend implementation of conjugate().

Original GalSim Documentation

This works for real or complex. For real images, it acts the same as view.

Note that for complex images, this is not a conjugate view into the original image. So changing the original image does not change the conjugate (or vice versa).

copy(scale=None, wcs=None, origin=None, center=None, dtype=None, make_const=False, contiguous=False)

Make a copy of the Image

LAX-backend implementation of galsim.image.copy().

🔪 JAX-GalSim - The Sharp Bits 🔪

JAX-GalSim supports extra keyword arguments to .copy so that users can make copies of images while also changing the image properties (e.g., the wcs). The extra keywords behave exactly like those of Image.view.

get_pixel_centers()

A convenience function to get the x and y values at the centers of the image pixels.

LAX-backend implementation of galsim.image.get_pixel_centers().

Original GalSim Documentation

Returns:

(x, y), each of which is a numpy array the same shape as self.array

resize(bounds, wcs=None)

Resize the image to have a new bounds (must be a BoundsI instance)

LAX-backend implementation of galsim.image.resize().

Parameters:

• bounds – The new bounds to resize to.

• wcs – If provided, also update the wcs to the given value. [default: None, which means keep the existing wcs]

Original GalSim Documentation

Note that the resized image will have uninitialized data. If you want to preserve the existing data values, you should either use subImage (if you want a smaller portion of the current Image) or make a new Image and copy over the current values into a portion of the new image (if you are resizing to a larger Image).

subImage(bounds)

Return a view of a portion of the full image

LAX-backend implementation of galsim.image.subImage().

Original GalSim Documentation

This is equivalent to self[bounds]

setSubImage(bounds, rhs)

Set a portion of the full image to the values in another image

LAX-backend implementation of galsim.image.setSubImage().

Original GalSim Documentation

This is equivalent to self[bounds] = rhs

wrap(bounds, hermitian=False)

Wrap the values in a image onto a given subimage and return the subimage.

LAX-backend implementation of galsim.image.wrap().

Parameters:

• bounds – The bounds of the subimage onto which to wrap the full image.

• hermitian – Whether the image is implicitly Hermitian and if so, whether it is the x or y values that are not stored. [default: False]

Original GalSim Documentation

This would typically be used on a k-space image where you initially draw a larger image than you want for the FFT and then wrap it onto a smaller subset. This will cause aliasing of course, but this is often preferable to just using the smaller image without wrapping.

For complex images of FFTs, one often only stores half the image plane with the implicit understanding that the function is Hermitian, so im(-x,-y) == im(x,y).conjugate(). In this case, the wrapping needs to work slightly differently, so you can specify that your image is implicitly Hermitian with the hermitian argument. Options are:

hermitian=False

(default) Normal non-Hermitian image.

hermitian=’x’

Only x>=0 values are stored with x<0 values being implicitly Hermitian. In this case im.bounds.xmin and bounds.xmin must be 0.

hermitian=’y’

Only y>=0 values are stored with y<0 values being implicitly Hermitian. In this case im.bounds.ymin and bounds.ymin must be 0.

Also, in the two Hermitian cases, the direction that is not implicitly Hermitian must be symmetric in the image’s bounds. The wrap bounds must be almost symmetric, but missing the most negative value. For example,:

>>> N = 100
>>> im_full = galsim.ImageCD(bounds=galsim.BoundsI(0,N/2,-N/2,N/2), scale=dk)
>>> # ... fill with im[i,j] = FT(kx=i*dk, ky=j*dk)
>>> N2 = 64
>>> im_wrap = im_full.wrap(galsim.BoundsI(0,N/2,-N2/2,N2/2-1, hermitian='x')

This sets up im_wrap to be the properly Hermitian version of the data appropriate for passing to an FFT.

Note that this routine modifies the original image (and not just the subimage onto which it is wrapped), so if you want to keep the original pristine, you should call wrapped_image = image.copy().wrap(bounds).

Returns:

the subimage, image[bounds], after doing the wrapping.

calculate_fft()

Performs an FFT of an Image in real space to produce a k-space Image.

LAX-backend implementation of galsim.image.calculate_fft().

🔪 JAX-GalSim - The Sharp Bits 🔪

JAX-GalSim does not support forward FFTs of complex dtypes.

Original GalSim Documentation

Note: the image will be padded with zeros as needed to make an image with bounds that look like BoundsI(-N/2, N/2-1, -N/2, N/2-1).

The input image must have a PixelScale wcs. The output image will be complex (an ImageCF or ImageCD instance) and its scale will be 2pi / (N dx), where dx is the scale of the input image.

Returns:

an Image instance with the k-space image.

calculate_inverse_fft()

Performs an inverse FFT of an Image in k-space to produce a real-space Image.

LAX-backend implementation of galsim.image.calculate_inverse_fft().

Original GalSim Documentation

The starting image is typically an ImageCD, although if the Fourier function is real valued, then you could get away with using an ImageD or ImageF.

The image is assumed to be Hermitian. In fact, only the portion with x >= 0 needs to be defined, with f(-x,-y) taken to be conj(f(x,y)).

Note: the k-space image will be padded with zeros and/or wrapped as needed to make an image with bounds that look like BoundsI(0, N/2, -N/2, N/2-1). If you are building a larger k-space image and then wrapping, you should wrap directly into an image of this shape.

The input image must have a PixelScale wcs. The output image will be real (an ImageD instance) and its scale will be 2pi / (N dk), where dk is the scale of the input image.

Returns:

an Image instance with the real-space image.

classmethod good_fft_size(input_size)

Round the given input size up to the next higher power of 2 or 3 times a power of 2.

LAX-backend implementation of galsim.image.good_fft_size().

Original GalSim Documentation

This rounds up to the next higher value that is either 2^k or 3*2^k. If you are going to be performing FFTs on an image, these will tend to be faster at performing the FFT.

copyFrom(rhs)

Copy the contents of another image

LAX-backend implementation of galsim.image.copyFrom().

view(scale=None, wcs=None, origin=None, center=None, dtype=None, make_const=False, contiguous=False)

Make a view of this image, which lets you change the scale, wcs, origin, etc. but view the same underlying data as the original image.

LAX-backend implementation of galsim.image.view().

🔪 JAX-GalSim - The Sharp Bits 🔪

JAX-GalSim does not support image views. This method will raise an error if called.

Parameters:

• scale – If provided, use this as the pixel scale for the image. [default: None]

• wcs – If provided, use this as the wcs for the image. [default: None]

• origin – If provided, use this as the origin position of the view. [default: None]

• center – If provided, use this as the center position of the view. [default: None]

• make_const – Make the view’s data array immutable. [default: False]

• dtype – If provided, ensure that the output has this dtype. If the original Image is a different dtype, then a copy will be made. [default: None]

• contiguous – If provided, ensure that the output array is contiguous. [default: False]

Original GalSim Documentation

If you do not provide either scale or wcs, the view will keep the same wcs as the current Image object.

shift(*args, **kwargs)

Shift the pixel coordinates by some (integral) dx,dy.

LAX-backend implementation of galsim.image.shift().

Original GalSim Documentation

The arguments here may be either (dx, dy) or a PositionI instance. Or you can provide dx, dy as named kwargs.

In terms of columns and rows, dx means a shift in the x value of each column in the array, and dy means a shift in the y value of each row. In other words, the following will return the same value for ixy. The shift function just changes the coordinates (x,y) used for that pixel:

>>> ixy = im(x,y)
>>> im.shift(3,9)
>>> ixy = im(x+3, y+9)

setCenter(*args, **kwargs)

Set the center of the image to the given (integral) (xcen, ycen)

LAX-backend implementation of galsim.image.setCenter().

Original GalSim Documentation

The arguments here may be either (xcen, ycen) or a PositionI instance. Or you can provide xcen, ycen as named kwargs.

In terms of the rows and columns, xcen is the new x value for the central column, and ycen is the new y value of the central row. For even-sized arrays, there is no central column or row, so the convention we adopt in this case is to round up. For example:

>>> im = galsim.Image(numpy.array(range(16),dtype=float).reshape((4,4)))
>>> im(1,1)
0.0
>>> im(4,1)
3.0
>>> im(4,4)
15.0
>>> im(3,3)
10.0
>>> im.setCenter(0,0)
>>> im(0,0)
10.0
>>> im(-2,-2)
0.0
>>> im(1,-2)
3.0
>>> im(1,1)
15.0
>>> im.setCenter(234,456)
>>> im(234,456)
10.0
>>> im.bounds
galsim.BoundsI(xmin=232, xmax=235, ymin=454, ymax=457)

setOrigin(*args, **kwargs)

Set the origin of the image to the given (integral) (x0, y0)

LAX-backend implementation of galsim.image.setOrigin().

Original GalSim Documentation

The arguments here may be either (x0, y0) or a PositionI instance. Or you can provide x0, y0 as named kwargs.

In terms of the rows and columns, x0 is the new x value for the first column, and y0 is the new y value of the first row. For example:

>>> im = galsim.Image(numpy.array(range(16),dtype=float).reshape((4,4)))
>>> im(1,1)
0.0
>>> im(4,1)
3.0
>>> im(1,4)
12.0
>>> im(4,4)
15.0
>>> im.setOrigin(0,0)
>>> im(0,0)
0.0
>>> im(3,0)
3.0
>>> im(0,3)
12.0
>>> im(3,3)
15.0
>>> im.setOrigin(234,456)
>>> im(234,456)
0.0
>>> im.bounds
galsim.BoundsI(xmin=234, xmax=237, ymin=456, ymax=459)

property center

The current nominal center (xcen,ycen) of the image as a PositionI instance.

LAX-backend implementation of center().

Original GalSim Documentation

In terms of the rows and columns, xcen is the x value for the central column, and ycen is the y value of the central row. For even-sized arrays, there is no central column or row, so the convention we adopt in this case is to round up. For example:

>>> im = galsim.Image(numpy.array(range(16),dtype=float).reshape((4,4)))
>>> im.center
galsim.PositionI(x=3, y=3)
>>> im(im.center)
10.0
>>> im.setCenter(56,72)
>>> im.center
galsim.PositionI(x=56, y=72)
>>> im(im.center)
10.0

property true_center

The current true center of the image as a PositionD instance.

LAX-backend implementation of true_center().

Original GalSim Documentation

Unline the nominal center returned by im.center, this value may be half-way between two pixels if the image has an even number of rows or columns. It gives the position (x,y) at the exact center of the image, regardless of whether this is at the center of a pixel (integer value) or halfway between two (half-integer). For example:

>>> im = galsim.Image(numpy.array(range(16),dtype=float).reshape((4,4)))
>>> im.center
galsim.PositionI(x=3, y=3)
>>> im.true_center
galsim.PositionI(x=2.5, y=2.5)
>>> im.setCenter(56,72)
>>> im.center
galsim.PositionI(x=56, y=72)
>>> im.true_center
galsim.PositionD(x=55.5, y=71.5)
>>> im.setOrigin(0,0)
>>> im.true_center
galsim.PositionD(x=1.5, y=1.5)

property origin

Return the origin of the image. i.e. the (x,y) position of the lower-left pixel.

LAX-backend implementation of origin().

Original GalSim Documentation

In terms of the rows and columns, this is the (x,y) coordinate of the first column, and first row of the array. For example:

>>> im = galsim.Image(numpy.array(range(16),dtype=float).reshape((4,4)))
>>> im.origin
galsim.PositionI(x=1, y=1)
>>> im(im.origin)
0.0
>>> im.setOrigin(23,45)
>>> im.origin
galsim.PositionI(x=23, y=45)
>>> im(im.origin)
0.0
>>> im(23,45)
0.0
>>> im.bounds
galsim.BoundsI(xmin=23, xmax=26, ymin=45, ymax=48)

getValue(x, y)

This method is a synonym for im(x,y). It is a bit faster than im(x,y), since GalSim does not have to parse the different options available for __call__. (i.e. im(x,y) or im(pos) or im(x=x,y=y))

LAX-backend implementation of galsim.image.getValue().

Parameters:

• x – The x coordinate of the pixel to get.

• y – The y coordinate of the pixel to get.

setValue(*args, **kwargs)

Set the pixel value at given (x,y) position

LAX-backend implementation of galsim.image.setValue().

Original GalSim Documentation

The arguments here may be either (x, y, value) or (pos, value) where pos is a PositionI. Or you can provide x, y, value as named kwargs.

This is equivalent to self[x,y] = rhs

addValue(*args, **kwargs)

Add some amount to the pixel value at given (x,y) position

LAX-backend implementation of galsim.image.addValue().

Original GalSim Documentation

The arguments here may be either (x, y, value) or (pos, value) where pos is a PositionI. Or you can provide x, y, value as named kwargs.

This is equivalent to self[x,y] += rhs

fill(value)

Set all pixel values to the given value

LAX-backend implementation of galsim.image.fill().

Original GalSim Documentation

Parameter:

value: The value to set all the pixels to.

setZero()

Set all pixel values to zero.

LAX-backend implementation of galsim.image.setZero().

invertSelf()

Set all pixel values to their inverse: x -> 1/x.

LAX-backend implementation of galsim.image.invertSelf().

Original GalSim Documentation

Note: any pixels whose value is 0 originally are ignored. They remain equal to 0 on the output, rather than turning into inf.

replaceNegative(replace_value=0)

Replace any negative values currently in the image with 0 (or some other value).

LAX-backend implementation of galsim.image.replaceNegative().

Parameters:

replace_value – The value with which to replace any negative pixels. [default: 0]

Original GalSim Documentation

Sometimes FFT drawing can result in tiny negative values, which may be undesirable for some purposes. This method replaces those values with 0 or some other value if desired.

transpose()

Return the tranpose of the image.

LAX-backend implementation of galsim.image.transpose().

Original GalSim Documentation

Note: The returned image will have an undefined wcs. If you care about the wcs, you will need to set it yourself.

flip_lr()

Return a version of the image flipped left to right.

LAX-backend implementation of galsim.image.flip_lr().

Original GalSim Documentation

Note: The returned image will have an undefined wcs. If you care about the wcs, you will need to set it yourself.

flip_ud()

Return a version of the image flipped top to bottom.

LAX-backend implementation of galsim.image.flip_ud().

Original GalSim Documentation

Note: The returned image will have an undefined wcs. If you care about the wcs, you will need to set it yourself.

rot_cw()

Return a version of the image rotated 90 degrees clockwise.

LAX-backend implementation of galsim.image.rot_cw().

Original GalSim Documentation

Note: The returned image will have an undefined wcs. If you care about the wcs, you will need to set it yourself.

rot_ccw()

Return a version of the image rotated 90 degrees counter-clockwise.

LAX-backend implementation of galsim.image.rot_ccw().

Original GalSim Documentation

Note: The returned image will have an undefined wcs. If you care about the wcs, you will need to set it yourself.

rot_180()

Return a version of the image rotated 180 degrees.

LAX-backend implementation of galsim.image.rot_180().

Original GalSim Documentation

Note: The returned image will have an undefined wcs. If you care about the wcs, you will need to set it yourself.

tree_flatten()

Flatten the image into a list of values.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation

classmethod from_galsim(galsim_image)

Create a Image from a galsim.Image instance.

to_galsim()

Create a galsim Image from a jax_galsim.Image object.

FindAdaptiveMom(*args, **kwargs)

Measure adaptive moments of an object.

LAX-backend implementation of galsim.hsm.FindAdaptiveMom().

🔪 JAX-GalSim - The Sharp Bits 🔪

This method converts the current jax_galsim.Image to a native galsim.Image and delegates the computation to galsim.hsm.FindAdaptiveMom. The returned object is GalSim’s ShapeData.

Parameters:

• object_image – The Image for the object being measured.

• weight – The optional weight image for the object being measured. Can be an int or a float array. Currently, GalSim does not account for the variation in non-zero weights, i.e., a weight map is converted to an image with 0 and 1 for pixels that are not and are used. Full use of spatial variation in non-zero weights will be included in a future version of the code. [default: None]

• badpix – The optional bad pixel mask for the image being used. Zero should be used for pixels that are good, and any nonzero value indicates a bad pixel. [default: None]

• guess_sig – Optional argument with an initial guess for the Gaussian sigma of the object (in pixels). [default: 5.0]

• precision – The convergence criterion for the moments. [default: 1e-6]

• guess_centroid – An initial guess for the object centroid (useful in case it is not located at the center, which is used if this keyword is not set). The convention for centroids is such that the center of the lower-left pixel is (image.xmin, image.ymin). [default: object_image.true_center]

• strict – Whether to require success. If strict=True, then there will be a GalSimHSMError exception if shear estimation fails. If set to False, then information about failures will be silently stored in the output ShapeData object. [default: True]

• check – Check if the object_image, weight and badpix are in the correct format and valid. [default: True]

• round_moments – Use a circular weight function instead of elliptical. [default: False]

• hsmparams – The hsmparams keyword can be used to change the settings used by FindAdaptiveMom when estimating moments; see HSMParams documentation for more information. [default: None]

• use_sky_coords – Whether to convert the measured moments to sky_coordinates. Setting this to true is equivalent to running applyWCS(object_image.wcs, image_pos=object_image.true_center) on the result. [default: False]

Original GalSim Documentation

This method estimates the best-fit elliptical Gaussian to the object (see Hirata & Seljak 2003 for more discussion of adaptive moments). This elliptical Gaussian is computed iteratively by initially guessing a circular Gaussian that is used as a weight function, computing the weighted moments, recomputing the moments using the result of the previous step as the weight function, and so on until the moments that are measured are the same as those used for the weight function. FindAdaptiveMom can be used either as a free function, or as a method of the Image class.

By default, this routine computes moments in pixel coordinates, which generally use (x,y) for the coordinate variables, so the underlying second moments are Ixx, Iyy, and Ixy. If the WCS is (at least approximately) just a PixelScale, then this scale can be applied to convert the moments’ units from pixels to arcsec. The derived shapes are unaffected by the pixel scale.

However, there is also an option to apply a non-trivial WCS, which may potentially rotate and/or shear the (x,y) moments to the local sky coordinates, which generally use (u,v) for the coordinate variables. These coordinates are measured in arcsec and are oriented such that +v is towards North and +u is towards West. In this case, the returned values are all in arcsec, and are based instead on Iuu, Ivv, and Iuv. To enable this feature, use use_sky_coords=True. See also the method ShapeData.applyWCS for more details.

Note

The application of the WCS implicitly assumes that the WCS is locally uniform across the size of the object being measured. This is normally a very good approximation for most applications of interest.

Like EstimateShear, FindAdaptiveMom works on Image inputs, and fails if the object is small compared to the pixel scale. For more details, see EstimateShear.

Example:

>>> my_gaussian = galsim.Gaussian(flux=1.0, sigma=1.0)
>>> my_gaussian_image = my_gaussian.drawImage(scale=0.2, method='no_pixel')
>>> my_moments = galsim.hsm.FindAdaptiveMom(my_gaussian_image)

or:

>>> my_moments = my_gaussian_image.FindAdaptiveMom()

Assuming a successful measurement, the most relevant pieces of information are my_moments.moments_sigma, which is |det(M)|^(1/4) (= sigma for a circular Gaussian) and my_moments.observed_shape, which is a Shear. In this case, my_moments.moments_sigma is precisely 5.0 (in units of pixels), and my_moments.observed_shape is consistent with zero.

Methods of the Shear class can be used to get the distortion e, the shear g, the conformal shear eta, and so on.

As an example of how to use the optional hsmparams argument, consider cases where the input images have unusual properties, such as being very large. This could occur when measuring the properties of a very over-sampled image such as that generated using:

>>> my_gaussian = galsim.Gaussian(sigma=5.0)
>>> my_gaussian_image = my_gaussian.drawImage(scale=0.01, method='no_pixel')

If the user attempts to measure the moments of this very large image using the standard syntax,

>>> my_moments = my_gaussian_image.FindAdaptiveMom()

then the result will be a GalSimHSMError due to moment measurement failing because the object is so large. While the list of all possible settings that can be changed is accessible in the docstring of the HSMParams class, in this case we need to modify max_amoment which is the maximum value of the moments in units of pixel^2. The following measurement, using the default values for every parameter except for max_amoment, will be successful:

>>> new_params = galsim.hsm.HSMParams(max_amoment=5.0e5)
>>> my_moments = my_gaussian_image.FindAdaptiveMom(hsmparams=new_params)

Returns:

a ShapeData object containing the results of moment measurement.

addNoise(noise)

Add noise to the image according to a supplied noise model.

LAX-backend implementation of galsim.noise.addNoise().

Parameters:

noise – The noise (BaseNoise) model to use.

addNoiseSNR(noise, snr, preserve_flux=False)

Adds noise to the image in a way that achieves the specified signal-to-noise ratio.

LAX-backend implementation of galsim.noise.addNoiseSNR().

Parameters:

• noise – The noise (BaseNoise) model to use.

• snr – The desired signal-to-noise after the noise is applied.

• preserve_flux – Whether to preserve the flux of the object (True) or the variance of the noise model (False) to achieve the desired snr. [default: False]

Original GalSim Documentation

The specified snr (signal-to-noise ratio, or \(S/N\)) can be achieved either by scaling the flux of the object while keeping the noise level fixed, or the flux can be preserved and the noise variance changed. This choice is specified using the parameter preserve_flux, where False means the former and True means the latter.

The definition of \(S/N\) is equivalent to the one used by Great08. We take the signal to be a weighted sum of the pixel values:

\[\begin{split}S &= \frac{\sum W(x,y) I(x,y)}{\sum W(x,y)} \\ N^2 = Var(S) &= \frac{\sum W(x,y)^2 Var(I(x,y))}{(\sum W(x,y))^2}\end{split}\]

and assume that \(Var(I(x,y))\) is constant, \(V \equiv Var(I(x,y))\). We then assume that we are using a matched filter for \(W\), so \(W(x,y) = I(x,y)\). Then a few things cancel and we find that

\[(S/N)^2 = \frac{\sum I(x,y)^2}{V}\]

and therefore, for a given \(I(x,y)\) and \(S/N\) (aka snr)

\[V = \frac{\sum I(x,y)^2}{(S/N)^2}\]

Note

For noise models such as PoissonNoise and CCDNoise, the assumption of constant \(Var(I(x,y))\) is only approximate, since the flux of the object adds to the Poisson noise in those pixels. Thus, the real \(S/N\) on the final image will be slightly lower than the target snr value, and this effect will be larger for brighter objects.

This function relies on BaseNoise.getVariance to determine how much variance the noise model will add. Thus, it will not work for noise models that do not have a well-defined variance, such as VariableGaussianNoise.

Returns:

the variance of the noise that was applied to the image.

write(**kwargs)

Write a single image to a FITS file.

LAX-backend implementation of galsim.fits.write().

Parameters:

• image – The Image to write to file. Per the description of this method, it may be given explicitly via galsim.fits.write(image, ...) or the method may be called directly as an image method, image.write(...). Note that if the image has a ‘header’ attribute containing a FitsHeader, then the FitsHeader is written to the header in the PrimaryHDU, followed by the WCS as usual.

• file_name – The name of the file to write to. [Either file_name or hdu_list is required.]

• dir – Optionally a directory name can be provided if file_name does not already include it. [default: None]

• hdu_list – An astropy.io.fits.HDUList. If this is provided instead of file_name, then the Image is appended to the end of the HDUList as a new HDU. In that case, the user is responsible for calling either hdu_list.writeto(...) or galsim.fits.writeFile(...) afterwards. [Either file_name or hdu_list is required.]

• clobber – Setting clobber=True will silently overwrite existing files. [default: True]

• compression – Which compression scheme to use (if any). Options are: - None or ‘none’ = no compression - ‘rice’ = use rice compression in tiles (preserves header readability) - ‘gzip’ = use gzip to compress the full file - ‘bzip2’ = use bzip2 to compress the full file - ‘gzip_tile’ = use gzip in tiles (preserves header readability) - ‘hcompress’ = use hcompress in tiles (only valid for 2-d images) - ‘plio’ = use plio compression in tiles (only valid for pos integer data) - ‘auto’ = determine the compression from the extension of the file name (requires file_name to be given): - ‘.fz’ => ‘rice’ - ‘.gz’ => ‘gzip’ - ‘.bz2’ => ‘bzip2’ - otherwise None [default: ‘auto’]

Original GalSim Documentation

Write the Image instance image to a FITS file, with details depending on the arguments. This function can be called directly as galsim.fits.write(image, ...), with the image as the first argument, or as an Image method: image.write(...).

class jax_galsim.ImageD(*args, **kwargs)

Bases:

Alias for galsim.Image(…, dtype=numpy.float64)

LAX-backend implementation of galsim.image.ImageD().

🔪 JAX-GalSim - The Sharp Bits 🔪

Contrary to GalSim native Image, this implementation does not support sharing of the underlying array between different Images or views. This is due to the fact that in JAX numpy arrays are immutable, so any operation applied to this Image will create a new jnp.ndarray. Making a view via .view() will raise an error. Instead, use the .copy() method. The Image.subImage() method will return a copy.

class jax_galsim.ImageF(*args, **kwargs)

Bases:

Alias for galsim.Image(…, dtype=numpy.float32)

LAX-backend implementation of galsim.image.ImageF().

🔪 JAX-GalSim - The Sharp Bits 🔪

Contrary to GalSim native Image, this implementation does not support sharing of the underlying array between different Images or views. This is due to the fact that in JAX numpy arrays are immutable, so any operation applied to this Image will create a new jnp.ndarray. Making a view via .view() will raise an error. Instead, use the .copy() method. The Image.subImage() method will return a copy.

class jax_galsim.ImageI(*args, **kwargs)

Bases:

Alias for galsim.Image(…, dtype=numpy.int32)

LAX-backend implementation of galsim.image.ImageI().

🔪 JAX-GalSim - The Sharp Bits 🔪

Contrary to GalSim native Image, this implementation does not support sharing of the underlying array between different Images or views. This is due to the fact that in JAX numpy arrays are immutable, so any operation applied to this Image will create a new jnp.ndarray. Making a view via .view() will raise an error. Instead, use the .copy() method. The Image.subImage() method will return a copy.

class jax_galsim.ImageS(*args, **kwargs)

Bases:

Alias for galsim.Image(…, dtype=numpy.int16)

LAX-backend implementation of galsim.image.ImageS().

🔪 JAX-GalSim - The Sharp Bits 🔪

Contrary to GalSim native Image, this implementation does not support sharing of the underlying array between different Images or views. This is due to the fact that in JAX numpy arrays are immutable, so any operation applied to this Image will create a new jnp.ndarray. Making a view via .view() will raise an error. Instead, use the .copy() method. The Image.subImage() method will return a copy.

class jax_galsim.ImageUS(*args, **kwargs)

Bases:

Alias for galsim.Image(…, dtype=numpy.uint16)

LAX-backend implementation of galsim.image.ImageUS().

🔪 JAX-GalSim - The Sharp Bits 🔪

Contrary to GalSim native Image, this implementation does not support sharing of the underlying array between different Images or views. This is due to the fact that in JAX numpy arrays are immutable, so any operation applied to this Image will create a new jnp.ndarray. Making a view via .view() will raise an error. Instead, use the .copy() method. The Image.subImage() method will return a copy.

class jax_galsim.ImageUI(*args, **kwargs)

Bases:

Alias for galsim.Image(…, dtype=numpy.uint32)

LAX-backend implementation of galsim.image.ImageUI().

🔪 JAX-GalSim - The Sharp Bits 🔪

Contrary to GalSim native Image, this implementation does not support sharing of the underlying array between different Images or views. This is due to the fact that in JAX numpy arrays are immutable, so any operation applied to this Image will create a new jnp.ndarray. Making a view via .view() will raise an error. Instead, use the .copy() method. The Image.subImage() method will return a copy.

class jax_galsim.ImageCD(*args, **kwargs)

Bases:

Alias for galsim.Image(…, dtype=numpy.complex128)

LAX-backend implementation of galsim.image.ImageCD().

🔪 JAX-GalSim - The Sharp Bits 🔪

Contrary to GalSim native Image, this implementation does not support sharing of the underlying array between different Images or views. This is due to the fact that in JAX numpy arrays are immutable, so any operation applied to this Image will create a new jnp.ndarray. Making a view via .view() will raise an error. Instead, use the .copy() method. The Image.subImage() method will return a copy.

class jax_galsim.ImageCF(*args, **kwargs)

Bases:

Alias for galsim.Image(…, dtype=numpy.complex64)

LAX-backend implementation of galsim.image.ImageCF().

🔪 JAX-GalSim - The Sharp Bits 🔪

Contrary to GalSim native Image, this implementation does not support sharing of the underlying array between different Images or views. This is due to the fact that in JAX numpy arrays are immutable, so any operation applied to this Image will create a new jnp.ndarray. Making a view via .view() will raise an error. Instead, use the .copy() method. The Image.subImage() method will return a copy.

Bounds

class jax_galsim.Bounds

Bases: object

A class for representing image bounds as 2D rectangles.

LAX-backend implementation of galsim.bounds.Bounds().

🔪 JAX-GalSim - The Sharp Bits 🔪

The JAX implementation

• will not always test whether the bounds are valid

• will not always test whether BoundsI is initialized with integers

Further, the JAX implementation adds a new method, isStatic to the BoundsI class. If JAX-GalSim detects that the BoundsI instance has been instantiated with static, known values, isStatic() will return True. You can indicate to JAX-GalSim that a BoundsI instance should be static via initializing it with the static keyword set to the True. If the object detects that it is being initialized with non-static data, an error will be raised.

BoundsI objects in JAX-Galsim support an additional initialization call BoundsI(xmin=..., deltax=..., ymin=..., deltay=...). In this case, the values for deltax/y indicate the width of the bounds and must be static constants.

When calling jax.vmap over BoundsI objects, only x/ymin are vectorized over. This restriction allows for code that renders objects in fixed sized stamps with variable locations, a common operation. BoundsI objects which are static (i.e., isStatic() returns True) are treated as constants with respect to vmap, jit, and other JAX transforms.

Original GalSim Documentation

Bounds is a base class for two slightly different kinds of bounds: BoundsD describes bounds with floating point values in x and y. BoundsI described bounds with integer values in x and y.

The bounds are stored as four numbers in each instance, (xmin, xmax, ymin, ymax), with an additional boolean switch to say whether or not the Bounds rectangle has been defined. The rectangle is undefined if the min value > the max value in either direction.

Initialization:

A BoundsI or BoundsD instance can be initialized in a variety of ways. The most direct is via four scalars:

>>> bounds = galsim.BoundsD(xmin, xmax, ymin, ymax)
>>> bounds = galsim.BoundsI(imin, imax, jmin, jmax)

In the BoundsI example above, imin, imax, jmin and jmax must all be integers to avoid a TypeError exception.

Another way to initialize a Bounds instance is using two Position instances, the first for (xmin,ymin) and the second for (xmax,ymax):

>>> bounds = galsim.BoundsD(galsim.PositionD(xmin, ymin), galsim.PositionD(xmax, ymax))
>>> bounds = galsim.BoundsI(galsim.PositionI(imin, jmin), galsim.PositionI(imax, jmax))

In both the examples above, the I/D type of PositionI/PositionD must match that of BoundsI/BoundsD.

Finally, there are a two ways to lazily initialize a bounds instance with xmin = xmax, ymin = ymax, which will have an undefined rectangle and the instance method isDefined() will return False. The first sets xmin = xmax = ymin = ymax = 0:

>>> bounds = galsim.BoundsD()
>>> bounds = galsim.BoundsI()

The second method sets both upper and lower rectangle bounds to be equal to some position:

>>> bounds = galsim.BoundsD(galsim.PositionD(xmin, ymin))
>>> bounds = galsim.BoundsI(galsim.PositionI(imin, jmin))

Once again, the I/D type of PositionI/PositionD must match that of BoundsI/BoundsD.

For the latter two initializations, you would typically then add to the bounds with:

>>> bounds += pos1
>>> bounds += pos2
>>> [etc.]

Then the bounds will end up as the bounding box of all the positions that were added to it.

You can also find the intersection of two bounds with the & operator:

>>> overlap = bounds1 & bounds2

This is useful for adding one image to another when part of the first image might fall off the edge of the other image:

>>> overlap = stamp.bounds & image.bounds
>>> image[overlap] += stamp[overlap]

area()

Return the area of the enclosed region.

LAX-backend implementation of galsim.bounds.area().

Original GalSim Documentation

The area is a bit different for integer-type BoundsI and float-type BoundsD instances. For floating point types, it is simply (xmax-xmin)*(ymax-ymin). However, for integer types, we add 1 to each size to correctly count the number of pixels being described by the bounding box.

withBorder(dx, dy=None)

Return a new Bounds object that expands the current bounds by the specified width.

LAX-backend implementation of galsim.bounds.withBorder().

Original GalSim Documentation

If two arguments are given, then these are separate dx and dy borders.

property origin

The lower left position of the Bounds.

LAX-backend implementation of origin().

property center

The central position of the Bounds.

LAX-backend implementation of center().

Original GalSim Documentation

For a BoundsI, this will return an integer PositionI, which will be above and/or to the right of the true center if the x or y ranges have an even number of pixels.

For a BoundsD, this is equivalent to true_center.

property true_center

The central position of the Bounds as a PositionD.

LAX-backend implementation of true_center().

Original GalSim Documentation

This is always (xmax + xmin)/2., (ymax + ymin)/2., even for integer BoundsI, where this may not necessarily be an integer PositionI.

includes(*args)

Test whether a supplied (x,y) pair, Position, or Bounds lie within a defined Bounds rectangle of this instance.

LAX-backend implementation of galsim.bounds.includes().

Original GalSim Documentation

Examples:

>>> bounds = galsim.BoundsD(0., 100., 0., 100.)
>>> bounds.includes(50., 50.)
True
>>> bounds.includes(galsim.PositionD(50., 50.))
True
>>> bounds.includes(galsim.BoundsD(-50., -50., 150., 150.))
False

The type of the PositionI/PositionD and BoundsI/BoundsD instances (i.e. integer or float type) should match that of the bounds instance.

expand(factor_x, factor_y=None)

Grow the Bounds by the supplied factor about the center.

LAX-backend implementation of galsim.bounds.expand().

Original GalSim Documentation

If two arguments are given, then these are separate x and y factors to expand by.

isDefined()

Test whether Bounds rectangle is defined.

LAX-backend implementation of galsim.bounds.isDefined().

getXMin()

Get the value of xmin.

LAX-backend implementation of galsim.bounds.getXMin().

getXMax()

Get the value of xmax.

LAX-backend implementation of galsim.bounds.getXMax().

getYMin()

Get the value of ymin.

LAX-backend implementation of galsim.bounds.getYMin().

getYMax()

Get the value of ymax.

LAX-backend implementation of galsim.bounds.getYMax().

shift(delta)

Shift the Bounds instance by a supplied Position.

LAX-backend implementation of galsim.bounds.shift().

Original GalSim Documentation

Examples:

The shift method takes either a PositionI or PositionD instance, which must match the type of the Bounds instance:

>>> bounds = BoundsI(1,32,1,32)
>>> bounds = bounds.shift(galsim.PositionI(3, 2))
>>> bounds = BoundsD(0, 37.4, 0, 49.9)
>>> bounds = bounds.shift(galsim.PositionD(3.9, 2.1))

tree_flatten()

This function flattens the Bounds into a list of children nodes that will be traced by JAX and auxiliary static data.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation

classmethod from_galsim(galsim_bounds)

Create a jax_galsim BoundsD/I from a galsim.BoundsD/I object.

to_galsim()

Create a galsim BoundsD/I from a jax_galsim.BoundsD/I object.

isStatic()

Returns True if the BoundsI instance has static, known dimensions and location. Always returns False for BoundsD.

class jax_galsim.BoundsI(*args, **kwargs)

Bases: Bounds

A Bounds that takes only integer values.

LAX-backend implementation of galsim.bounds.BoundsI().

🔪 JAX-GalSim - The Sharp Bits 🔪

The JAX implementation

• will not always test whether the bounds are valid

• will not always test whether BoundsI is initialized with integers

Further, the JAX implementation adds a new method, isStatic to the BoundsI class. If JAX-GalSim detects that the BoundsI instance has been instantiated with static, known values, isStatic() will return True. You can indicate to JAX-GalSim that a BoundsI instance should be static via initializing it with the static keyword set to the True. If the object detects that it is being initialized with non-static data, an error will be raised.

BoundsI objects in JAX-Galsim support an additional initialization call BoundsI(xmin=..., deltax=..., ymin=..., deltay=...). In this case, the values for deltax/y indicate the width of the bounds and must be static constants.

When calling jax.vmap over BoundsI objects, only x/ymin are vectorized over. This restriction allows for code that renders objects in fixed sized stamps with variable locations, a common operation. BoundsI objects which are static (i.e., isStatic() returns True) are treated as constants with respect to vmap, jit, and other JAX transforms.

Original GalSim Documentation

Typically used to define the bounding box of an image.

See the Bounds doc string for more details.

numpyShape()

A simple utility function to get the numpy shape that corresponds to this Bounds object.

property xmin

property xmax

property ymin

property ymax

tree_flatten()

This function flattens the Bounds into a list of children nodes that will be traced by JAX and auxiliary static data.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation

class jax_galsim.BoundsD(*args, **kwargs)

Bases: Bounds

A Bounds that takes floating point values.

LAX-backend implementation of galsim.bounds.BoundsD().

🔪 JAX-GalSim - The Sharp Bits 🔪

The JAX implementation

• will not always test whether the bounds are valid

• will not always test whether BoundsI is initialized with integers

Further, the JAX implementation adds a new method, isStatic to the BoundsI class. If JAX-GalSim detects that the BoundsI instance has been instantiated with static, known values, isStatic() will return True. You can indicate to JAX-GalSim that a BoundsI instance should be static via initializing it with the static keyword set to the True. If the object detects that it is being initialized with non-static data, an error will be raised.

BoundsI objects in JAX-Galsim support an additional initialization call BoundsI(xmin=..., deltax=..., ymin=..., deltay=...). In this case, the values for deltax/y indicate the width of the bounds and must be static constants.

When calling jax.vmap over BoundsI objects, only x/ymin are vectorized over. This restriction allows for code that renders objects in fixed sized stamps with variable locations, a common operation. BoundsI objects which are static (i.e., isStatic() returns True) are treated as constants with respect to vmap, jit, and other JAX transforms.

Original GalSim Documentation

See the Bounds doc string for more details.

property xmax

property ymax

Positions

class jax_galsim.Position

Bases: object

A class for representing 2D positions on the plane.

LAX-backend implementation of galsim.position.Position().

Original GalSim Documentation

Position is a base class for two slightly different kinds of positions: PositionD describes positions with floating point values in x and y. PositionI described positions with integer values in x and y.

In the C++ layer, these are templates, but of course no such thing exists in Python, so the trailing D or I indicate the type.

Initialization:

For the float-valued position class, example initializations include:

>>> pos = galsim.PositionD(x=0.5, y=-0.5)
>>> pos = galsim.PositionD(0.5, -0.5)
>>> pos = galsim.PositionD( (0.5, -0.5) )

And for the integer-valued position class, example initializations include:

>>> pos = galsim.PositionI(x=45, y=13)
>>> pos = galsim.PositionI(45, 13)
>>> pos = galsim.PositionD( (45, 15) )

Attributes:

x: The x component of the position y: The y component of the position

Arithmetic:

Most arithmetic that makes sense for a position is allowed:

>>> pos1 + pos2
>>> pos1 - pos2
>>> pos * x
>>> pos / x
>>> -pos
>>> pos1 += pos2
>>> pos1 -= pos2
>>> pos *= x
>>> pos -= x

Note though that the types generally need to match. For example, you cannot multiply a PositionI by a float add a PositionD to a PositionI in place.

Position instances can be sheared by a galsim.Shear:

>>> pos = galsim.PositionD(x=0.5, y=-0.5)
>>> shear = galsim.Shear(g1=0.1, g2=-0.1)
>>> sheared_pos = pos.shear(shear)

Note that this operation will always return a PositionD even if an integer position is being sheared.

shear(shear)

Shear the position.

LAX-backend implementation of galsim.position.shear().

Parameters:

shear – a galsim.Shear instance

Original GalSim Documentation

See the doc string of galsim.Shear.getMatrix for more details.

Returns:

a galsim.PositionD instance.

round()

Return the rounded-off PositionI version of this position.

tree_flatten()

This function flattens the GSObject into a list of children nodes that will be traced by JAX and auxiliary static data.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation

classmethod from_galsim(galsim_position)

Create a jax_galsim PositionD/I from a galsim.PositionD/I object.

to_galsim()

Create a galsim PositionD/I from a jax_galsim.PositionD/I object.

class jax_galsim.PositionI(*args, **kwargs)

Bases: Position

A Position that takes only integer values.

LAX-backend implementation of galsim.position.PositionI().

Original GalSim Documentation

Typically used for coordinate positions on an image.

See the Position doc string for more details.

class jax_galsim.PositionD(*args, **kwargs)

Bases: Position

A Position that takes floating point values.

LAX-backend implementation of galsim.position.PositionD().

Original GalSim Documentation

See the Position doc string for more details.

Coordinates

class jax_galsim.CelestialCoord(ra, dec=None)

Bases: object

This class defines a position on the celestial sphere, normally given by two angles, ra and dec.

LAX-backend implementation of coord.celestial.CelestialCoord().

🔪 JAX-GalSim - The Sharp Bits 🔪

The JAX version of this object does not check that the declination is between -90 and 90.

Original GalSim Documentation

This class can be used to perform various calculations in spherical coordinates, such as finding the angular distance between two points in the sky, calculating the angles in spherical triangles, projecting from sky coordinates onto a Euclidean tangent plane, etc.

Initialization:

A CelestialCoord object is constructed from the right ascension and declination:

coord.CelestialCoord.__init__()

>>> c = CelestialCoord(ra=12*hours, dec=31*degrees)
>>> print(c)
coord.CelestialCoord(3.141592653589793 radians, 0.5410520681182421 radians)

Attributes:

A CelestialCoord has the following (read-only) attributes:

ra:

The right ascension (an Angle instance)

dec:

The declination (an Angle instance)

>>> print(c.ra / degrees, c.dec / degrees)
180.0 31.0

In addition there is a convenience access property that returns ra and dec in radians.

rad:

A tuple (ra.rad, dec.rad)

>>> print(c.rad)
(3.141592653589793, 0.5410520681182421)

Spherical Geometry:

The basic spherical geometry operations are available to work with spherical triangles

For three coordinates cA, cB, cC making a spherical triangle, one can calculate the sides and angles via:

coord.CelestialCoord.distanceTo()

coord.CelestialCoord.angleBetween()

>>> cA = CelestialCoord(0 * degrees, 0 * degrees)
>>> cB = CelestialCoord(0 * degrees, 10 * degrees)
>>> cC = CelestialCoord(10 * degrees, 0 * degrees)
>>> a = cB.distanceTo(cC)
>>> b = cC.distanceTo(cA)
>>> c = cA.distanceTo(cB)
>>> print(a.deg, b.deg, c.deg)
14.106044260566366 10.0 10.0
>>> A = cA.angleBetween(cB, cC)
>>> B = cB.angleBetween(cC, cA)
>>> C = cC.angleBetween(cA, cB)
>>> print(A.deg, B.deg, C.deg)
90.0 45.43854858674231 45.43854858674231

Projections:

Local tangent plane projections of an area of the sky can be performed using the project method:

coord.CelestialCoord.project()

>>> center = CelestialCoord(ra=10*hours, dec=30*degrees)
>>> sky_coord = CelestialCoord(ra=10.5*hours, dec=31*degrees)
>>> print(sky_coord)
coord.CelestialCoord(2.748893571891069 radians, 0.5410520681182421 radians)
>>> u, v = center.project(sky_coord)
>>> print(u.deg, v.deg)
-6.452371275343261 1.21794987288635

and back:

coord.CelestialCoord.deproject()

>>> sky_coord = center.deproject(u,v)
>>> print(sky_coord)
coord.CelestialCoord(2.748893571891069 radians, 0.5410520681182421 radians)

where u and v are Angles and center and sky_coord are CelestialCoords.

property ra

A read-only attribute, giving the Right Ascension as an Angle

LAX-backend implementation of ra().

property dec

A read-only attribute, giving the Declination as an Angle

LAX-backend implementation of dec().

property rad

A convenience property, giving a tuple (ra.rad, dec.rad)

LAX-backend implementation of rad().

get_xyz()

Get the (x,y,z) coordinates on the unit sphere corresponding to this (RA, Dec).

LAX-backend implementation of coord.celestial.get_xyz().

Original GalSim Documentation

\[\begin{split}x &= \cos(dec) \cos(ra) \\ y &= \cos(dec) \sin(ra) \\ z &= \sin(dec)\end{split}\]

returns:

a tuple (x,y,z)

static from_xyz(x, y, z)

Construct a CelestialCoord from a given (x,y,z) position in three dimensions.

LAX-backend implementation of coord.celestial.from_xyz().

🔪 JAX-GalSim - The Sharp Bits 🔪

The JAX version of this static method does not check that the norm of the input vector is non-zero.

Original GalSim Documentation

The 3D (x,y,z) position does not need to fall on the unit sphere. The RA, Dec will be inferred from the relations:

\[\begin{split}x &= r \cos(dec) \cos(ra) \\ y &= r \cos(dec) \sin(ra) \\ z &= r \sin(dec)\end{split}\]

where \(r\) is arbitrary.

param x:

The x position in 3 dimensions. Corresponds to r cos(dec) cos(ra)

param y:

The y position in 3 dimensions. Corresponds to r cos(dec) sin(ra)

param z:

The z position in 3 dimensions. Corresponds to r sin(dec)

returns:

a CelestialCoord instance

static radec_to_xyz(ra, dec, r=1.0)

Convert ra, dec (in radians) to 3D x,y,z coordinates on the unit sphere.

LAX-backend implementation of coord.celestial.radec_to_xyz().

Original GalSim Documentation

The connection between (ra,dec) and (x,y,z) are given by the following formulae: .. math:

x &= r \cos(dec) \cos(ra)  \\
y &= r \cos(dec) \sin(ra)  \\
z &= r \sin(dec)

For a single ra,dec pair, the following are essentially equivalent:

>>> ra = 12*hours/radians       # May be any angle measured
>>> dec = 31*degrees/radians    # in radians

>>> CelestialCoord.radec_to_xyz(ra, dec)
(-0.8571673007021123, 1.0497271911386187e-16, 0.5150380749100542)

>>> CelestialCoord(ra * radians, dec * radians).get_xyz()
(-0.8571673007021123, 1.0497271911386187e-16, 0.5150380749100542)

However, the advantage of this function is that the input values may be numpy arrays, in which case, the return values will also be numpy arrays.

param ra:

The right ascension(s) in radians. May be a numpy array.

param dec:

The declination(s) in radians. May be a numpy array.

param r:

The distance(s) from Earth (default 1.). May be a numpy array.

returns:

x, y, z as a tuple.

static xyz_to_radec(x, y, z, return_r=False)

Convert 3D x,y,z coordinates to ra, dec (in radians).

LAX-backend implementation of coord.celestial.xyz_to_radec().

Original GalSim Documentation

The connection between (ra,dec) and (x,y,z) are given by the following formulae: .. math:

x &= r \cos(dec) \cos(ra)  \\
y &= r \cos(dec) \sin(ra)  \\
z &= r \sin(dec)

For a single (x,y,z) position, the following are essentially equivalent:

>>> x = 0.839       # May be any any 3D location
>>> y = 0.123       # Not necessarily on unit sphere
>>> z = 0.530

>>> CelestialCoord.xyz_to_radec(x, y, z)
(0.14556615088111796, 0.558616191048523)

>>> c = CelestialCoord.from_xyz(x, y, z)
>>> c.ra.rad, c.dec.rad
(0.145566150881118, 0.558616191048523)

However, the advantage of this function is that the input values may be numpy arrays, in which case, the return values will also be numpy arrays.

param x:

The x position(s) in 3 dimensions. May be a numpy array.

param y:

The y position(s) in 3 dimensions. May be a numpy array.

param z:

The z position(s) in 3 dimensions. May be a numpy array.

param return_r:

Whether to return r as well as ra, dec. (default: False)

returns:

ra, dec as a tuple. Or if return_r is True, (ra, dec, r).

normal()

Return the coordinate in the “normal” convention of having 0 <= ra < 24 hours.

LAX-backend implementation of coord.celestial.normal().

Original GalSim Documentation

This convention is not enforced on construction, so this function exists to make it easy to convert if desired.

Functions such as from_galactic and from_xyz will return normal coordinates.

distanceTo(coord2)

Returns the great circle distance between this coord and another one. The return value is an Angle object

LAX-backend implementation of coord.celestial.distanceTo().

Original GalSim Documentation

param coord2:

The CelestialCoord to calculate the distance to.

returns:

the great circle distance to coord2.

greatCirclePoint(coord2, theta)

Returns a point on the great circle connecting self and coord2.

LAX-backend implementation of coord.celestial.greatCirclePoint().

🔪 JAX-GalSim - The Sharp Bits 🔪

The JAX version of this method does not check that coord2 defines a unique great circle with the current coord at angle theta.

Original GalSim Documentation

Two points, c1 and c2, on the unit sphere define a great circle (so long as the two points are not either coincident or antipodal). We can define points on this great circle by their angle from c1, such that the angle for c2 has 0 < theta2 < pi. I.e. theta increases from 0 as the points move from c1 towards c2.

This function then returns the coordinate on this great circle (where c1 is self and c2 is coord2) that corresponds to the given angle theta.

param coord2:

Another CelestialCoord defining the great circle to use.

param theta:

The Angle along the great circle corresponding to the desired point.

returns:

the corresponding CelestialCoord

angleBetween(coord2, coord3)

Find the open angle at the location of the current coord between coord2 and coord3.

LAX-backend implementation of coord.celestial.angleBetween().

Original GalSim Documentation

The current coordinate along with the two other coordinates form a spherical triangle on the sky. This function calculates the angle between the two sides at the location of the current coordinate.

Note that this returns a signed angle. The angle is positive if the sweep direction from coord2 to coord3 is counter-clockwise (as observed from Earth). It is negative if the direction is clockwise.

param coord2:

A second CelestialCoord

param coord3:

A third CelestialCoord

returns:

the angle between the great circles joining the other two coordinates to the current coordinate.

area(coord2, coord3)

Find the area of a spherical triangle in steradians.

LAX-backend implementation of coord.celestial.area().

Original GalSim Documentation

The current coordinate along with the two other coordinates form a spherical triangle on the sky. This function calculates the area of that spherical triangle, which is measured in steradians (i.e. surface area of the triangle on the unit sphere).

param coord2:

A second CelestialCoord

param coord3:

A third CelestialCoord

returns:

the area in steradians of the given spherical triangle.

project(coord2, projection=None)

Use the currect coord as the center point of a tangent plane projection to project the coord2 coordinate onto that plane.

LAX-backend implementation of coord.celestial.project().

Original GalSim Documentation

This function return a tuple (u,v) in the Euclidean coordinate system defined by a tangent plane projection around the current coordinate, with +v pointing north and +u pointing west. (i.e. to the right on the sky if +v is up.)

There are currently four options for the projection, which you can specify with the optional projection keyword argument:

gnomonic:

[default] uses a gnomonic projection (i.e. a projection from the center of the sphere, which has the property that all great circles become straight lines. For more information, see http://mathworld.wolfram.com/GnomonicProjection.html This is the usual TAN projection used by most FITS images.

stereographic:

uses a stereographic proejection, which preserves angles, but not area. For more information, see http://mathworld.wolfram.com/StereographicProjection.html

lambert:

uses a Lambert azimuthal projection, which preserves area, but not angles. For more information, see http://mathworld.wolfram.com/LambertAzimuthalEqual-AreaProjection.html

postel:

uses a Postel equidistant proejection, which preserves distances from the projection point, but not area or angles. For more information, see http://mathworld.wolfram.com/AzimuthalEquidistantProjection.html

The distance or angle errors increase with distance from the projection point of course.

param coord2:

The coordinate to project onto the tangent plane.

param projection:

The name of the projection to be used. [default: gnomonic, see above for other options]

returns:

(u,v) as Angle instances

project_rad(ra, dec, projection=None)

This is basically identical to the project() function except that the input ra, dec are given in radians rather than packaged as a CelestialCoord object and the returned u,v are given in radians.

LAX-backend implementation of coord.celestial.project_rad().

Original GalSim Documentation

The main advantage to this is that it will work if ra and dec are NumPy arrays, in which case the output u, v will also be NumPy arrays.

param ra:

The right ascension in radians to project onto the tangent plane.

param dec:

The declination in radians to project onto the tangent plane.

param projection:

The name of the projection to be used. [default: gnomonic, see project docstring for other options]

returns:

(u,v) in radians

deproject(u, v, projection=None)

Do the reverse process from the project() function.

LAX-backend implementation of coord.celestial.deproject().

Original GalSim Documentation

i.e. This takes in a position (u,v) and returns the corresponding celestial coordinate, using the current coordinate as the center point of the tangent plane projection.

param u:

The u position on the tangent plane to deproject (must be an Angle instance)

param v:

The v position on the tangent plane to deproject (must be an Angle instance)

param projection:

The name of the projection to be used. [default: gnomonic, see project docstring for other options]

returns:

the corresponding CelestialCoord for that position.

deproject_rad(u, v, projection=None)

This is basically identical to the deproject() function except that the output ra, dec are returned as a tuple (ra, dec) in radians rather than packaged as a CelestialCoord object and u and v are in radians rather than Angle instances.

LAX-backend implementation of coord.celestial.deproject_rad().

Original GalSim Documentation

The main advantage to this is that it will work if u and v are NumPy arrays, in which case the output ra, dec will also be NumPy arrays.

param u:

The u position in radians on the tangent plane to deproject

param v:

The v position in radians on the tangent plane to deproject

param projection:

The name of the projection to be used. [default: gnomonic, see project docstring for other options]

returns:

the corresponding RA, Dec in radians

jac_deproject(u, v, projection=None)

Return the jacobian of the deprojection.

LAX-backend implementation of coord.celestial.jac_deproject().

Original GalSim Documentation

i.e. if the input position is (u,v) then the return matrix is

\[\begin{split}J \equiv \begin{bmatrix} J00 & J01 \\ J10 & J11 \end{bmatrix} = \begin{bmatrix} d\textrm{ra}/du \cos(\textrm{dec}) & d\textrm{ra}/dv \cos(\textrm{dec}) \\ d\textrm{dec}/du & d\textrm{dec}/dv \end{bmatrix}\end{split}\]

param u:

The u position (as an Angle instance) on the tangent plane

param v:

The v position (as an Angle instance) on the tangent plane

param projection:

The name of the projection to be used. [default: gnomonic, see project docstring for other options]

returns:

the Jacobian as a 2x2 numpy array [[J00, J01], [J10, J11]]

jac_deproject_rad(u, v, projection=None)

Equivalent to jac_deproject, but the inputs are in radians and may be numpy arrays.

LAX-backend implementation of coord.celestial.jac_deproject_rad().

Original GalSim Documentation

param u:

The u position (in radians) on the tangent plane

param v:

The v position (in radians) on the tangent plane

param projection:

The name of the projection to be used. [default: gnomonic, see project docstring for other options]

returns:

the Jacobian as a 2x2 numpy array [[J00, J01], [J10, J11]]

precess(from_epoch, to_epoch)

This function precesses equatorial ra and dec from one epoch to another. It is adapted from a set of fortran subroutines based on (a) pages 30-34 of the Explanatory Supplement to the AE, (b) Lieske, et al. (1977) A&A 58, 1-16, and (c) Lieske (1979) A&A 73, 282-284.

LAX-backend implementation of coord.celestial.precess().

Original GalSim Documentation

param from_epoch:

The epoch of the current coordinate

param to_epoch:

The epoch of the returned precessed coordinate

returns:

a CelestialCoord object corresponding to the precessed position.

galactic(epoch=2000.0)

Get the longitude and latitude in galactic coordinates corresponding to this position.

LAX-backend implementation of coord.celestial.galactic().

Original GalSim Documentation

param epoch:

The epoch of the current coordinate. [default: 2000.]

returns:

the longitude and latitude as a tuple (el, b), given as Angle instances.

static from_galactic(el, b, epoch=2000.0)

Create a CelestialCoord from the given galactic coordinates

LAX-backend implementation of coord.celestial.from_galactic().

Original GalSim Documentation

param el:

The longitude in galactic coordinates (an Angle instance)

param b:

The latitude in galactic coordinates (an Angle instance)

param epoch:

The epoch of the returned coordinate. [default: 2000.]

returns:

the CelestialCoord corresponding to these galactic coordinates.

ecliptic(epoch=2000.0, date=None)

Get the longitude and latitude in ecliptic coordinates corresponding to this position.

LAX-backend implementation of coord.celestial.ecliptic().

Original GalSim Documentation

The epoch parameter is used to get an accurate value for the (time-varying) obliquity of the ecliptic. The formulae for this are quite straightforward. It requires just a single parameter for the transformation, the obliquity of the ecliptic (the Earth’s axial tilt).

param epoch:

The epoch to be used for estimating the obliquity of the ecliptic, if date is None. But if date is given, then use that to determine the epoch. [default: 2000.]

param date:

If a date is given as a python datetime object, then return the position in ecliptic coordinates with respect to the sun position at that date. If None, then return the true ecliptic coordiantes. [default: None]

returns:

the longitude and latitude as a tuple (lambda, beta), given as Angle instances.

static from_ecliptic(lam, beta, epoch=2000.0, date=None)

Create a CelestialCoord from the given ecliptic coordinates

LAX-backend implementation of coord.celestial.from_ecliptic().

Original GalSim Documentation

param lam:

The longitude in ecliptic coordinates (an Angle instance)

param beta:

The latitude in ecliptic coordinates (an Angle instance)

param epoch:

The epoch to be used for estimating the obliquity of the ecliptic, if date is None. But if date is given, then use that to determine the epoch. [default: 2000.]

param date:

If a date is given as a python datetime object, then return the position in ecliptic coordinates with respect to the sun position at that date. If None, then return the true ecliptic coordiantes. [default: None]

returns:

the CelestialCoord corresponding to these ecliptic coordinates.

tree_flatten()

This function flattens the CelestialCoord into a list of children nodes that will be traced by JAX and auxiliary static data.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation

static from_galsim(gcoord)

Create a jax_galsim CelestialCoord from a galsim.CelestialCoord object.

to_galsim()

Create a galsim CelestialCoord from a jax_galsim.CelestialCoord object.

class jax_galsim.Angle(theta, unit=None)

Bases: object

A class representing an Angle. Angles are a value with an AngleUnit.

LAX-backend implementation of coord.angle.Angle().

Original GalSim Documentation

Initialization:

You typically create an Angle by multiplying a number by a coord.AngleUnit, for example:

>>> pixel = 0.27 * arcsec
>>> ra = 13.4 * hours
>>> dec = -32 * degrees
>>> from math import pi
>>> theta = pi/2. * radians

You can also initialize explicitly, taking a value and a unit:

coord.Angle.__init__()

>>> unit = AngleUnit(math.pi / 100)  # gradians
>>> phi = Angle(90, unit)

Built-in units:

There are five built-in AngleUnits which are always available for use:

coord.radians:

coord.AngleUnit(1.)

coord.degrees:

coord.AngleUnit(pi / 180.)

coord.hours:

coord.AngleUnit(pi / 12.)

coord.arcmin:

coord.AngleUnit(pi / 180. / 60.)

coord.arcsec:

coord.AngleUnit(pi / 180. / 3600.)

Attribute:

Since extracting the value in radians is extremely common, we have a read-only attribute to do this quickly:

rad:

The measure of the unit in radians.

For example:

>>> theta = 90 * degrees
>>> print(theta.rad)
1.5707963267948966

It is equivalent to the more verbose:

>>> x = theta / radians
>>> print(x)
1.5707963267948966

but without actually requiring the floating point operation of dividing by 1.

Arithmetic:

Allowed arithmetic with Angles include the following. In the list below,

• x is an arbitrary float value

• unit1 and unit2 are arbitrary AngleUnit instances

• theta1 and theta2 are arbitrary Angle instances

>>> x = 37.8
>>> unit1 = arcmin
>>> unit2 = degrees

>>> theta1 = x * unit1
>>> theta2 = x * unit2
>>> x2 = theta1 / unit2
>>> theta = theta1 + theta2
>>> theta = theta1 - theta2
>>> theta = theta1 * x
>>> theta = x * theta1
>>> theta = theta1 / x
>>> theta = -theta1
>>> theta += theta1
>>> theta -= theta1
>>> theta *= x
>>> theta /= x
>>> x = unit1 / unit2   # equivalent to x = (1 * unit1) / unit2

The above operations on NumPy arrays containing Angles are permitted as well.

Trigonometry:

There are convenience function for getting the sin, cos, and tan of an angle, along with one for getting sin and cos together, which should be more efficient than doing sin and cos separately:

coord.Angle.sin()

coord.Angle.cos()

coord.Angle.tan()

coord.Angle.sincos()

>>> sint = theta.sin()  # equivalent to sint = math.sin(theta.rad)
>>> cost = theta.cos()  # equivalent to cost = math.cos(theta.rad)
>>> tant = theta.tan()  # equivalent to tant = math.tan(theta.rad)
>>> sint, cost = theta.sincos()

These functions mean that numpy trig functions will work on Angles or arrays of Angles:

>>> sint = np.sin(theta)
>>> cost = np.cos(theta)
>>> tant = np.tan(theta)

Wrapping:

Depending on the context, theta = 2pi radians and theta = 0 radians may mean the same thing. If you want your angles to be wrapped to [-pi,pi) radians, you can do this by calling

coord.Angle.wrap()

>>> theta = theta.wrap()

This could be appropriate before testing for the equality of two angles for example, or calculating the difference between them.

There is also an option to wrap into a different 2 pi range if so desired by specifying the center of the range.

property rad

Return the Angle in radians.

LAX-backend implementation of rad().

Original GalSim Documentation

Equivalent to angle / coord.radians

property deg

Return the Angle in degrees.

LAX-backend implementation of deg().

Original GalSim Documentation

Equivalent to angle / coord.degrees

wrap(center=None)

Wrap Angle to lie in the range [-pi, pi) radians (or other range of 2pi radians)

LAX-backend implementation of coord.angle.wrap().

Original GalSim Documentation

Depending on the context, theta = 2pi radians and theta = 0 radians are the same thing. If you want your angles to be wrapped to [-pi, pi) radians, you can do this as follows:

>>> theta = Angle(700 * degrees)
>>> theta = theta.wrap()
>>> print(theta.deg)
-19.99999999999998

This could be appropriate before testing for the equality of two angles for example, or calculating the difference between them.

If you want to wrap to a different range than [-pi, pi), you can set the center argument to be the desired center of the the range. e.g. for return values to fall in [0, 2pi), you could call

>>> theta = theta.wrap(center=180. * degrees)
>>> print(theta / degrees)
340.0

param center:

The center point of the wrapped range. [default: 0 radians]

returns:

the equivalent angle within the range [center-pi, center+pi)

sin()

Return the sin of an Angle.

LAX-backend implementation of coord.angle.sin().

cos()

Return the cos of an Angle.

LAX-backend implementation of coord.angle.cos().

tan()

Return the tan of an Angle.

LAX-backend implementation of coord.angle.tan().

sincos()

Return both the sin and cos of an Angle as a numpy array [sint, cost].

LAX-backend implementation of coord.angle.sincos().

hms(sep=':', prec=None, pad=True, plus_sign=False)

Return an HMS representation of the angle as a string: +-hh:mm:ss.decimal.

LAX-backend implementation of coord.angle.hms().

Original GalSim Documentation

An optional sep parameter can change the : to something else (e.g. a space or nothing at all).

Note: the reverse process is effected by Angle.from_hms():

>>> angle = -5.357 * hours
>>> hms = angle.hms()
>>> print(hms)
-05:21:25.2
>>> angle2 = Angle.from_hms(hms)
>>> print(angle2 / hours)
-5.356999999999999

param sep:

The token to put between the hh and mm and beteen mm and ss. This may also be a string of 2 or 3 items, e.g. ‘hm’ or ‘hms’. Or even a tuple of strings such as (‘hours ‘, ‘minutes ‘, ‘seconds’). [default: ‘:’]

param prec:

The number of digits of precision after the decimal point. [default: None]

param pad:

Whether to pad with a leading 0 if necessary to make h,m,s 2 digits. [default: True]

param plus_sign:

Whether to use a plus sign for positive angles. [default: False]

returns:

a string of the HMS representation of the angle.

dms(sep=':', prec=None, pad=True, plus_sign=False)

Return a DMS representation of the angle as a string: +-dd:mm:ss.decimal An optional sep parameter can change the : to something else (e.g. a space or nothing at all).

LAX-backend implementation of coord.angle.dms().

Original GalSim Documentation

Note: the reverse process is effected by Angle.from_dms():

>>> angle = -(5 * degrees + 21 * arcmin + 25.2 * arcsec)
>>> dms = angle.dms()
>>> print(dms)
-05:21:25.2
>>> angle2 = Angle.from_dms(dms)
>>> print(angle2 / degrees)
-5.356999999999999

param sep:

The token to put between the hh and mm and beteen mm and ss. This may also be a string of 2 or 3 items, e.g. ‘dm’ or ‘dms’. Or even a tuple of strings such as (‘degrees ‘, ‘minutes ‘, ‘seconds’). [default: ‘:’]

param prec:

The number of digits of precision after the decimal point. [default: None]

param pad:

Whether to pad with a leading 0 if necessary to make h 2 digits. [default: True]

param plus_sign:

Whether to use a plus sign for positive angles. [default: False]

returns:

a string of the DMS representation of the angle.

static from_hms(str)

Convert a string of the form hh:mm:ss.decimal into an Angle.

LAX-backend implementation of coord.angle.from_hms().

Original GalSim Documentation

There may be an initial + or - (or neither), then two digits for the hours, two for the minutes, and two for the seconds. Then there may be a decimal point followed by more digits. There may be a colon separating hh, mm, and ss, or whitespace, or nothing at all. In fact, the code will ignore any non-digits between the hours, minutes, and seconds.

Note: the reverse process is effected by Angle.hms():

>>> angle = -5.357 * hours
>>> hms = angle.hms()
>>> print(hms)
-05:21:25.2
>>> angle2 = Angle.from_hms(hms)
>>> print(angle2 / hours)
-5.356999999999999

param str:

The string to parse.

returns:

the corresponding Angle instance

static from_dms(str)

Convert a string of the form dd:mm:ss.decimal into an Angle.

LAX-backend implementation of coord.angle.from_dms().

Original GalSim Documentation

There may be an initial + or - (or neither), then two digits for the degrees, two for the minutes, and two for the seconds. Then there may be a decimal point followed by more digits. There may be a colon separating dd, mm, and ss, or whitespace, or nothing at all. In fact, the code will ignore any non-digits between the degrees, minutes, and seconds.

Note: the reverse process is effected by Angle.dms():

>>> angle = -(5 * degrees + 21 * arcmin + 25.2 * arcsec)
>>> dms = angle.dms()
>>> print(dms)
-05:21:25.2
>>> angle2 = Angle.from_dms(dms)
>>> print(angle2 / degrees)
-5.356999999999999

param str:

The string to parse.

returns:

the corresponding Angle instance

tree_flatten()

This function flattens the Angle into a list of children nodes that will be traced by JAX and auxiliary static data.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation

static from_galsim(gs_angle)

Create a jax_galsim Angle from a galsim.Angle object.

to_galsim()

Create a galsim Angle from a jax_galsim.Angle object.

class jax_galsim.AngleUnit(value)

Bases: object

A class for defining angular units used by Angle objects.

LAX-backend implementation of coord.angleunit.AngleUnit().

Original GalSim Documentation

Initialization:

An AngleUnit takes a single argument for initialization, a float that specifies the size of the desired angular unit in radians. For example:

coord.AngleUnit.__init__()

>>> gradian = AngleUnit(2. * math.pi / 400.)
>>> print(gradian)
coord.AngleUnit(0.015707963267948967)

Built-in units:

There are five built-in AngleUnits which are always available for use:

coord.radians:

coord.AngleUnit(1.)

coord.degrees:

coord.AngleUnit(pi / 180.)

coord.hours:

coord.AngleUnit(pi / 12.)

coord.arcmin:

coord.AngleUnit(pi / 180. / 60.)

coord.arcsec:

coord.AngleUnit(pi / 180. / 3600.)

Attribute:

An AngleUnit as the following (read-only) attribute:

value:

The measure of the unit in radians.

valid_names = ['rad', 'deg', 'hr', 'hour', 'arcmin', 'arcsec']

property value

A read-only attribute giving the measure of the AngleUnit in radians.

LAX-backend implementation of value().

static from_name(unit)

Convert a string into the corresponding AngleUnit.

LAX-backend implementation of coord.angleunit.from_name().

Original GalSim Documentation

Only the start of the string is checked, so for instance ‘radian’ or ‘radians’ is equivalent to ‘rad’.

Valid options are:

rad:

AngleUnit(1.)

deg:

AngleUnit(pi / 180.)

hour or hr:

AngleUnit(pi / 12.)

arcmin:

AngleUnit(pi / 180. / 60.)

arcsec:

AngleUnit(pi / 180. / 3600.)

Note: these valid names are listed in AngleUnit.valid_names.

param unit:

The string name of the unit to return

returns:

an AngleUnit

tree_flatten()

This function flattens the AngleUnit into a list of children nodes that will be traced by JAX and auxiliary static data.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation