The Brane

Important Notes

This section highlights some important aspects of the module.

The first thing to do is load the Brane class and logging module

from scatterbrane import Brane
import logging
logging.basicConfig(level=logging.INFO) # for example

The Brane object holds the parameters for the scattering screen and functions for generating images. To initialize a simulation you contruct an instance of the screen and set parameters

import numpy as np
b = Brane(np.zeros((64,64)),1,nphi=4096,screen_res=5,wavelength=3e-6,r_inner=100)

In this example I have set the source to be empty with a pixel size of 1 microarcsecond. Upon initialization, Brane creates a version of the source image whose pixel size is chosen to match the screen.

Warning

The resolution of the scattered (iss) and source images (isrc) may not match the original resolution element you provided Brane. You should access the property through dx.

So in general, the screen has some resolution size (in km) which you can acces via screen_dx and each pixel in the scattered image is some integer factor of the screen pixel size (ips).

Construction of a Brane instance will check some properties:

  • Is the image resolution approaching the refractive scale? (warning only)
  • Screen covers the source image.
  • Source image is square.
  • Inner turbulence scale is larger than the phase coherence length.
  • Resolution element of the screen is larger than the inner turbulence scale.
  • A screen pixel is smaller than inner turbulence scale.
  • Image is smooth enough to satisfy the approximation for equation 12 in Johnson & Gwinn (2015):
\[V_{\mathrm{src}}\left(\frac{(1+M)r_{\mathrm{inner}}}{\lambda}\right) \ll V_{\mathrm{src}}(0)\]

We can now proceed to generate the phase screen and scatter the source image:

b.generateScreen()
b.scatter()

By default, for anisotropic scattering with some position angle, scatter() rotates the source structure. This may introduce artifacts and reduce performance. See the examples for some ways around this.

Class Methods

class scatterbrane.Brane(model, dx, nphi=4096, screen_res=2, wavelength=0.0013, dpc=8400, rpc=5800, r0='sgra', r_outer=10000000, r_inner=12, alpha='kolmogorov', anisotropy=2.045, pa=78, match_screen_res=False, live_dangerously=False, think_positive=False)

Scattering simulation object.

Parameters:
  • model(n, n) Numpy array of the source image.
  • dx – scalar Resolution element of model in uas.
  • nphi – (optional) (2, ) or scalar Number of pixels in a screen. This may be a tuple specifying the dimensions of a rectangular screen.
  • screen_res – (optional) scalar Size of a screen pixel in units of \(R_0\).
  • wavelength – (optional) scalar Observing wavelength in meters.
  • dpc – (optional) scalar Observer-Source distance in parsecs.
  • rpc – (optional) scalar Observer-Scatterer distance in parsecs.
  • r0 – (optional) scalar Phase coherence length along major axis as preset string or in km.
  • r_outer – (optional) scalar Outer scale of turbulence in units of \(R_0\).
  • r_inner – (optional) scalar Inner scale of turbulence in units of \(R_0\).
  • alpha – (optional) string or scalar Preset string or float to set power-law index for tubulence scaling (e.g., Kolmogorov has \(\alpha= 5/3\))
  • anisotropy – (optional) scalar Anisotropy for screen is the EW / NS elongation.
  • pa – (optional) scalar Orientation of kernel’s major axis, East of North, in degrees.
  • live_dangerously – (optional) bool Skip the parameter checks?
  • think_positive – (optional) bool Should we enforce that the source image has no negative pixel values?
Returns:

An instance of a scattering simulation.

Example:
s = Brane(m,dx,nphi=2**12,screen_res=5.,wavelength=3.0e-3,dpc=8.4e3,rpc=5.8e3)

where s is the class instance, m is the image array, nphi is the number of screen pixels, wavelength is the observing wavelength.

Note

\(R_0\) is the phase coherence length and Sgr A* defaults are from Bower et al. (2006).

chatter()

Print information about the current scattering simulation where many parameters are cast as integers.

generatePhases(seed=None, save_phi=None)

Generate screen phases.

Parameters:
  • seed – (optional) scalar Seed for random number generator
  • save_phi – (optional) string To save the screen, set this to the filename.
readScreen(filename)

Read in screen phases from a file.

Parameters:filename – string File containing the screen phases.
saveSettings(filename)

Save screen settings to a file.

Parameters:filename – string settings filename
scatter(move_pix=0)

Generate the scattered image which is stored in the iss member.

Parameters:move_pix – (optional) int Number of pixels to roll the screen (for time evolution).
setModel(model, dx, think_positive=False)

Set new model for the source.

Parameters:
  • model(n, n) Numpy image array.
  • dx – scalar Pixel size in microarcseconds.
  • think_positive – (optional) bool Should we enforce that the source image has no negative pixel values?