README.md

Python Gravitational Wave Interferometer Noise Calculator

pygwinc is a multi-faceted tool for processing and plotting noise budgets for ground-based gravitational wave detectors. It's primary feature is a collection of mostly analytic noise calculation functions for various sources of noise affecting detectors (gwinc.noise):

• quantum noise
• mirror coating thermal noise
• mirror substrate thermal noise
• suspension fiber thermal noise
• seismic noise
• Newtonian/gravity-gradient noise
• residual gas noise

pygwinc is also a generalized noise budgeting tool (gwinc.nb) that allows users to create arbitrary noise budgets (for any experiment, not just ground-based GW detectors) using measured or analytically calculated data. See the budget interface section below.

pygwinc includes canonical budgets for various well-known current and future GW detectors (gwinc.ifo):

• aLIGO
• A+
• Voyager
• Cosmic Explorer 1
• Cosmic Explorer 2

See IFO.md for the latest CI-generated plots and hdf5 cached data.

The inspiral_range package can be used to calculate various common "inspiral range" figures of merit for gravitational wave detector budgets. See the inspiral range section below.

usage

command line interface

pygwinc provides a command line interface that can be used to calculate and plot the various canonical IFO noise budgets described above, as well as custom noise budgets (see below):

$ python3 -m gwinc aLIGO

Budget plots save/plot hdf5 trace data, and dump budget IFO parameters:

You can play with IFO parameters and see the effects on the budget by dumping the pre-defined parameters to a YAML-formatted parameter file, editing the parameter file, and re-calculating the noise budget:

$ python3 -m gwinc --yaml aLIGO > my_aLIGO.yaml
$ edit my_aLIGO.yaml
$ python3 -m gwinc -d my_aLIGO.yaml aLIGO
                             aLIGO    my_aLIGO.yaml
Materials.Coating.Philown    5e-05            3e-05
$ python3 -m gwinc my_aLIGO.yaml

You can also use the --ifo option to change parameters from the command line:

$ python3 -m gwinc aLIGO --ifo Optics.SRM.Tunephase=3.14

Stand-alone YAML files assume the nominal 'aLIGO' budget description.

Custom budgets may also be processed by providing the path to the budget module/package:

$ python3 -m gwinc path/to/mybudget

The command line interface also includes an "interactive" mode which provides an IPython shell for interacting with a processed budget:

$ python3 -m gwinc -i Aplus
GWINC interactive shell

The 'ifo' Struct and 'trace' data are available for inspection.
Use the 'whos' command to view the workspace.

You may interact with the plot using the 'plt' functions, e.g.:

In [.]: plt.title("My Special Budget")
In [.]: plt.savefig("mybudget.pdf")

In [1]: 

See command help for more info:

$ python3 -m gwinc -h

library interface

For custom plotting, parameter optimization, etc. all functionality can be accessed directly through the gwinc library interface:

>>> import gwinc
>>> budget = gwinc.load_budget('aLIGO')
>>> trace = budget.run()
>>> fig = gwinc.plot_budget(trace)
>>> fig.show()

A default frequency array is used, but alternative frequencies can be provided to load_budget() either in the form of a numpy array:

>>> import numpy as np
>>> freq = np.logspace(1, 3, 1000)
>>> budget = gwinc.load_budget('aLIGO', freq=freq)

or frequency specification string ('FLO:[NPOINTS:]FHI'):

>>> budget = gwinc.load_budget('aLIGO', freq='10:1000:1000')

The load_budget() function takes most of the same inputs as the command line interface (e.g. IFO names, budget module paths, YAML parameter files), and returns the instantiated Budget object defined in the specified budget module (see budget interface below). The budget ifo gwinc.Struct is available in the budget.ifo attribute.

The budget run() method calculates all budget noises and the noise total and returns a BudgetTrace object with freq, psd, and asd properties. The budget sub-traces are available through a dictionary (trace['QuantumVacuum']) interface and via attributes (trace.QuantumVacumm).

The budget freq and ifo attributes can be updated at run time by passing them as keyword arguments to the run() method:

>>> budget = load_budget('aLIGO')
>>> freq = np.logspace(1, 3, 1000)
>>> ifo = Struct.from_file('/path/to/ifo_alt.yaml')
>>> trace = budget.run(freq=freq, ifo=ifo)

noise functions

The pygwinc analytical noise functions are available in the gwinc.noise package. This package includes multiple sub-modules for the different types of noises, e.g. suspensionthermal, coatingthermal, quantum, etc.)

The various noise functions need many different parameters to calculate their noise outputs. Many parameters are expected to be in the form of object attributes of a class-like container that is passed to the calculation function. The pygwinc Struct object is designed to hold such parameters.

For instance, the coating_brownian function expects a materials structure as input argument, that holds the various mirror materials parameters (e.g. materials.Substrate.MirrorY):

def coating_brownian(f, materials, wavelength, wBeam, dOpt):
    ...
    # extract substructures
    sub = materials.Substrate
    ...
    # substrate properties
    Ysub = sub.MirrorY

gwinc.Struct objects

pygwinc provides a Struct class that can hold parameters in attributes and additionally acts like a dictionary, for passing to the noise calculation functions. Structs can be created from dictionaries, or loaded from various file formats (see below).

YAML parameter files

The easiest way to store all budget parameters is in a YAML file. YAML files can be loaded directly into gwinc.Struct objects via the Struct.from_file() class method:

from gwinc import Struct
ifo = Struct.from_file('/path/to/ifo.yaml')

YAML parameter files can also be given to the load_budget() function as described above, in which case the base 'aLIGO' budget structure will be assumed and returned, with the YAML Struct inserted in the Budget.ifo class attribute.

Here are the included ifo.yaml files for all the canonical IFOs:

• aLIGO.yaml
• Aplus.yaml
• Voyager.yaml
• CE1.yaml
• CE2.yaml