GalMag Documentation

This is the documentation of GalMag is a Python package for computing galactic magnetic fields based on mean field dynamo theory.

For a detailed description of the physics, please refer to the code paper.

A quick tour through the functionality and a description of the features and usage of the package can by found in the tutorial jupyter notebook.

galmag

galmag package

Module contents

GalMag - A Python tool for computing realistic galactic magnetic fields

Generates realistic galactic magnetic field based on the dynamo equation

Example

Initializes a B_field object on a uniform cartesian 100x100x100 grid:

from galmag import B_field

box_limits = [[-15, 15],[-15, 15],[-15, 15]] # kpc
box_resolution = [100,100,100]
B = B_field(box_limits, box_resolution)

Adds a disc magnetic field with reversals at 4.7 kpc and 12.25 kpc and a field strength of -3 microgauss close to the Sun:

B.add_disk_field(reversals=[4.7,12.25] ,
                 B_phi_solar_radius=-3, # muG
                 number_of_modes=number_of_modes)

Adds a halo magnetic field with intensity 0.1 microgauss close to the Sun:

B.add_halo_field(halo_ref_Bphi=Bphi_sun)

Each coordinate component of the produced magnetic can then be accessed through the relevant coordinate attributes, e.g.:

B.r_spherical
B.theta

For a quick introduction to usage, please check the tutorial jupyter notebook.

Subpackages

galmag.B_generators package
Submodules
galmag.B_generators.B_generator module
class galmag.B_generators.B_generator.B_generator(grid=None, box=None, resolution=None, grid_type='cartesian', default_parameters={}, dtype=<type 'float'>)[source]

Bases: object

Base class for B-field generators

Note

This class does not work on its own.

get_B_field()[source]
galmag.B_generators.B_generator_disk module
class galmag.B_generators.B_generator_disk.B_generator_disk(grid=None, box=None, resolution=None, grid_type='cartesian', default_parameters={}, dtype=<type 'float'>)[source]

Bases: galmag.B_generators.B_generator.B_generator

Generator for the disk field

Parameters:
  • box (3x2-array_like) – Box limits
  • 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’
  • dtype (numpy.dtype, optional) – Data type used. Default: np.dtype(np.float)
find_B_field(B_phi_ref=-3.0, reversals=None, number_of_modes=0, **kwargs)[source]

Constructs B_field objects for the disk field based on constraints.

Parameters:
  • B_phi_ref (float) – Magnetic field intensity at the reference radius. Default: -3
  • reversals (list_like) – a list containing the r-positions of field reversals over the midplane (units consitent with the grid).
  • number_of_modes (int, optional) – Minimum of modes to be used. NB: modes_count = max(number_of_modes, len(reversals)+1)

Note

Other disc parameters should be specified as keyword arguments.

Returns:The computed disc component.
Return type:B_field_component
get_B_field(**kwargs)[source]

Computes a B_field object containing the specified disk field.

Parameters:disk_modes_normalization (array_like) – array of coefficients for the disc modes

Note

Other disc parameters should be specified as keyword arguments.

Returns:The computed disc component.
Return type:B_field_component
galmag.B_generators.B_generator_halo module
class galmag.B_generators.B_generator_halo.B_generator_halo(grid=None, box=None, resolution=None, grid_type='cartesian', default_parameters={}, dtype=<type 'float'>)[source]

Bases: galmag.B_generators.B_generator.B_generator

Generator for the halo field

Parameters:
  • box (3x2-array_like) – Box limits
  • 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’
  • dtype (numpy.dtype, optional) – Data type used. Default: np.dtype(np.float)
get_B_field(**kwargs)[source]

Constructs a B_field component object containing a solution of the dynamo equation for the halo field.

Module contents
galmag.analysis package
Submodules
galmag.analysis.visualization module
galmag.analysis.visualization.plot_r_z_uniform(B, skipr=3, skipz=5, quiver=True, contour=True, quiver_color='0.25', cmap='viridis', vmin=None, vmax=None, **kwargs)[source]

Plots a r-z slice of the field. Assumes B is created using a cylindrical grid - for a more sophisticated/flexible plotting script which does not rely on the grid structure check the plot_slice.

The plot consists of:
  1. a coloured contourplot of B_phi
  2. quivers showing the x-z projection of the field
Parameters:
  • B (B_field) – a B_field or B_field_component object
  • quiver (bool) – If True, shows quivers. Default True
  • contour (bool) – If True, shows contours. Default: True
  • skipx/skipz (int) – Tweaks the display of quivers (Default: skipz=5, skipr=3)
galmag.analysis.visualization.plot_slice()[source]

Plots slice of arbitrary orientation

Note

Not implemented yet

galmag.analysis.visualization.plot_x_y_uniform(B, skipx=5, skipy=5, iz=0, field_lines=True, quiver=True, contour=True, quiver_color='0.25', cmap='viridis', **kwargs)[source]

Plots a x-y slice of the field. Assumes B is created using a cartesian grid - for a more sophisticated/flexible plotting script which does not rely on the grid structure check the plot_slice.

