imagine.fields package¶
Subpackages¶
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 aSimulator
without having to evaluate anything on aGrid
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
- grid (imagine.fields.grid.BaseGrid) – Instance of
-
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
- grid (imagine.fields.grid.BaseGrid) – Instance of
-
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:
-
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
¶ Dictionary with all parameter names as keys
-
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'¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
class
imagine.fields.basic_fields.
ConstantThermalElectrons
(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]¶ Bases:
imagine.fields.base_fields.ThermalElectronDensityField
Constant magnetic 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'¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
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'¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
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'¶
-
STOCHASTIC_FIELD
= True¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
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 bydata_description
in unitsfield_units
.Return type:
-
REQ_ATTRS
= ['TYPE', '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
¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
name
¶ Name 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
- grid (imagine.fields.grid.BaseGrid) – Instance of
imagine.fields.field_factory module¶
-
class
imagine.fields.field_factory.
FieldFactory
(*, grid=None, boxsize=None, resolution=None, active_parameters=(), field_kwargs={})[source]¶ Bases:
imagine.tools.class_tools.BaseClass
FieldFactory is designed for generating ensemble of field configuration DIRECTLY and/or handle of field to be conducted by simulators
Through calling the factory, the factory object takes a given set of variable values (can be at any chain point in bayesian analysis) and translates it into physical parameter values, returning a field object with current parameter set.
Example
To include a new Field_Factory, one needs to create a derived class with customized initialization. Below we show an example which is compatible with the
xConstantField
showed in the Fields section of the documentation:@icy class xConstantField_Factory(GeneralFieldFactory): def __init__(self, grid=None, boxsize=None, resolution=None): super().__init__(grid, boxsize, resolution) self.field_class = xConstantField self.default_parameters = {'constantA': 5.0} self.parameter_ranges = {'constantA': [-10., 10.]}
Parameters: - 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
- grid (imagine.fields.BaseGrid or None) – If present, the supplied instance of imagine.fields.BaseGrid is used and the arguments boxsize and resolution are ignored
- field_kwargs (dict) – Any extra keyword arguments that should be used in the field instantiation
-
__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:
-
REQ_ATTRS
= ['FIELD_CLASS', 'DEFAULT_PARAMETERS', 'PRIORS']¶
-
active_parameters
¶ Tuple of parameter names which can vary, not necessary to cover all default parameters
-
default_parameters
¶ Dictionary storing parameter name as entry, default parameter value as content
-
default_variables
¶ A dictionary containing default parameter values converted into default normalized variables (i.e with values scaled to be in the range [0,1]).
-
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.GeneralPrior
.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'¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
class
imagine.fields.test_field.
CosThermalElectronDensityFactory
(*, grid=None, boxsize=None, resolution=None, active_parameters=(), field_kwargs={})[source]¶ Bases:
imagine.fields.field_factory.FieldFactory
Field factory associated with the
CosThermalElectronDensityw
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'¶
-
STOCHASTIC_FIELD
= True¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
class
imagine.fields.test_field.
NaiveGaussianMagneticFieldFactory
(*, grid=None, boxsize=None, resolution=None, active_parameters=(), 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
- grid (imagine.fields.grid.BaseGrid) – Instance of
-
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
- grid (imagine.fields.grid.BaseGrid) – Instance of
-
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:
-
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
¶ Dictionary with all parameter names as keys
-
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'¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
class
imagine.fields.
ConstantThermalElectrons
(grid, *, parameters={}, ensemble_size=None, ensemble_seeds=None, dependencies={})[source]¶ Bases:
imagine.fields.base_fields.ThermalElectronDensityField
Constant magnetic 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'¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
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'¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
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'¶
-
STOCHASTIC_FIELD
= True¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
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 bydata_description
in unitsfield_units
.Return type:
-
REQ_ATTRS
= ['TYPE', '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
¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
name
¶ Name 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
- grid (imagine.fields.grid.BaseGrid) – Instance of
-
class
imagine.fields.
FieldFactory
(*, grid=None, boxsize=None, resolution=None, active_parameters=(), field_kwargs={})[source]¶ Bases:
imagine.tools.class_tools.BaseClass
FieldFactory is designed for generating ensemble of field configuration DIRECTLY and/or handle of field to be conducted by simulators
Through calling the factory, the factory object takes a given set of variable values (can be at any chain point in bayesian analysis) and translates it into physical parameter values, returning a field object with current parameter set.
Example
To include a new Field_Factory, one needs to create a derived class with customized initialization. Below we show an example which is compatible with the
xConstantField
showed in the Fields section of the documentation:@icy class xConstantField_Factory(GeneralFieldFactory): def __init__(self, grid=None, boxsize=None, resolution=None): super().__init__(grid, boxsize, resolution) self.field_class = xConstantField self.default_parameters = {'constantA': 5.0} self.parameter_ranges = {'constantA': [-10., 10.]}
Parameters: - 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
- grid (imagine.fields.BaseGrid or None) – If present, the supplied instance of imagine.fields.BaseGrid is used and the arguments boxsize and resolution are ignored
- field_kwargs (dict) – Any extra keyword arguments that should be used in the field instantiation
-
__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:
-
REQ_ATTRS
= ['FIELD_CLASS', 'DEFAULT_PARAMETERS', 'PRIORS']¶
-
active_parameters
¶ Tuple of parameter names which can vary, not necessary to cover all default parameters
-
default_parameters
¶ Dictionary storing parameter name as entry, default parameter value as content
-
default_variables
¶ A dictionary containing default parameter values converted into default normalized variables (i.e with values scaled to be in the range [0,1]).
-
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.GeneralPrior
.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'¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
class
imagine.fields.
CosThermalElectronDensityFactory
(*, grid=None, boxsize=None, resolution=None, active_parameters=(), field_kwargs={})[source]¶ Bases:
imagine.fields.field_factory.FieldFactory
Field factory associated with the
CosThermalElectronDensityw
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'¶
-
STOCHASTIC_FIELD
= True¶
-
field_checklist
¶ Dictionary with all parameter names as keys
-
-
class
imagine.fields.
NaiveGaussianMagneticFieldFactory
(*, grid=None, boxsize=None, resolution=None, active_parameters=(), 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>}¶
-