Utils (skypy.utils
)¶
Decorators¶
SkyPy provides a number of convenient decorators to perform common tasks:
Use the default cosmology¶
The uses_default_cosmology
decorator will check if a cosmology
argument is
provided, and if not, use the astropy.cosmology.default_cosmology
instead.
from skypy.utils import uses_default_cosmology
@uses_default_cosmology
def a_function_with_cosmology(cosmology):
print('the comoving distance at z=1 is', cosmology.comoving_distance(1.))
# function can now be called without argument
a_function_with_cosmology()
# output: the comoving distance at z=1 is 3395.9053119753967 Mpc
As shown in the example, the decorated function should treat the cosmology
argument as a non-optional argument. Because the uses_default_cosmology
decorator provides a required argument, it should always be placed above
decorators which handle arguments.
Broadcast arguments to same shape¶
The broadcast_arguments
decorator takes a list of argument names that will
be broadcast to a common shape (using numpy.broadcast_arrays
) before being
passed to the function.
import numpy as np
from skypy.utils import broadcast_arguments
@broadcast_arguments('a', 'b')
def a_function_of_arrays(a, b):
print(np.block([a, b]))
a = [[1, 2, 3]] # row vector
b = [[4], [5], [6]] # column vector
a_function_of_arrays(a, b)
# output: [[1 2 3 4 4 4]
# [1 2 3 5 5 5]
# [1 2 3 6 6 6]]
Since broadcast_arguments
requires the final shapes of its arguments, it
should be placed below decorators which modify arguments.
Evaluate dependent arguments¶
Sometimes, the value of one argument (the dependent argument) will be a function other arguments (the independent arguments). Consider the following example to plot a parametric surface:
import numpy as np
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D
def plot(x, y, z):
'''plot the surface given by `z = f(x, y)`'''
fig = plt.figure()
ax = fig.add_subplot(111, projection='3d')
ax.plot_surface(x, y, z)
plt.show()
def f(x, y):
'''the surface function `z = f(x, y)`'''
return np.sin(np.hypot(x, y))
# x and y over a [-5, 5]x[-5, 5] grid
x, y = np.mgrid[-5.0:5.0:0.1, -5.0:5.0:0.1]
# compute surface
z = f(x, y)
# plot surface
plot(x, y, z)
The function plot(x, y, z)
takes three coordinates, where z
is generated by
a function f(x, y)
. In this situation, it is often more convenient to pass
the function f
directly instead of the z
coordinate, which would require
the receiving function to distinguish whether it is given values or a function.
The dependent_argument
decorator handles this situation transparently by
taking the name of one dependent argument and the names of one or more
independent arguments, and computing values if a function is provided for the
dependent argument:
import numpy as np
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D
from skypy.utils import dependent_argument
@dependent_argument('z', 'x', 'y')
def plot(x, y, z):
'''plot the surface given by `z = f(x, y)`'''
fig = plt.figure()
ax = fig.add_subplot(111, projection='3d')
ax.plot_surface(x, y, z)
plt.show()
def f(x, y):
'''the surface function `z = f(x, y)`'''
return np.sin(np.hypot(x, y))
# x and y over a [-5, 5]x[-5, 5] grid
x, y = np.mgrid[-5.0:5.0:0.1, -5.0:5.0:0.1]
# plot surface
plot(x, y, f)
Since dependent_argument
requires the values of all independent arguments, it
should be placed below decorators which modify any of the independent
arguments.
Random sampling (skypy.utils.random
)¶
Random utility module.
This module provides methods to draw from random distributions.
Special functions (skypy.utils.special
)¶
Special functions.
This module computes useful special functions.
Regularized upper incomplete gamma function. |
Reference/API¶
skypy.utils Package¶
This module contains utility functions.
Functions¶
|
Decorator that broadcasts arguments. |
|
Decorator to evaluate a dependent argument. |
|
Decorator to use the Astropy default cosmology if none is given. |
|
Decorator to load spectral data automatically and validate units. |