imagine.fields package

Submodules

imagine.fields.base_fields module

This module contains basic base classes that can be used to include new fields in IMAGINE. The classes found here here correspond to the physical fields most commonly found by members of the IMAGINE community and may be improved in the future.

A brief summary of the module:

  • MagneticField — for models of the galactic/Galactic Magnetic Field, \(\mathbf{B}(\mathbf{r})\)
  • ThermalElectronDensityField — for models of the density of thermal electrons, \(n_e(\mathbf{r})\)
  • CosmicRayElectronDensityField— for models of the density/flux of cosmic ray electrons, \(n_{\rm cr}(\mathbf{r})\)
  • DummyField — allows passing parameters to a Simulator without having to evaluate anything on a Grid

See also IMAGINE Components section of the docs.

class imagine.fields.base_fields.MagneticField(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.field.Field

Base class for the inclusion of new models for magnetic fields. It should be subclassed following the template provided.

For more details, check the Magnetic Fields Section of the documentation.

Parameters:
  • grid (imagine.fields.grid.BaseGrid) – Instance of imagine.fields.grid.BaseGrid containing a 3D grid where the field is evaluated
  • parameters (dict) – Dictionary of full parameter set {name: value}
  • ensemble_size (int) – Number of realisations in field ensemble
  • ensemble_seeds – Random seed(s) for generating random field realisations
TYPE = 'magnetic_field'
UNITS = Unit("uG")
data_description

Summary of what is in each axis of the data array

data_shape

Shape of the field data array

class imagine.fields.base_fields.ThermalElectronDensityField(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.field.Field

Base class for the inclusion of models for spatial distribution of thermal electrons. It should be subclassed following the template provided.

For more details, check the Thermal electrons Section of the documentation.

Parameters:
  • grid (imagine.fields.grid.BaseGrid) – Instance of imagine.fields.grid.BaseGrid containing a 3D grid where the field is evaluated
  • parameters (dict) – Dictionary of full parameter set {name: value}
  • ensemble_size (int) – Number of realisations in field ensemble
  • ensemble_seeds – Random seed(s) for generating random field realisations
TYPE = 'thermal_electron_density'
UNITS = Unit("1 / cm3")
data_description

Summary of what is in each axis of the data array

data_shape

Shape of the field data array

class imagine.fields.base_fields.DummyField(*args, **kwargs)[source]

Bases: imagine.fields.field.Field

Base class for a dummy Field used for sending parameters and settings to specific Simulators rather than computing and storing a physical field.

compute_field(*args, **kwargs)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
get_data(i_realization=0, dependencies={})[source]

Mock evaluation of the dummy field defined by this class.

Parameters:
  • i_realization (int) – Index of the current realization
  • dependencies (dict) – If the dependencies_list is non-empty, a dictionary containing the requested dependencies must be provided.
Returns:

parameters – Dictionary of containing a copy of the Field parameters including an extra entry with the random seed that should be used with the present realization (under the key: ‘random_seed’)

Return type:

dict

PARAMETER_NAMES = None
REQ_ATTRS = ['FIELD_CHECKLIST', 'SIMULATOR_CONTROLLIST']
TYPE = 'dummy'
UNITS = None
data_description

Summary of what is in each axis of the data array

data_shape

Shape of the field data array

field_checklist

Parameters of the dummy field

parameter_names

Parameters of the field

simulator_controllist

Dictionary containing fixed Simulator settings

imagine.fields.basic_fields module

class imagine.fields.basic_fields.ConstantMagneticField(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.MagneticField

Constant magnetic field

The field parameters are: ‘Bx’, ‘By’, ‘Bz’, which correspond to the fixed components \(B_x\), \(B_x\) and \(B_z\).

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'constant_B'
PARAMETER_NAMES = ['Bx', 'By', 'Bz']
class imagine.fields.basic_fields.ConstantThermalElectrons(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.ThermalElectronDensityField

Constant thermal electron density field

The field parameters are: ‘ne’, the number density of thermal electrons

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'constant_TE'
PARAMETER_NAMES = ['ne']
class imagine.fields.basic_fields.ExponentialThermalElectrons(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.ThermalElectronDensityField

Thermal electron distribution in a double exponential disc characterized by a scale-height and a scale-radius, i.e.

..math:

n_e(R) = n_0 e^{-R/R_e} e^{-|z|/h_e}

where \(R\) is the cylindrical radius and \(z\) is the vertical coordinate.

The field parameters are: the ‘central_density’, n_0; ‘scale_radius`, \(R_e\); and ‘scale_height’, \(h_e\).

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'exponential_disc_thermal_electrons'
PARAMETER_NAMES = ['central_density', 'scale_radius', 'scale_height']
class imagine.fields.basic_fields.RandomThermalElectrons(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.ThermalElectronDensityField

Thermal electron densities drawn from a Gaussian distribution

NB This may lead to negative densities depending on the choice of parameters. This may be controlled with the ‘min_ne’ parameter which sets a minimum value for the density field (i.e. any value smaller than the minimum density is set to min_ne).

The field parameters are: ‘mean’, the mean of the distribution; ‘std’, the standard deviation of the distribution; and ‘min_ne’, the aforementioned minimum density. To disable the minimum density requirement, it may be set to NaN.

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'random_thermal_electrons'
PARAMETER_NAMES = ['mean', 'std', 'min_ne']
STOCHASTIC_FIELD = True

imagine.fields.field module

class imagine.fields.field.Field(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.tools.class_tools.BaseClass

This is the base class which can be used to include a completely new field in the IMAGINE pipeline. Base classes for specific physical quantites (e.g. magnetic fields) are already available in the module imagine.fields.basic_fields. Thus, before subclassing GeneralField, check whether a more specialized subclass is not available.

For more details check the Fields section in the documentation.

Parameters:
  • grid (imagine.fields.grid.BaseGrid) – Instance of imagine.fields.grid.BaseGrid containing a 3D grid where the field is evaluated
  • parameters (dict) – Dictionary of full parameter set {name: value}
  • ensemble_size (int) – Number of realisations in field ensemble
  • ensemble_seeds (list) – Random seeds for generating random field realisations
compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
get_data(i_realization=0, dependencies={})[source]

Evaluates the physical field defined by this class.

Parameters:
  • i_realization (int) – If the field is stochastic, this indexes the realization generated. Default value: 0 (i.e. the first realization).
  • dependencies (dict) – If the dependencies_list is non-empty, a dictionary containing the requested dependencies must be provided.
Returns:

field – Array of shape data_shape whose contents are described by data_description in units field_units.

Return type:

astropy.units.quantity.Quantity

REQ_ATTRS = ['TYPE', 'PARAMETER_NAMES', 'NAME', 'UNITS']
data_description

Summary of what is in each axis of the data array

data_shape

Shape of the field data array

dependencies_list

Dependencies on other fields

ensemble_seeds
name

Name of the field

parameter_names

Parameters of the field

parameters

Dictionary containing parameters used for this field.

stochastic_field

True if the field is stochastic or False if the field is deterministic (i.e. the output depends only on the parameter values and not on the seed value). Default value is False if subclass does not override STOCHASTIC_FIELD.

type

Type of the field

units

Physical units of the field

imagine.fields.field_factory module

class imagine.fields.field_factory.FieldFactory(field_class=None, active_parameters=(), default_parameters={}, priors={}, grid=None, boxsize=None, resolution=None, field_kwargs={})[source]

Bases: imagine.tools.class_tools.BaseClass

The FieldFactory object stores all the required information for the Pipeline to generate multiple realisations of a given Field while sampling the parameter space.

To produce a FieldFactory one needs to supply the chosen Field subclass, a list of active parameters, the default values for the parameters (at least for the inactive ones), the a dictionary of Prior objects, containing (at least) all the active parameters, and (if the Field is not a dummy) a Grid object, with the grid where the instances should be evaluated.

Parameters:
  • field_class (imagine.fields.Field) – The field class based on which one wants to create a field factory. A Field object can also be supplied.
  • active_parameters (tuple) – List of parameter to be varied/constrained
  • default_parameters (dict) – Dictionary containing the default values of the inactive parameters
  • priors (dict) – Dictionary containing parameter names as keys and Prior objects as values, for all the active parameters.
  • grid (imagine.fields.grid.Grid) – Grid object that will be used by the fields generated by this field factory
  • field_kwargs (dict) – Initialization keyword arguments to be passed to the fields produced by this factory.
  • boxsize (list/tuple of floats) – The physical size of simulation box (i.e. edges of the box).
  • resolution (list/tuple of ints) – The discretization size in corresponding dimension
__call__(*, variables={}, ensemble_size=None, ensemble_seeds=None)[source]

Takes an active variable dictionary, an ensemble size and a random seed value, translates the active variables to parameter values (updating the default parameter dictionary accordingly) and send this to an instance of the field class.

Parameters:
  • variables (dict) – Dictionary of variables with name and value
  • ensemble_size (int) – Number of instances in a field ensemble
  • ensemble_seeds – seeds for generating random numbers in realising instances in field ensemble if ensemble_seeds is None, field_class initialization will take all seed as 0
Returns:

result_field – a Field object

Return type:

imagine.fields.field.Field

default_parameters

Dictionary storing parameter name as entry, default parameter value as content

field_class

Python class whose instances are produced by the present factory

field_name

Name of the physical field

field_type

Type of physical field.

field_units

Units of physical field.

grid

Instance of imagine.fields.BaseGrid containing a 3D grid where the field is/was evaluated

name
parameter_ranges

Dictionary storing varying range of all default parameters in the form {‘parameter-name’: (min, max)}

priors

A dictionary containing the priors associated with each parameter. Each prior is represented by an instance of imagine.priors.prior.Prior.

To set new priors one can update the priors dictionary using attribution (any missing values will be set to imagine.priors.basic_priors.FlatPrior).

resolution

How many bins on each direction of simulation box

imagine.fields.grid module

Contains the definition of the BaseGrid class and an example of its application: a basic uniform grid.

This was strongly based on GalMag’s Grid class, initially developed by Theo Steininger

class imagine.fields.grid.BaseGrid(box, resolution)[source]

Bases: imagine.tools.class_tools.BaseClass

Defines a 3D grid object for a given choice of box dimensions and resolution.

This is a base class. To create your own grid, you need to subclass BaseGrid and override the method generate_coordinates().

Calling the attributes does the conversion between different coordinate systems automatically (spherical, cylindrical and cartesian coordinates centred at the galaxy centre).

Parameters:
  • box (3x2-array_like) – Box limits
  • resolution (3-array_like) – containing the resolution along each axis.
box

Box limits

Type:3x2-array_like
resolution

Containing the resolution along each axis (the shape of the grid).

Type:3-array_like
generate_coordinates()[source]

Placeholder for method which uses the information in the attributes box and resolution to return a dictionary containing the values of (either) the coordinates (‘x’,’y’,’z’) or (‘r_cylindrical’, ‘phi’,’z’), (‘r_spherical’,’theta’, ‘phi’)

This method is automatically called the first time any coordinate is read.

coordinates

A dictionary contaning all the coordinates

cos_phi

\(\cos(\phi)\)

cos_theta

\(\cos(\theta)\)

phi

Azimuthal coordinate, \(\phi\)

r_cylindrical

Cylindrical radial coordinate, \(s\)

r_spherical

Spherical radial coordinate, \(r\)

shape

The same as resolution

sin_phi

\(\sin(\phi)\)

sin_theta

\(\sin(\theta)\)

theta

Polar coordinate, \(\theta\)

x

Horizontal coordinate, \(x\)

y

Horizontal coordinate, \(y\)

z

Vertical coordinate, \(z\)

class imagine.fields.grid.UniformGrid(box, resolution, grid_type='cartesian')[source]

Bases: imagine.fields.grid.BaseGrid

Defines a 3D grid object for a given choice of box dimensions and resolution. The grid is uniform in the selected coordinate system (which is chosen through the parameter grid_type.

Example

>>> import magnetizer.grid as grid
>>> import astropy.units as u
>>> xlims = [0,4]*u.kpc; ylims = [1,2]*u.kpc; zlims = [1,1]*u.kpc
>>> g = grid.UniformGrid([xlims, ylims, zlims], [5,2,1])
>>> g.x
array([[[0.],[0.]], [[1.],[1.]], [[2.],[2.]], [[3.],[3.]], [[4.],[4.]]])
>>> g.y
array([[[1.], [2.]], [[1.], [2.]], [[1.], [2.]], [[1.], [2.]], [[1.], [2.]]])

Calling the attributes does the conversion between different coordinate systems automatically.

Parameters:
  • box (3x2-array_like) – Box limits. Each row corresponds to a different coordinate and should contain units. For ‘cartesian’ grid_type, the rows should contain (in order)’x’,’y’ and ‘z’. For ‘cylindrical’ they should have ‘r_cylindrical’, ‘phi’ and ‘z’. for ‘spherical’, ‘r_spherical’,’theta’ and ‘phi’.
  • resolution (3-array_like) – containing the resolution along each axis.
  • grid_type (str, optional) – Choice between ‘cartesian’, ‘spherical’ and ‘cylindrical’ uniform coordinate grids. Default: ‘cartesian’
generate_coordinates()[source]

This method is automatically called internally the first time any coordinate is requested.

Generates a uniform grid based on the attributes box, resolution and grid_type and returns it in a dictionary.

Returns:coordinates_dict – Dictionary containing the keys (‘x’,’y’,’z’) if grid_type is ‘cartesian`, (‘r_cylindrical’, ‘phi’,’z’) if grid_type is spherical, and (‘r_spherical’,’theta’, ‘phi’) if grid_type is ‘cylindrical`.
Return type:dict

imagine.fields.test_field module

class imagine.fields.test_field.CosThermalElectronDensity(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.ThermalElectronDensityField

Toy model for naively oscilating thermal electron distribution following:

\[n_e(x,y,z) = n_0 [1+\cos (a x + \alpha)][1+\cos (b y + \beta)][1+\cos(c y + \gamma)]\]

The field parameters are: ‘n0’, which corresponds to \(n_0\); and ‘a’, ‘b’, ‘c’, ‘alpha’, ‘beta’, ‘gamma’, which are \(a\), \(b\), \(c\), \(\alpha\), \(\beta\), \(\gamma\), respectively.

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'cos_therm_electrons'
PARAMETER_NAMES = ['n0', 'a', 'alpha', 'b', 'beta', 'c', 'gamma']
class imagine.fields.test_field.CosThermalElectronDensityFactory(field_class=None, active_parameters=(), default_parameters={}, priors={}, grid=None, boxsize=None, resolution=None, field_kwargs={})[source]

Bases: imagine.fields.field_factory.FieldFactory

Field factory associated with the CosThermalElectronDensity class

FIELD_CLASS

alias of CosThermalElectronDensity

DEFAULT_PARAMETERS = {'a': <Quantity 0. rad / kpc>, 'alpha': <Quantity 0. rad>, 'b': <Quantity 0. rad / kpc>, 'beta': <Quantity 0. rad>, 'c': <Quantity 0. rad / kpc>, 'gamma': <Quantity 0. rad>, 'n0': <Quantity 1. 1 / cm3>}
PRIORS = {'a': <imagine.priors.basic_priors.FlatPrior object>, 'alpha': <imagine.priors.basic_priors.FlatPrior object>, 'b': <imagine.priors.basic_priors.FlatPrior object>, 'beta': <imagine.priors.basic_priors.FlatPrior object>, 'c': <imagine.priors.basic_priors.FlatPrior object>, 'gamma': <imagine.priors.basic_priors.FlatPrior object>, 'n0': <imagine.priors.basic_priors.FlatPrior object>}
d = <imagine.priors.basic_priors.FlatPrior object>
k = <imagine.priors.basic_priors.FlatPrior object>
class imagine.fields.test_field.NaiveGaussianMagneticField(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.MagneticField

Toy model for naive Gaussian random field for testing.

The values of each of the magnetic field components are individually drawn from a Gaussian distribution with mean ‘a0’ and standard deviation ‘b0’.

Warning: divergence may be non-zero!

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'naive_gaussian_magnetic_field'
PARAMETER_NAMES = ['a0', 'b0']
STOCHASTIC_FIELD = True
class imagine.fields.test_field.NaiveGaussianMagneticFieldFactory(field_class=None, active_parameters=(), default_parameters={}, priors={}, grid=None, boxsize=None, resolution=None, field_kwargs={})[source]

Bases: imagine.fields.field_factory.FieldFactory

Field factory associated with the NaiveGaussianMagneticField class

FIELD_CLASS

alias of NaiveGaussianMagneticField

DEFAULT_PARAMETERS = {'a0': <Quantity 1. uG>, 'b0': <Quantity 0.1 uG>}
PRIORS = {'a0': <imagine.priors.basic_priors.FlatPrior object>, 'b0': <imagine.priors.basic_priors.FlatPrior object>}

Module contents

class imagine.fields.MagneticField(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.field.Field

Base class for the inclusion of new models for magnetic fields. It should be subclassed following the template provided.

For more details, check the Magnetic Fields Section of the documentation.

Parameters:
  • grid (imagine.fields.grid.BaseGrid) – Instance of imagine.fields.grid.BaseGrid containing a 3D grid where the field is evaluated
  • parameters (dict) – Dictionary of full parameter set {name: value}
  • ensemble_size (int) – Number of realisations in field ensemble
  • ensemble_seeds – Random seed(s) for generating random field realisations
TYPE = 'magnetic_field'
UNITS = Unit("uG")
data_description

Summary of what is in each axis of the data array

data_shape

Shape of the field data array

class imagine.fields.ThermalElectronDensityField(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.field.Field

Base class for the inclusion of models for spatial distribution of thermal electrons. It should be subclassed following the template provided.

For more details, check the Thermal electrons Section of the documentation.

Parameters:
  • grid (imagine.fields.grid.BaseGrid) – Instance of imagine.fields.grid.BaseGrid containing a 3D grid where the field is evaluated
  • parameters (dict) – Dictionary of full parameter set {name: value}
  • ensemble_size (int) – Number of realisations in field ensemble
  • ensemble_seeds – Random seed(s) for generating random field realisations
TYPE = 'thermal_electron_density'
UNITS = Unit("1 / cm3")
data_description

Summary of what is in each axis of the data array

data_shape

Shape of the field data array

class imagine.fields.DummyField(*args, **kwargs)[source]

Bases: imagine.fields.field.Field

Base class for a dummy Field used for sending parameters and settings to specific Simulators rather than computing and storing a physical field.

compute_field(*args, **kwargs)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
get_data(i_realization=0, dependencies={})[source]

Mock evaluation of the dummy field defined by this class.

Parameters:
  • i_realization (int) – Index of the current realization
  • dependencies (dict) – If the dependencies_list is non-empty, a dictionary containing the requested dependencies must be provided.
Returns:

parameters – Dictionary of containing a copy of the Field parameters including an extra entry with the random seed that should be used with the present realization (under the key: ‘random_seed’)

Return type:

dict

PARAMETER_NAMES = None
REQ_ATTRS = ['FIELD_CHECKLIST', 'SIMULATOR_CONTROLLIST']
TYPE = 'dummy'
UNITS = None
data_description

Summary of what is in each axis of the data array

data_shape

Shape of the field data array

field_checklist

Parameters of the dummy field

parameter_names

Parameters of the field

simulator_controllist

Dictionary containing fixed Simulator settings

class imagine.fields.ConstantMagneticField(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.MagneticField

Constant magnetic field

The field parameters are: ‘Bx’, ‘By’, ‘Bz’, which correspond to the fixed components \(B_x\), \(B_x\) and \(B_z\).

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'constant_B'
PARAMETER_NAMES = ['Bx', 'By', 'Bz']
class imagine.fields.ConstantThermalElectrons(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.ThermalElectronDensityField

Constant thermal electron density field

The field parameters are: ‘ne’, the number density of thermal electrons

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'constant_TE'
PARAMETER_NAMES = ['ne']
class imagine.fields.ExponentialThermalElectrons(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.ThermalElectronDensityField

Thermal electron distribution in a double exponential disc characterized by a scale-height and a scale-radius, i.e.

..math:

n_e(R) = n_0 e^{-R/R_e} e^{-|z|/h_e}

where \(R\) is the cylindrical radius and \(z\) is the vertical coordinate.

The field parameters are: the ‘central_density’, n_0; ‘scale_radius`, \(R_e\); and ‘scale_height’, \(h_e\).

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'exponential_disc_thermal_electrons'
PARAMETER_NAMES = ['central_density', 'scale_radius', 'scale_height']
class imagine.fields.RandomThermalElectrons(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.ThermalElectronDensityField

Thermal electron densities drawn from a Gaussian distribution

NB This may lead to negative densities depending on the choice of parameters. This may be controlled with the ‘min_ne’ parameter which sets a minimum value for the density field (i.e. any value smaller than the minimum density is set to min_ne).

The field parameters are: ‘mean’, the mean of the distribution; ‘std’, the standard deviation of the distribution; and ‘min_ne’, the aforementioned minimum density. To disable the minimum density requirement, it may be set to NaN.

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'random_thermal_electrons'
PARAMETER_NAMES = ['mean', 'std', 'min_ne']
STOCHASTIC_FIELD = True
class imagine.fields.Field(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.tools.class_tools.BaseClass

This is the base class which can be used to include a completely new field in the IMAGINE pipeline. Base classes for specific physical quantites (e.g. magnetic fields) are already available in the module imagine.fields.basic_fields. Thus, before subclassing GeneralField, check whether a more specialized subclass is not available.

For more details check the Fields section in the documentation.

Parameters:
  • grid (imagine.fields.grid.BaseGrid) – Instance of imagine.fields.grid.BaseGrid containing a 3D grid where the field is evaluated
  • parameters (dict) – Dictionary of full parameter set {name: value}
  • ensemble_size (int) – Number of realisations in field ensemble
  • ensemble_seeds (list) – Random seeds for generating random field realisations
compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
get_data(i_realization=0, dependencies={})[source]

Evaluates the physical field defined by this class.

Parameters:
  • i_realization (int) – If the field is stochastic, this indexes the realization generated. Default value: 0 (i.e. the first realization).
  • dependencies (dict) – If the dependencies_list is non-empty, a dictionary containing the requested dependencies must be provided.
Returns:

field – Array of shape data_shape whose contents are described by data_description in units field_units.

Return type:

astropy.units.quantity.Quantity

REQ_ATTRS = ['TYPE', 'PARAMETER_NAMES', 'NAME', 'UNITS']
data_description

Summary of what is in each axis of the data array

data_shape

Shape of the field data array

dependencies_list

Dependencies on other fields

ensemble_seeds
name

Name of the field

parameter_names

Parameters of the field

parameters

Dictionary containing parameters used for this field.

stochastic_field

True if the field is stochastic or False if the field is deterministic (i.e. the output depends only on the parameter values and not on the seed value). Default value is False if subclass does not override STOCHASTIC_FIELD.

type

Type of the field

units

Physical units of the field

class imagine.fields.FieldFactory(field_class=None, active_parameters=(), default_parameters={}, priors={}, grid=None, boxsize=None, resolution=None, field_kwargs={})[source]

Bases: imagine.tools.class_tools.BaseClass

The FieldFactory object stores all the required information for the Pipeline to generate multiple realisations of a given Field while sampling the parameter space.

To produce a FieldFactory one needs to supply the chosen Field subclass, a list of active parameters, the default values for the parameters (at least for the inactive ones), the a dictionary of Prior objects, containing (at least) all the active parameters, and (if the Field is not a dummy) a Grid object, with the grid where the instances should be evaluated.

Parameters:
  • field_class (imagine.fields.Field) – The field class based on which one wants to create a field factory. A Field object can also be supplied.
  • active_parameters (tuple) – List of parameter to be varied/constrained
  • default_parameters (dict) – Dictionary containing the default values of the inactive parameters
  • priors (dict) – Dictionary containing parameter names as keys and Prior objects as values, for all the active parameters.
  • grid (imagine.fields.grid.Grid) – Grid object that will be used by the fields generated by this field factory
  • field_kwargs (dict) – Initialization keyword arguments to be passed to the fields produced by this factory.
  • boxsize (list/tuple of floats) – The physical size of simulation box (i.e. edges of the box).
  • resolution (list/tuple of ints) – The discretization size in corresponding dimension
__call__(*, variables={}, ensemble_size=None, ensemble_seeds=None)[source]

Takes an active variable dictionary, an ensemble size and a random seed value, translates the active variables to parameter values (updating the default parameter dictionary accordingly) and send this to an instance of the field class.

Parameters:
  • variables (dict) – Dictionary of variables with name and value
  • ensemble_size (int) – Number of instances in a field ensemble
  • ensemble_seeds – seeds for generating random numbers in realising instances in field ensemble if ensemble_seeds is None, field_class initialization will take all seed as 0
Returns:

result_field – a Field object

Return type:

imagine.fields.field.Field

default_parameters

Dictionary storing parameter name as entry, default parameter value as content

field_class

Python class whose instances are produced by the present factory

field_name

Name of the physical field

field_type

Type of physical field.

field_units

Units of physical field.

grid

Instance of imagine.fields.BaseGrid containing a 3D grid where the field is/was evaluated

name
parameter_ranges

Dictionary storing varying range of all default parameters in the form {‘parameter-name’: (min, max)}

priors

A dictionary containing the priors associated with each parameter. Each prior is represented by an instance of imagine.priors.prior.Prior.

To set new priors one can update the priors dictionary using attribution (any missing values will be set to imagine.priors.basic_priors.FlatPrior).

resolution

How many bins on each direction of simulation box

class imagine.fields.BaseGrid(box, resolution)[source]

Bases: imagine.tools.class_tools.BaseClass

Defines a 3D grid object for a given choice of box dimensions and resolution.

This is a base class. To create your own grid, you need to subclass BaseGrid and override the method generate_coordinates().

Calling the attributes does the conversion between different coordinate systems automatically (spherical, cylindrical and cartesian coordinates centred at the galaxy centre).

Parameters:
  • box (3x2-array_like) – Box limits
  • resolution (3-array_like) – containing the resolution along each axis.
box

Box limits

Type:3x2-array_like
resolution

Containing the resolution along each axis (the shape of the grid).

Type:3-array_like
generate_coordinates()[source]

Placeholder for method which uses the information in the attributes box and resolution to return a dictionary containing the values of (either) the coordinates (‘x’,’y’,’z’) or (‘r_cylindrical’, ‘phi’,’z’), (‘r_spherical’,’theta’, ‘phi’)

This method is automatically called the first time any coordinate is read.

coordinates

A dictionary contaning all the coordinates

cos_phi

\(\cos(\phi)\)

cos_theta

\(\cos(\theta)\)

phi

Azimuthal coordinate, \(\phi\)

r_cylindrical

Cylindrical radial coordinate, \(s\)

r_spherical

Spherical radial coordinate, \(r\)

shape

The same as resolution

sin_phi

\(\sin(\phi)\)

sin_theta

\(\sin(\theta)\)

theta

Polar coordinate, \(\theta\)

x

Horizontal coordinate, \(x\)

y

Horizontal coordinate, \(y\)

z

Vertical coordinate, \(z\)

class imagine.fields.UniformGrid(box, resolution, grid_type='cartesian')[source]

Bases: imagine.fields.grid.BaseGrid

Defines a 3D grid object for a given choice of box dimensions and resolution. The grid is uniform in the selected coordinate system (which is chosen through the parameter grid_type.

Example

>>> import magnetizer.grid as grid
>>> import astropy.units as u
>>> xlims = [0,4]*u.kpc; ylims = [1,2]*u.kpc; zlims = [1,1]*u.kpc
>>> g = grid.UniformGrid([xlims, ylims, zlims], [5,2,1])
>>> g.x
array([[[0.],[0.]], [[1.],[1.]], [[2.],[2.]], [[3.],[3.]], [[4.],[4.]]])
>>> g.y
array([[[1.], [2.]], [[1.], [2.]], [[1.], [2.]], [[1.], [2.]], [[1.], [2.]]])

Calling the attributes does the conversion between different coordinate systems automatically.

Parameters:
  • box (3x2-array_like) – Box limits. Each row corresponds to a different coordinate and should contain units. For ‘cartesian’ grid_type, the rows should contain (in order)’x’,’y’ and ‘z’. For ‘cylindrical’ they should have ‘r_cylindrical’, ‘phi’ and ‘z’. for ‘spherical’, ‘r_spherical’,’theta’ and ‘phi’.
  • resolution (3-array_like) – containing the resolution along each axis.
  • grid_type (str, optional) – Choice between ‘cartesian’, ‘spherical’ and ‘cylindrical’ uniform coordinate grids. Default: ‘cartesian’
generate_coordinates()[source]

This method is automatically called internally the first time any coordinate is requested.

Generates a uniform grid based on the attributes box, resolution and grid_type and returns it in a dictionary.

Returns:coordinates_dict – Dictionary containing the keys (‘x’,’y’,’z’) if grid_type is ‘cartesian`, (‘r_cylindrical’, ‘phi’,’z’) if grid_type is spherical, and (‘r_spherical’,’theta’, ‘phi’) if grid_type is ‘cylindrical`.
Return type:dict
class imagine.fields.CosThermalElectronDensity(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.ThermalElectronDensityField

Toy model for naively oscilating thermal electron distribution following:

\[n_e(x,y,z) = n_0 [1+\cos (a x + \alpha)][1+\cos (b y + \beta)][1+\cos(c y + \gamma)]\]

The field parameters are: ‘n0’, which corresponds to \(n_0\); and ‘a’, ‘b’, ‘c’, ‘alpha’, ‘beta’, ‘gamma’, which are \(a\), \(b\), \(c\), \(\alpha\), \(\beta\), \(\gamma\), respectively.

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'cos_therm_electrons'
PARAMETER_NAMES = ['n0', 'a', 'alpha', 'b', 'beta', 'c', 'gamma']
class imagine.fields.CosThermalElectronDensityFactory(field_class=None, active_parameters=(), default_parameters={}, priors={}, grid=None, boxsize=None, resolution=None, field_kwargs={})[source]

Bases: imagine.fields.field_factory.FieldFactory

Field factory associated with the CosThermalElectronDensity class

FIELD_CLASS

alias of CosThermalElectronDensity

DEFAULT_PARAMETERS = {'a': <Quantity 0. rad / kpc>, 'alpha': <Quantity 0. rad>, 'b': <Quantity 0. rad / kpc>, 'beta': <Quantity 0. rad>, 'c': <Quantity 0. rad / kpc>, 'gamma': <Quantity 0. rad>, 'n0': <Quantity 1. 1 / cm3>}
PRIORS = {'a': <imagine.priors.basic_priors.FlatPrior object>, 'alpha': <imagine.priors.basic_priors.FlatPrior object>, 'b': <imagine.priors.basic_priors.FlatPrior object>, 'beta': <imagine.priors.basic_priors.FlatPrior object>, 'c': <imagine.priors.basic_priors.FlatPrior object>, 'gamma': <imagine.priors.basic_priors.FlatPrior object>, 'n0': <imagine.priors.basic_priors.FlatPrior object>}
d = <imagine.priors.basic_priors.FlatPrior object>
k = <imagine.priors.basic_priors.FlatPrior object>
class imagine.fields.NaiveGaussianMagneticField(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]

Bases: imagine.fields.base_fields.MagneticField

Toy model for naive Gaussian random field for testing.

The values of each of the magnetic field components are individually drawn from a Gaussian distribution with mean ‘a0’ and standard deviation ‘b0’.

Warning: divergence may be non-zero!

compute_field(seed)[source]

This should be overridden with a derived class. It must return an array with dimensions compatible with the associated field_type. See documentation.

Should not be used directly (use get_data() instead).

Parameters:seed (int) – If the field is stochastic, this argument allows setting the random number generator seed accordingly.
NAME = 'naive_gaussian_magnetic_field'
PARAMETER_NAMES = ['a0', 'b0']
STOCHASTIC_FIELD = True
class imagine.fields.NaiveGaussianMagneticFieldFactory(field_class=None, active_parameters=(), default_parameters={}, priors={}, grid=None, boxsize=None, resolution=None, field_kwargs={})[source]

Bases: imagine.fields.field_factory.FieldFactory

Field factory associated with the NaiveGaussianMagneticField class

FIELD_CLASS

alias of NaiveGaussianMagneticField

DEFAULT_PARAMETERS = {'a0': <Quantity 1. uG>, 'b0': <Quantity 0.1 uG>}
PRIORS = {'a0': <imagine.priors.basic_priors.FlatPrior object>, 'b0': <imagine.priors.basic_priors.FlatPrior object>}