Skip to main content
`Ctrl`+`K`

# Cosmology

class astropy.cosmology.Cosmology(*, name=None, meta=None)

  Bases: `object`

  Base-class for all Cosmologies.

  Parameters:
    *args

      Arguments into the cosmology; used by subclasses, not this base class.

    name `python:str` or `python:None` (optional, keyword-only)

      The name of the cosmology.

    meta `python:dict` or `python:None` (optional, keyword-only)

      Metadata for the cosmology, e.g., a reference.

    **kwargs

      Arguments into the cosmology; used by subclasses, not this base class.

  Notes

  Class instances are static – you cannot (and should not) change the values of the parameters. That is, all of the above attributes (except meta) are read only.

  For details on how to create performant custom subclasses, see the documentation on Speeding up Integrals in Custom Cosmologies.

  Cosmology subclasses are automatically registered in a global registry and with various I/O methods. To turn off or change this registration, override the `_register_cls` classmethod in the subclass.

  Attributes Summary

  `from_format` | Transform object to a `Cosmology`.
  `is_flat` | Return bool; `True` if the cosmology is flat.
  `meta` |
  `name` | The name of the cosmology realization, e.g. 'Planck2018' or `None`.
  `parameters` | Immutable mapping of the Parameters.
  `read` | Read and parse data to a `Cosmology`.
  `to_format` | Transform this Cosmology to another format.
  `write` | Write this Cosmology object out in the specified format.

  Methods Summary

  `clone`(*[, meta]) | Returns a copy of this object with updated parameters, as specified.
  `is_equivalent`(other, /, *[, format]) | Check equivalence between Cosmologies.

  Attributes Documentation

  from_format

    Transform object to a `Cosmology`.

    This function provides the Cosmology interface to the Astropy unified I/O layer. This allows easily parsing supported data formats using syntax such as:

        >>> from astropy.cosmology import Cosmology
        >>> cosmo1 = Cosmology.from_format(cosmo_mapping, format='mapping')

    When the `from_format` method is called from a subclass the subclass will provide a keyword argument `cosmology=<class>` to the registered parser. The method uses this cosmology class, regardless of the class indicated in the data, and sets parameters’ default values from the class’ signature.

    Get help on the available readers using the `help()` method:

        >>> Cosmology.from_format.help()  # Get help and list supported formats
        >>> Cosmology.from_format.help('<format>')  # Get detailed help on a format
        >>> Cosmology.from_format.list_formats()  # Print list of available formats

    See also: https://docs.astropy.org/en/stable/io/unified.html

    Parameters:
      obj `object`

        The object to parse according to ‘format’

      *args

        Positional arguments passed through to data parser.

      format `python:str` or `python:None`, optional keyword-only

        Object format specifier. For `None` (default) CosmologyFromFormat tries to identify the correct format.

      **kwargs

        Keyword arguments passed through to data parser. Parsers should accept the following keyword arguments:

        - cosmologythe class (or string name thereof) to use / check when

            constructing the cosmology instance.

    Returns:
      out `Cosmology` subclass instance

        `Cosmology` corresponding to `obj` contents.

  is_flat

    Return bool; `True` if the cosmology is flat.

    This is abstract and must be defined in subclasses.

  meta = None
  name = None

    The name of the cosmology realization, e.g. ‘Planck2018’ or `None`.

  parameters = mappingproxy({})

    Immutable mapping of the Parameters.

    If accessed from the class, this returns a mapping of the Parameter objects themselves. If accessed from an instance, this returns a mapping of the values of the Parameters.

  read

    Read and parse data to a `Cosmology`.

    This function provides the Cosmology interface to the Astropy unified I/O layer. This allows easily reading a file in supported data formats using syntax such as:

        >>> from astropy.cosmology import Cosmology
        >>> cosmo1 = Cosmology.read('<file name>')

    When the `read` method is called from a subclass the subclass will provide a keyword argument `cosmology=<class>` to the registered read method. The method uses this cosmology class, regardless of the class indicated in the file, and sets parameters’ default values from the class’ signature.

    Get help on the available readers using the `help()` method:

        >>> Cosmology.read.help()  # Get help reading and list supported formats
        >>> Cosmology.read.help(format='<format>')  # Get detailed help on a format
        >>> Cosmology.read.list_formats()  # Print list of available formats

    See also: https://docs.astropy.org/en/stable/io/unified.html

    Parameters:
      *args

        Positional arguments passed through to data reader. If supplied the first argument is typically the input filename.

      format `python:str` (optional, keyword-only)

        File format specifier.

      **kwargs

        Keyword arguments passed through to data reader.

    Returns:
      out `Cosmology` subclass instance

        `Cosmology` corresponding to file contents.

  to_format

    Transform this Cosmology to another format.

    This function provides the Cosmology interface to the astropy unified I/O layer. This allows easily transforming to supported data formats using syntax such as:

        >>> from astropy.cosmology import Planck18
        >>> Planck18.to_format("mapping")
        {'cosmology': astropy.cosmology.core.FlatLambdaCDM,
         'name': 'Planck18',
         'H0': <Quantity 67.66 km / (Mpc s)>,
         'Om0': 0.30966,
         ...

    Get help on the available representations for `Cosmology` using the `help()` method:

        >>> Cosmology.to_format.help()  # Get help and list supported formats
        >>> Cosmology.to_format.help('<format>')  # Get detailed help on format
        >>> Cosmology.to_format.list_formats()  # Print list of available formats

    Parameters:
      format `python:str`

        Format specifier.

      *args

        Positional arguments passed through to data writer. If supplied the first argument is the output filename.

      **kwargs

        Keyword arguments passed through to data writer.

  write

    Write this Cosmology object out in the specified format.

    This function provides the Cosmology interface to the astropy unified I/O layer. This allows easily writing a file in supported data formats using syntax such as:

        >>> from astropy.cosmology import Planck18
        >>> Planck18.write('<file name>')

    Get help on the available writers for `Cosmology` using the `help()` method:

        >>> Cosmology.write.help()  # Get help writing and list supported formats
        >>> Cosmology.write.help(format='<format>')  # Get detailed help on format
        >>> Cosmology.write.list_formats()  # Print list of available formats

    Parameters:
      *args

        Positional arguments passed through to data writer. If supplied the first argument is the output filename.

      format `python:str` (optional, keyword-only)

        File format specifier.

      **kwargs

        Keyword arguments passed through to data writer.

  Methods Documentation

  clone(*, meta=None, **kwargs)

    Returns a copy of this object with updated parameters, as specified.

    In general this returns an instance of the same class. For some classes (e.g. flat classes like `FlatLambdaCDM`) there are more options, which are documented in the relevant subclass.

    Parameters:
      meta python:mapping or `python:None` (optional, keyword-only)

        Metadata that will update the current metadata.

      **kwargs

        Cosmology parameter (and name) modifications. If any parameter is changed and a new name is not given, the name will be set to “[old name] (modified)”.

    Returns:
      newcosmo `Cosmology` subclass instance

        A new instance of this (or non-flat equivalent) class with updated parameters as specified. If no arguments are given, then a reference to this object is returned instead of a copy.

    Examples

    To make a copy of the `Planck13` cosmology with a different matter density (`Om0`), and a new name:

        >>> from astropy.cosmology import Planck13
        >>> Planck13.clone(name="Modified Planck 2013", Om0=0.35)
        FlatLambdaCDM(name='Modified Planck 2013', H0=<Quantity 67.77 km / (Mpc s)>,
                      Om0=0.35, ...

    If no name is specified, the new name will note the modification.

        >>> Planck13.clone(Om0=0.35).name
        'Planck13 (modified)'

  is_equivalent(other, /, *, format=False)

    Check equivalence between Cosmologies.

    Two cosmologies may be equivalent even if not the same class. For example, an instance of `LambdaCDM` might have \(\Omega_0=1\) and \(\Omega_k=0\) and therefore be flat, like `FlatLambdaCDM`.

    Parameters:
      other `Cosmology` subclass instance, positional-only

        The object to which to compare.

      format bool or `python:None` or `python:str`, optional keyword-only

        Whether to allow, before equivalence is checked, the object to be converted to a |Cosmology|. This allows, e.g. a |Table| to be equivalent to a Cosmology. `False` (default) will not allow conversion. `True` or `None` will, and will use the auto-identification to try to infer the correct format. A `str` is assumed to be the correct format to use when converting. `format` is broadcast to match the shape of `other`. Note that the cosmology arguments are not broadcast against `format`, so it cannot determine the output shape.

    Returns:
      bool

        True if cosmologies are equivalent, False otherwise.

    Examples

    Two cosmologies may be equivalent even if not of the same class. In this examples the `LambdaCDM` has `Ode0` set to the same value calculated in `FlatLambdaCDM`.

        >>> import astropy.units as u
        >>> from astropy.cosmology import LambdaCDM, FlatLambdaCDM
        >>> cosmo1 = LambdaCDM(70 * (u.km/u.s/u.Mpc), 0.3, 0.7)
        >>> cosmo2 = FlatLambdaCDM(70 * (u.km/u.s/u.Mpc), 0.3)
        >>> cosmo1.is_equivalent(cosmo2)
        True

    While in this example, the cosmologies are not equivalent.

        >>> cosmo3 = FlatLambdaCDM(70 * (u.km/u.s/u.Mpc), 0.3, Tcmb0=3 * u.K)
        >>> cosmo3.is_equivalent(cosmo2)
        False

    Also, using the keyword argument, the notion of equivalence is extended to any Python object that can be converted to a |Cosmology|.

        >>> from astropy.cosmology import Planck18
        >>> tbl = Planck18.to_format("astropy.table")
        >>> Planck18.is_equivalent(tbl, format=True)
        True

    The list of valid formats, e.g. the |Table| in this example, may be checked with `Cosmology.from_format.list_formats()`.

    As can be seen in the list of formats, not all formats can be auto-identified by `Cosmology.from_format.registry`. Objects of these kinds can still be checked for equivalence, but the correct format string must be used.

        >>> tbl = Planck18.to_format("yaml")
        >>> Planck18.is_equivalent(tbl, format="yaml")
        True