The plot consists of:
  1. a coloured contourplot of |B|^2
  2. Field lines of the B_x and B_y field
  3. Quivers showing the B_x and B_y field
Parameters:
  • B (B_field) – a B_field or B_field_component object
  • field_lines (bool) – If True, shows field lines. Default: True
  • quiver (bool) – If True, shows quivers. Default True
  • contour (bool) – If True, shows contours. Default: True
  • skipx/skipy (int) – Tweaks the display of quivers (Default: skipx=5, skipy=5)
galmag.analysis.visualization.plot_x_z_uniform(B, skipx=1, skipz=5, iy=0, quiver=True, contour=True, quiver_color='0.25', cmap='viridis', vmin=None, vmax=None, no_colorbar=False, **kwargs)[source]

Plots a x-z slice of the field. Assumes B is created using a cartesian grid - for a more sophisticated/flexible plotting script which does not rely on the grid structure check the plot_slice.

The plot consists of:
  1. a coloured contourplot of B_phi
  2. quivers showing the x-z projection of the field
Parameters:
  • B (B_field) – a B_field or B_field_component object
  • quiver (bool) – If True, shows quivers. Default True
  • contour (bool) – If True, shows contours. Default: True
  • skipx/skipz (int) – Tweaks the display of quivers (Default: skipz=5, skipx=1)
galmag.analysis.visualization.plot_y_z_uniform(B, skipy=5, skipz=5, ix=0, quiver=True, contour=True, quiver_color='0.25', cmap='viridis', vmin=None, vmax=None, **kwargs)[source]

Plots a y-z slice of the field. Assumes B is created using a cartesian grid - for a more sophisticated/flexible plotting script which does not rely on the grid structure check the plot_slice.

The plot consists of:
  1. a coloured contourplot of B_phi
  2. Quivers showing the y-z projection of the field
Parameters:
  • B (B_field) – a B_field or B_field_component object
  • quiver (bool) – If True, shows quivers. Default True
  • contour (bool) – If True, shows contours. Default: True
  • skipy/skipz (int) – Tweaks the display of quivers (Default: skipz=5, skipy=5)
galmag.analysis.visualization.std_setup()[source]

Adjusts matplotlib default settings

Module contents

Submodules

galmag.B_field module

Contains the definition of the B_field and B_field_component classes.

class galmag.B_field.B_field(box, resolution, grid_type='cartesian', dtype=<type 'float'>, **kwargs)[source]

Bases: object

Galactic magnetic field

B_field objects store data for the whole galactic magnetic field.

Individual galactic magnetic field components (e.g. disk or halo) are stored as attributes containing B_field_component objects.

The properties x, y, z, r_spherical, r_cylindrical, theta and phi return the magnetic field along each of these axis. These are actually the sum of all the galactic components available.

A disk or halo component can be added using the add_disk_field and add_halo_field methods.

A custom new magnetic field component can be set using the set_field_component method. Alternatively, the custom component can be added during initialization as an extra keyword (i.e. B_field.set_field_component(name, component) is equivalent to B_field(…, name=component).

Parameters:
  • box (3x2-array_like) – Box limits
  • 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’
  • dtype (numpy.dtype, optional) – Data type used. Default: np.dtype(np.float)
add_disk_field(name='disk', **kwargs)[source]

Includes a disc magnetic field component.

Parameters:
  • name (str, optional) – Name of the disc component. Default value: ‘disk’
  • **kwargs – See galmag.B_generator_disk for the list of disc parameters
add_halo_field(name='halo', **kwargs)[source]
Parameters:
  • name – (Default value = ‘halo’)
  • **kwargs
phi

Azimuthal coordinate component, \(\phi\)

r_cylindrical

Cylindrical radial coordinate component, \(s\)

r_spherical

Spherical radial coordinate component, \(r\)

reset_cache()[source]

Erases cached total field values. Major components as ‘disk’ or ‘halo’ are preserved and coordinate component values will be generated on next time they are called.

set_field_component(name, component)[source]
Parameters:
  • name
  • component
theta

Polar coordinate component, \(\theta\)

x

Horizontal coordinate component, \(x\)

y

Horizontal coordinate component, \(y\)

z

Vertical coordinate component, \(z\)

class galmag.B_field.B_field_component(grid, x=None, y=None, z=None, r_spherical=None, r_cylindrical=None, theta=None, phi=None, copy=True, dtype=dtype('float64'), generator=None, parameters={})[source]

Bases: object

A single galactic magnetic field component.

B_field_component objects store data for a single galactic magnetic field component (e.g. the galactic halo magnetic field).

The properties x, y, z, r_spherical, r_cylindrical, theta and phi return the magnetic field along each of these axis (with any required coordinate transformation being performed on the fly).

Parameters:
  • grid (grid_object) – See :class: galmag.Grid
  • y, z, r_spherical, r_cylindrical, theta, phi (x,) – Values of the magnetic field in coordinates compatible with the grid parameter should be supplied at initialization. Unused coordinates should be set to None. E.g. r_cylindrical=[[..],[..],[..]], z=[[..],[..],[..]], phi=[[..],[..],[..]]
  • copy (bool) – whether a fresh copy of the field data should be made upon initialization. Default: True
phi

Azimuthal coordinate component, \(\phi\)

r_cylindrical

Cylindrical radial coordinate component, \(s\)

r_spherical

Spherical radial coordinate component, \(r\)

set_field_data(name, data, copy=True)[source]

Includes fresh data in a particular component

Parameters:
  • name (str) – Name of the coordinate component
  • data (array_like) – Data
  • copy (bool, optional) – Copy (usual) or reference the data? Default: True.
theta

Polar coordinate component, \(\theta\)

x

Horizontal coordinate component, \(x\)

y

Horizontal coordinate component, \(y\)

z

Vertical coordinate component, \(z\)

galmag.Grid module

Contains the definition of the Grid class.

class galmag.Grid.Grid(box, resolution, grid_type='cartesian')[source]

Bases: object

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

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

Parameters:
  • box (3x2-array_like) – Box limits
  • 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’
coordinates

A dictionary contaning all the coordinates

cos_phi

\(\cos(\phi)\)

cos_theta

\(\cos(\theta)\)

get_prototype(dtype=None)[source]
phi

Azimuthal coordinate, \(\phi\)

r_cylindrical

Cylindrical radial coordinate, \(s\)

r_spherical

Spherical radial coordinate, \(r\)

sin_phi

\(\sin(\phi)\)

sin_theta

\(\sin(\theta)\)

theta

Polar coordinate, \(\theta\)

x

Horizontal coordinate, \(x\)

y

Horizontal coordinate, \(y\)

z

Vertical coordinate, \(z\)

galmag.Observables module

Contains a class for computing a selection of observables

class galmag.Observables.Observables(B_field, default_parameters={}, dtype=<type 'numpy.float64'>, direction=None, **kwargs)[source]

Bases: galmag.B_generators.B_generator.B_generator

Synchrotron emmission and Faraday rotation observables

Class properties compute and return a range of observables computed along the axis specified in the initialization.

Parameters:
  • B_field (B_field) – The magnetic field based on which the observables should be computed. At the moment, only B_field constructed using a uniform cartesian grid is supported
  • direction (str) – The coordinate axis parallel to the line-of-sight (i.e. the axis along which the integrations are performed). Valid values: ‘x’/’edge-on’, ‘y’ or ‘z’/’face-on’.
  • obs_electron_density_function (func) – A function which receives three coordinate arrays r_spherical, theta, phi and returns the electron density
  • obs_cosmic_ray_function (func) – A function which receives three coordinate arrays r_spherical, theta, phi and returns the cosmic ray density
  • obs_wavelength_m (float) – The wavelength of used in the synchrotron emission calculations. Default: 5 cm
  • obs_emissivivty_normalization (float) – Needs to be adjusted
Stokes_I

Stokes parameter I (total emmission)

\[I(\lambda) = \int_{-\infty}^\infty \epsilon(w,\lambda) dw\]

where \(w\) is the specified coordinate axis.

Stokes_Q

Stokes parameter Q

\[Q(\lambda) = \int_{-\infty}^\infty \epsilon(w,\lambda) p_0(w) \cos[2 \psi(w)] dw\]

where \(w\) is the specified coordinate axis.

Stokes_U

Stokes parameter U

\[U(\lambda) = \int_{-\infty}^\infty \epsilon(w,\lambda) p_0(w) \sin[2 \psi(w)] dw\]

where \(w\) is the specified coordinate axis.

electron_density

Thermal electron density evaluated on this grid used for calculations.

This is set through the parameter obs_electron_density_function, chosen during initialization.

get_B_field()[source]

B_field based on which this Observables object was constructed

intrinsic_polarization_angle

Intrinsic polarization angle

\[\psi_0 = \frac{\pi}{2} + \tan^{-1}\left(\frac{B_y}{B_x}\right)\]
intrinsic_polarization_degree

Intrinsic degree of polarization

\[p_0 = \frac{\gamma+1}{\gamma + 7/3}\]
observed_polarization_angle

Observed integrated polarization angle

\[\Psi = \frac{1}{2} \arctan\left(\frac{U}{Q}\right)\]
polarized_intensity

Polarized intensity

\[P = \sqrt{Q^2 + U^2}\]
psi

Polarization angle of radiation emitted at a given depth Faraday rotated over the line of sight.

\[\psi(z) = \psi_0(z) + 0.812\,{\rm rad}\left(\frac{\lambda}{1\,\rm m}\right)^2 \int_z^\infty \left(\frac{n_e(z')}{1\,\rm cm^{-3}}\right) \left(\frac{B_\parallel(z')}{1\,\mu\rm G}\right) \frac{{\rm d} z'}{1\,\rm pc}\]
rotation_measure

Rotation measure

\[RM = (0.812\,{\rm rad\,m}^{-2}) \int \frac{n_e(z)}{1\,\rm cm^{-3}} \frac{B_z}{1\,\mu\rm G} \frac{{\rm d} z}{1\,\rm pc}\]
synchrotron_emissivity

Synchrotron emissivity along a coordinate axis

\[\epsilon = C\, n_{cr} B_\perp^{(\gamma+1)/2)} \lambda^{(\gamma-1)/2}\]
Returns:Syncrotron emmissivity, along a coordinate axis
Return type:3D-d2o

galmag.disk_profiles module

Contains the definitions of the disk rotation curve, radial shear, alpha profile and disk scale height.

galmag.disk_profiles.Clemens_Milky_Way_rotation_curve(R, R_d=1.0, Rsun=8.5, normalize=True)[source]

Rotation curve of the Milky Way obtained by Clemens (1985)

Parameters:
  • R (float or array) – radial coordinate
  • Rsun (float or array) – sun’s radius in kpc. Default: 8.5 kpc
  • R_d (float) – unit of R in kpc [e.g. R_d=(disk radius in kpc) for r=0..1 within the disk]. Default: 1.0
  • normalize (bool) – If True , with result normalized to unit at solar radius, if False, the result will be in km/s for R and Rsun in kpc
Returns:

rotation curve

Return type:

same as R

galmag.disk_profiles.Clemens_Milky_Way_shear_rate(R, R_d=1.0, Rsun=8.5, normalize=True)[source]

Shear rate of the Milky Way based on the rotation curve obtained by Clemens (1985)

Parameters:
  • R (float or array) – radial coordinate
  • Rsun (float or array) – sun’s radius in kpc. Default: 8.5 kpc
  • R_d (float) – unit of R in kpc [e.g. R_d=(disk radius in kpc) for r=0..1 within the disk]. Default: 1.0
  • normalize (bool) – If True , with result normalized to unit at solar radius, if False, the result will be in km/s for R and Rsun in kpc
Returns:

shear rate profile, with

Return type:

same as R

galmag.disk_profiles.Omega(rotation_curve, R, Rsun=8.5, R_d=1.0, normalize=True, **kwargs)[source]

Simple wrapper to avoid making mistakes when using dimensionless (aka normalized) quantities.

galmag.disk_profiles.constant_scale_height(R, h_d=1.0, R_d=1.0, Rsun=8.5)[source]

Constant scale height for testing.

galmag.disk_profiles.constant_shear_rate(R, R_d=1.0, Rsun=8.5, S0=25, normalize=True)[source]

Constant shear for testing.

\[V(R) = cte\]
Parameters:R (float or array) – cylindrical radius
galmag.disk_profiles.exponential_scale_height(R, h_d=1.0, R_HI=5, R_d=1.0, Rsun=8.5)[source]

Exponential disk scale-heigh profile profile

\[h(R)=\exp\left(\frac{R-R_\odot}{R_{\rm sh}}\right)\]
Parameters:
  • R (float or array) – radial coordinate
  • h_d (float) – normalization of the scaleheight. Default: 1.0
  • R_d (float) – unit of R in kpc [e.g. R_d=(disk radius in kpc) for r=0..1 within the disk]. Default: 1.0
  • R_HI (float) – Parameter \(R_{\rm sh}\), characterizes how “flared” the disc is.
  • Rsun (float) – Sun’s radius in kpc. Default: 8.5 kpc
Returns:

scale height normalized to h_d at the solar radius

Return type:

same as R

galmag.disk_profiles.regularize(r, Om, S, r_reg, Om_reg, k=4)[source]

Avoids unphysically large values of Omega and Shear near the origin applying an exponential cutoff on Omega to prevent it.

\[\Omega(r) = \exp\left[-(r_\xi/r)^k\right]\left[ \tilde\Omega(r)-\Omega_\xi\right] + \Omega_\xi\,,\]

and

\[S(r) = e^{-(r_\xi/r)^k}\left\{k\left(\frac{r_\xi}{r}\right)^k\left[\tilde\Omega(r) -\Omega_\xi \right] +\tilde S \right\}\]
Parameters:
  • R (array) – radial coordinate
  • Om (float) – Angular velocity profile
  • r_reg (float) – regularization radius
  • Om_reg (float) – Value of Omega to be used for math:r lesssim r_{reg
  • k (float) – How sharp is the cutoff. Default: 4
galmag.disk_profiles.simple_rotation_curve(R, R_d=1.0, Rsun=8.5, V0=220, normalize=True, fraction=0.029411764705882353)[source]

Simple flat rotation curve

\[V = V_0 \left[1-\exp(-R/(f R_\odot)\right]\]

with fraction \(= f\), Rsun \(= R_\odot\), V0 \(= V_0\)

Parameters:
  • R (float or array) – radial coordinate
  • Rsun (float or array) – sun’s radius in kpc. Default: 8.5 kpc
  • R_d (float) – unit of R in kpc [e.g. R_d=(disk radius in kpc) for r=0..1 within the disk]. Default: 1.0
  • V0 (float) – Circular velocity at infinity (i.e. at the flat part). Default: 220 (km/s)
  • fraction (float) – Fraction of the solar radius at which the profile decays exponentially. Default: 0.03 (i.e. 250 pc for Rsun=8.5).
  • normalize (bool) – If True , with result normalized to unit at solar radius, if False, the result will be in units of V0.
Returns:

rotation curve

Return type:

same as R

galmag.disk_profiles.simple_shear_rate(R, R_d=1.0, Rsun=8.5, V0=220, normalize=True, fraction=0.029411764705882353)[source]

A simple shear rate profile, compatible with the simple_rotation_curve() .

Parameters:
  • R (float or array) – radial coordinate
  • Rsun (float or array) – sun’s radius in kpc. Default: 8.5 kpc
  • R_d (float) – unit of R in kpc [e.g. R_d=(disk radius in kpc) for r=0..1 within the disk]. Default: 1.0
  • V0 (float) – Circular velocity at infinity (i.e. at the flat part). Default: 220 (km/s)
  • fraction (float) – Fraction of the solar radius at which the profile decays exponentially. Default: 0.03 (i.e. 250 pc for Rsun=8.5).
  • normalize (bool) – If True , with result normalized to unit at solar radius, if False, the result will be in km/s for R and Rsun in kpc
Returns:

shear rate

Return type:

same as R

galmag.disk_profiles.solid_body_rotation_curve(R, R_d=1.0, Rsun=8.5, V0=220, normalize=True)[source]

Solid body rotation curve for testing.

\[V(R) = R\]
Parameters:R (float or array) – cylindrical radius

galmag.electron_profiles module

Distributions of electron densities and cosmic ray densities

galmag.electron_profiles.constant_ncr(rho, theta, phi, ncr0=1.0)[source]

Dummy for constant cosmic ray electron density

galmag.electron_profiles.constant_ne(rho, theta, phi, ne0=1.0)[source]

Dummy for constant cosmic ray electron density

galmag.electron_profiles.simple_ne(rho, theta, phi, ne0=1.0, Rs=2.6, R_d=1.0, Rsun=8.5, **kwargs)[source]

Simple electron density profile

Comprises a exponential flared disc.

\[n = n_0 \exp\left[-\frac{r \sin(\theta)-s_\odot}{s_s}\right] \exp\left[\frac{-r \cos(\theta)}{h(s)}\right]\]

where \(h(s)\) is given by galmag.disk_profiles.exponential_scale_height()

Parameters:
  • rho (array) – Spherical radial coordinate, \(r\)
  • theta (array) – Polar coordinate, \(\theta\)
  • phi (array) – Azimuthal coordinate, \(\phi\)
  • ne0 (float) – Number density at Rsun. Default: 1.0
  • R_d (float) – unit of rho in kpc [e.g. R_d=(disk radius in kpc) for r=0..1 within the disk]. Default: 1.0
  • Rs (float) – Scale radius, \(s_s\), of the disc in kpc. Default: 2.6 kpc
  • Rsun (float) – Reference radius, \(s_\odot\), in kpc. Default: 8.5 kpc

galmag.galerkin module

Contains functions which deal with the computation the coefficients associated with a Galerkin expansion of the solution of the mean field dynamo equation.

galmag.galerkin.Galerkin_expansion_coefficients(parameters, return_matrix=False, dtype=<type 'numpy.float64'>)[source]

Calculates the Galerkin expansion coefficients.

First computes the transformation M defined by:

\[M_{ij} = W_{ij}, \text{ for } i \neq j\]
\[M_{ij} = \gamma_j, \text{ for } i=j\]

where:

\[W_{ij} = \int B_j \cdot \hat{W} B_i\]

Then, solves the eigenvalue/eigenvector problem using numpy.linalg.eig() , computing thus all the coefficients \(a_i\) and the growth rates (eigenvalues) \(\Gamma_i\).

Parameters:
  • return_matrix (bool, optional) – If True, the matrix \(W_{ij}\) will be returned as well.
  • p (dict) –
    A dictionary of parameters dictionary of parameters containing the parameters:
    • halo_Galerkin_ngrid -> Number of grid points used in the
      calculation of the Galerkin expansion
    • halo_rotation_function -> a function specifying the halo rotation
      curve
    • halo_alpha_function -> a function specifying the dependence of
      the alpha effect
    • halo_turbulent_induction -> \(R_{\alpha}\)
    • halo_rotation_induction -> \(R_{\omega}\)
    • halo_n_free_decay_modes -> number of free decay modes to be used
      in the expansion
    • halo_symmetric_field -> Symmetric or anti-symmetric field
      solution
    • halo_rotation_characteristic_radius -> turn-over radius of the flat
      rotation curve
    • halo_rotation_characteristic_height -> characteristic z used in some
      rotation curve prescriptions
Returns:

  • val (array) – n-array containing growth rates (the eigenvalues of \(Mij\)).
  • vec (array) – \(a_i\)‘s: nx3 array containing the Galerkin coefficients associated.
  • Wij (array) – The matrix \(W_{ij}\). Only present if return_matrix is True.

galmag.galerkin.perturbation_operator(r, theta, phi, Br, Bt, Bp, Vr, Vt, Vp, alpha, Ra, Ro, dynamo_type='alpha-omega')[source]

Applies the perturbation operator associated with an dynamo to a magnetic field in uniform spherical coordinates.

Parameters:
  • r/B/alpha/V (array) – position vector (not radius!), magnetic field, alpha and rotation curve, respectively, expressed as 3xNxNxN arrays containing the \(r\), \(\theta\) and \(\phi\) components in [0,…], [1,…] and [2,…], respectively.
  • p (dict) – A dictionary of parameters containing ‘Ralpha_h’.
Returns:

A list containing NxNxN arrays corresponding to the 3 components of \(\hat W(\mathbf{B})\)

Return type:

list

galmag.halo_free_decay_modes module

Contains functions to compute the free decay modes of the magnetic of the halo of a galaxy.

They should be accessed through the function get_mode().

galmag.halo_free_decay_modes.get_B_a_1(r, theta, phi, C=0.346, k=3.141592653589793)[source]

Computes the first (pure poloidal) antisymmetric free decay mode. Purely poloidal.

Parameters:
  • r (array_like) – NxNxN array containing azimuthal coordinates.
  • theta (array_like) – NxNxN array containing azimuthal coordinates.
  • phi (array_like) – NxNxN array containing azimuthal coordinates.
  • C (float, optional) – Mode normalization.
  • k (float, optional) – \(k\)
Returns:

List containing three numpy arrays corresponding to: \(B_r\), \(B_\theta\), \(B_\phi\)

Return type:

list

galmag.halo_free_decay_modes.get_B_a_2(r, theta, phi, C=0.25, k=5.763)[source]

Computes the second antisymmetric free decay mode - one of a degenerate pair, with eigenvalue \(\gamma_2=-(5.763)^2\). Purely poloidal.

Parameters:
  • r (array_like) – NxNxN array containing azimuthal coordinates.
  • theta (array_like) – NxNxN array containing azimuthal coordinates.
  • phi (array_like) – NxNxN array containing azimuthal coordinates.
  • C (float, optional) – Mode normalization.
  • k (float, optional) – \(k\)
Returns:

List containing three numpy arrays corresponding to: \(B_r\), \(B_\theta\), \(B_\phi\)

Return type:

list

galmag.halo_free_decay_modes.get_B_a_3(r, theta, phi, C=3.445, k=5.763)[source]

Computes the third antisymmetric free decay mode - one of a degenerate pair, with eigenvalue \(\gamma_2=-(5.763)^2\). Purely toroidal.

Parameters:
  • r (array_like) – NxNxN array containing azimuthal coordinates.
  • theta (array_like) – NxNxN array containing azimuthal coordinates.
  • phi (array_like) – NxNxN array containing azimuthal coordinates.
  • C (float, optional) – Mode normalization.
  • k (float, optional) – \(k\)
Returns:

List containing three numpy arrays corresponding to: \(B_r\), \(B_\theta\), \(B_\phi\)

Return type:

list

galmag.halo_free_decay_modes.get_B_a_4(r, theta, phi, C=0.244, k=6.283185307179586)[source]

Computes the forth antisymmetric free decay mode. Purely poloidal.

Parameters:
  • r (array_like) – NxNxN array containing azimuthal coordinates.
  • theta (array_like) – NxNxN array containing azimuthal coordinates.
  • phi (array_like) – NxNxN array containing azimuthal coordinates.
  • C (float, optional) – Mode normalization.
  • k (float, optional) – \(k\)
Returns:

List containing three numpy arrays corresponding to: \(B_r\), \(B_\theta\), \(B_\phi\)

Return type:

list

galmag.halo_free_decay_modes.get_B_s_1(r, theta, phi, C=0.653646562698, k=4.493409457909)[source]

Computes the first (poloidal) symmetric free decay mode. Purely poloidal.

Parameters:
  • r (array_like) – NxNxN array containing azimuthal coordinates.
  • theta (array_like) – NxNxN array containing azimuthal coordinates.
  • phi (array_like) – NxNxN array containing azimuthal coordinates.
  • C (float, optional) – Mode normalization.
  • k (float, optional) – \(k\)
Returns:

List containing three numpy arrays corresponding to: \(B_r\), \(B_\theta\), \(B_\phi\)

Return type:

list

galmag.halo_free_decay_modes.get_B_s_2(r, theta, phi, C=1.32984358196, k=4.493409457909)[source]

Computes the second symmetric free decay mode (one of a degenerate pair, with eigenvalue gamma_2=-(5.763)^2 . Purely toroidal.

Parameters:
  • r (array_like) – NxNxN array containing azimuthal coordinates.
  • theta (array_like) – NxNxN array containing azimuthal coordinates.
  • phi (array_like) – NxNxN array containing azimuthal coordinates.
  • C (float, optional) – Mode normalization.
  • k (float, optional) – \(k\)
Returns:

List containing three numpy arrays corresponding to: \(B_r\), \(B_\theta\), \(B_\phi\)

Return type:

list

galmag.halo_free_decay_modes.get_B_s_3(r, theta, phi, C=0.0169610298034, k=6.987932000501)[source]

Computes the third symmetric free decay mode. Purely poloidal

Parameters:
  • r (array_like) – NxNxN array containing azimuthal coordinates.
  • theta (array_like) – NxNxN array containing azimuthal coordinates.
  • phi (array_like) – NxNxN array containing azimuthal coordinates.
  • C (float, optional) – Mode normalization.
  • k (float, optional) – \(k\)
Returns:

List containing three numpy arrays corresponding to: \(B_r\), \(B_\theta\), \(B_\phi\)

Return type:

list

galmag.halo_free_decay_modes.get_B_s_4(r, theta, phi, C=0.539789362061, k=6.987932000501)[source]

Computes the fourth symmetric free decay mode. Purely toroidal.

Parameters:
  • r (array_like) – NxNxN array containing azimuthal coordinates.
  • theta (array_like) – NxNxN array containing azimuthal coordinates.
  • phi (array_like) – NxNxN array containing azimuthal coordinates.
  • C (float, optional) – Mode normalization.
  • k (float, optional) – \(k\)
Returns:

List containing three numpy arrays corresponding to: \(B_r\), \(B_\theta\), \(B_\phi\)

Return type:

list

galmag.halo_free_decay_modes.get_mode(r, theta, phi, n_mode, symmetric)[source]

Computes the n_mode’th free decay mode.

(This is actually a wrapper invoking other functions)

Parameters:
  • r (array_like) – NxNxN array containing azimuthal coordinates.
  • theta (array_like) – NxNxN array containing azimuthal coordinates.
  • phi (array_like) – NxNxN array containing azimuthal coordinates.
  • nmode (int) – index of the mode to be computed
  • symmetric – If True, the mode is assumed to be symmetric over the midplane (i.e. quadrupolar). If False the mode is assumed to be antisymmetric (dipolar). If None (or anything else), than the mode is drawn from a mixture of symmetric and antisymmetric modes.

Note

At the moment, only the first 4 symmetric and first 4 antisymmetric modes are available. Later versions will support arbitrary choice of mode.

Returns:List containing three numpy arrays corresponding to: \(B_r\), \(B_\theta\), \(B_\phi\)
Return type:list
class galmag.halo_free_decay_modes.xi_lookup_table(filepath='.xilookup.npy', regenerate=False, **kwargs)[source]

Bases: object

Stores a look-up table of the roots of the equation

\[J_{n-1/2}(\xi_{nl}) J_{n+1/2}(\xi_{nl}) = 0\]

which can be accessed through the method get_xi().

These are related to the decay rates through: \(\gamma_{nl} = -(\xi_{nl})^2\)

which can be access through the method get_gamma().

Parameters:
  • filepath (str) – Path to the file where the lookup table will be stored. Default: ‘.xilookup.npy’
  • regenerate (bool) – If True, the original file on hard disk will be overwritten.
generate_xi_lookup_table(max_n=4, max_l=4, number_of_guesses=150, max_guess=25, save=True)[source]

Produces a (max_n,max_l)-array containing containing the roots of

\[J_{n-1/2}(\xi_{nl}) J_{n+1/2}(\xi_{nl}) = 0\]

These are related to the decay rates through:

\[\gamma_{nl} = -(\xi_{nl})^2\]

The root are found using the mpmath.findroot function. The search for roots supplying findroot with number_of_guesses initial guesses uniformly distributed in the interval [3,max_guess].

Parameters:
  • max_l (max_n,) – Maximum values for n and l in the table. Default: 4
  • number_of_guesses (int) – Number of uniformly distributed guesses. Default 150
  • max_guess (float) – Maximum guess value for root.
  • save – Saves the lookup table to file
Returns:

A (max_n,max_l)-array containing containing the roots of

Return type:

numpy.ndarray

get_gamma(n, l, **kwargs)[source]

Returns the free-decay-mode decay rate, \(\gamma_{nl}\)

Parameters:l (n,) – indices of the free decay mode
Returns:\(\gamma_{nl}\)
Return type:float
get_xi(n, l, regenerate=False, **kwargs)[source]

Computes or reads the root of \(J_{n-1/2}(\xi_{nl}) J_{n+1/2}(\xi_{nl}) = 0\)

Parameters:
  • l (n,) – indices of the free decay mode
  • regenerate – (Default value = False)
  • **kwargs
Returns:

\(\xi_{nl}\)

Return type:

float

galmag.halo_profiles module

GalMag

Contains the definitions of the halo rotation curve and alpha profile.

galmag.halo_profiles.simple_V(rho, theta, phi, r_h=1.0, Vh=220, fraction=0.2, normalize=True, fraction_z=None, legacy=False)[source]

Simple form of the rotation curve to be used for the halo

\[V(r,\theta,\phi) \propto [1-\exp(-r \sin(\theta) / s_v) ]\]

Note

This simple form has no z dependence

Parameters:
  • rho (array) – Spherical radial coordinate, \(r\)
  • theta (array) – Polar coordinate, \(\theta\)
  • phi (array) – Azimuthal coordinate, \(\phi\)
  • fraction – fraction of the halo radius corresponding to the turnover of the rotation curve.
  • r_h – halo radius in the same units as rho. Default: 1.0
  • Vh – Value of the rotation curve at rho=r_h. Default: 220 km/s
  • normalize (bool, optional) – if True, the rotation curve will be normalized to one at rho=r_h
Returns:

List containing three numpy arrays corresponding to: \(V_r\), \(V_\theta\), \(V_\phi\)

Return type:

list

galmag.halo_profiles.simple_V_exp(rho, theta, phi, r_h=1.0, Vh=220, fraction=0.2, fraction_z=0.7333333333333333, normalize=True, legacy=False)[source]

Variation on simple_V which decays exponentially with z

\[V(r,\theta,\phi) \propto (1-\exp(-r \sin(\theta) / s_v)) \exp(-r \cos(\theta)/z_v)\]
Parameters:
  • rho (array) – Spherical radial coordinate, \(r\)
  • theta (array) – Polar coordinate, \(\theta\)
  • phi (array) – Azimuthal coordinate, \(\phi\)
  • fraction – fraction of the halo radius corresponding to the turnover of the rotation curve.
  • fraction_z – fraction of the halo radius corresponding to the characteristic vertical decay length of the rotation
  • r_h – halo radius in the same units as rho. Default: 1.0
  • Vh – Value of the rotation curve at rho=r_h. Default: 220 km/s
  • normalize (bool, optional) – if True, the rotation curve will be normalized to one at rho=r_h
Returns:

List containing three numpy arrays corresponding to: \(V_r\), \(V_\theta\), \(V_\phi\)

Return type:

list

galmag.halo_profiles.simple_V_legacy(rho, theta, phi, r_h=1.0, Vh=220, fraction=0.5, fraction_z=None, normalize=True)[source]

Rotation curve employed in version 0.1 and in the MMath Final Report of James Hollins. Same as simple_V but with a slight change in the way it is normalized.

galmag.halo_profiles.simple_V_linear(rho, theta, phi, r_h=1.0, Vh=220, fraction=0.2, fraction_z=0.7333333333333333, normalize=True, legacy=False)[source]

Variation on simple_V which decays linearly with z, reaching 0 at z=(halo radius), and V_h at z=0

\[V(r,\theta,\phi) \propto [1-\exp(-r \sin(\theta) / s_v)] (1-z/z_v)\]
Parameters:
  • rho (array) – Spherical radial coordinate, \(r\)
  • theta (array) – Polar coordinate, \(\theta\)
  • phi (array) – Azimuthal coordinate, \(\phi\)
  • fraction – fraction of the halo radius corresponding to the turnover of the rotation curve. (s_v = fraction*r_h)
  • fraction_z – fraction of the halo radius controling the “lag” of the rotation curve. (z_v = fraction_z*r_h)
  • r_h – halo radius in the same units as rho. Default: 1.0
  • Vh – Value of the rotation curve at rho=r_h. Default: 220 km/s
  • normalize (bool, optional) – if True, the rotation curve will be normalized to one at rho=r_h
  • Returns – List containing three numpy arrays corresponding to: \(V_r\), \(V_\theta\), \(V_\phi\)
galmag.halo_profiles.simple_alpha(rho, theta, phi, alpha0=1.0)[source]

Simple profile for alpha

\[\alpha(\mathbf{r}) = \alpha_0\cos(\theta)\]
Parameters:
  • rho (array) – Spherical radial coordinate, \(r\)
  • theta (array) – Polar coordinate, \(\theta\)
  • phi (array) – Azimuthal coordinate, \(\phi\)
  • alpha0 (float, optional) – Normalization. Default: 1.0

galmag.util module

Auxiliary functions.

galmag.util.arctan2(B1, B2)[source]

A distributed version of numpy.arctan2

(which works efficiently with a distributed_data_object)

galmag.util.curl_spherical(rr, tt, pp, Br, Bt, Bp, order=2)[source]

Computes the curl of a vector in spherical coordinates.

Parameters:
  • rr/tt/pp (array_like) – NxNxN arrays containing the \(r\), \(\theta\) and \(\phi\) coordinates
  • Br/Bt/Bp (array_like) – NxNxN arrays \(r\), \(\theta\) and \(\phi\) components of the vector in the same coordinate grid.
Returns:

three NxNxN arrays containing the components of the curl.

Return type:

list

galmag.util.derive(V, dx, axis=0, order=2)[source]

Computes the numerical derivative of a function specified over a 3 dimensional uniform grid. Uses second order finite differences.

Obs: extremities will use forward or backwards finite differences.

Parameters:
  • V (array_like) – NxNxN array (either numpy or d2o)
  • dx (float) – grid spacing
  • axis (int) – specifies over which axis the derivative should be performed. Default: 0.
  • order (int) – order of the finite difference method. Default: 2
Returns:

The derivative, dV/dx

Return type:

same as V

galmag.util.distribute_function(f, x)[source]

Evaluates a function f using only local data from the d2o x. After that, collects the data into a single d2o and returns the results. If x is not a d2o, simple evaluates the funtion for x.

galmag.util.simpson(f, r)[source]

Integrates over the last axis

galmag.version module

Stores version number