Package: gwinc
Python Gravitational Wave Interferometer Noise Calculatorpygwincis 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 analyticnoise calculation
functionsfor various sources of noise affecting
detectors (gwinc.noise):quantum noisemirror coating thermal noisemirror substrate thermal noisesuspension fiber thermal noiseseismic noiseNewtonian/gravity-gradient noiseresidual gas noisepygwincis 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 thebudget interfacesection below.pygwincincludes canonical budgets for various well-known current
and future GW detectors (gwinc.ifo):aLIGOA+VoyagerCosmic Explorer 1Cosmic Explorer 2 (Silica)Cosmic Explorer 2 (Silicon)SeeIFO.mdfor the latest CI-generated plots and hdf5 cached
data.Theinspiral_rangepackage can be used to calculate various common "inspiral range"
figures of merit for gravitational wave detector budgets.  See theinspiral rangesection below.usagecommand line interfacepygwincprovides a command line interface that can be used to
calculate and plot the various canonical IFO noise budgets described
above.  For most distributions this should be available viagwincat the command line, orpython3 -m gwincotherwise:$gwincaLIGOOrcustom budgetsmay also be processed by providing
the path to the budget module/package:$gwincpath/to/mybudgetBudget plots can be saved in various formats (.png, .svg, .pdf):$gwinc--saveaLIGO.pngaLIGOOr trace data can be saved to anHDF5file:$gwinc--saveaLIGO.hdf5aLIGOTrace HDF5 files can also be plotted directly:$gwincaLIGO.hdf5The--rangeoption can be used to include the values of various
inspiral ranges for the overall noise in the output.IFO parameters can be manipulated from the command line with the--ifooption:$gwincaLIGO--ifoOptics.SRM.Tunephase=3.14You can also dump the IFO parameters to aYAML-formatted parameter
file:$gwinc--yamlaLIGO>my_aLIGO.yaml
$editmy_aLIGO.yaml
$gwinc-dmy_aLIGO.yamlaLIGOaLIGOmy_aLIGO.yaml
Materials.Coating.Philown5e-053e-05
$gwincmy_aLIGO.yamlStand-alone YAML files assume the nominal'aLIGO' budget
description.The command line interface also includes an "interactive" mode which
provides anIPythonshell for interacting with
a processed budget:$gwinc-iAplus
GWINCinteractiveshell

The'ifo'Structand'trace'dataareavailableforinspection.
Usethe'whos'commandtoviewtheworkspace.

Youmayinteractwiththeplotusingthe'plt'functions,e.g.:

In[.]:plt.title("My Special Budget")In[.]:plt.savefig("mybudget.pdf")In[1]:See command help for more info:$gwinc--helplibrary interfaceFor custom plotting, parameter optimization, etc. all functionality can be
accessed directly through thegwinclibrary interface:>>>importgwinc>>>budget=gwinc.load_budget('aLIGO')>>>trace=budget.run()>>>fig=trace.plot()>>>fig.show()A default frequency array is used, but alternative frequencies can be
provided toload_budget()either in the form of a numpy array:>>>importnumpyasnp>>>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')Theload_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 instantiatedBudgetobject defined
in the specified budget module (seebudget
interfacebelow).  The budgetifogwinc.Structis available in thebudget.ifoattribute.The budgetrun()method calculates all budget noises and the noise
total and returns aBudgetTraceobject withfreq,psd, andasdproperties.  The budget sub-traces are available through a dictionary
(trace['Quantum']) interface and via attributes
(trace.Quantum).The budgetfreqandifoattributes can be updated at run time by
passing them as keyword arguments to therun()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 functionsThepygwincanalytical noise functions are available in thegwinc.noisepackage.  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 pygwincStructobject is designed to hold such
parameters.For instance, thecoating_brownianfunction expects amaterialsstructure as input argument, that holds the various mirror materials
parameters (e.g.materials.Substrate.MirrorY):defcoating_brownian(f,materials,wavelength,wBeam,dOpt):...# extract substructuressub=materials.Substrate...# substrate propertiesYsub=sub.MirrorYgwinc.Structobjectspygwincprovides aStructclass 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 filesThe easiest way to store all budget parameters is in a YAML file.
YAML files can be loaded directly intogwinc.Structobjects via
theStruct.from_file()class method:fromgwincimportStructifo=Struct.from_file('/path/to/ifo.yaml')YAML parameter files can also be given to theload_budget()function
as described above, in which case the base 'aLIGO' budget structure
will be assumed and returned, with the YAML Struct inserted in theBudget.ifoclass attribute.Here are the included ifo.yaml files for all the canonical IFOs:aLIGO.yamlAplus.yamlVoyager.yamlCE1.yamlCE2.yamlTheStruct.from_file()class method can also load MATLAB structs
defined in .mat files, for compatibility withmatgwinc, and MATLAB .m files,
although the later requires the use of thepython MATLAB
engine.budget interfacepygwincprovides a generic noise budget interface,gwinc.nb, that
can be used to define custom noise budgets (it also underlies the
"canonical" budgets included ingwinc.ifo).  Budgets are defined in
a "budget module" which includesBudgetItemdefinitions.BudgetItem classesThegwinc.nbpackage provides threeBudgetItemclasses that can be
inherited to define the various components of a budget:nb.Noise: a noise sourcenb.Calibration: a noise calibrationnb.Budget: a group of noisesThe primary action of aBudgetItemhappens in it'scalc()method.
ForNoiseclasses, thecalcmethod should return the noise PSD at
the specified frequency points.  For theCalibrationclass,calcshould return a frequency response.Budgetclasses should not have
a specialcalcmethod defined as they already know how to calculate
the overall noise from their constituent noises and calibrations.AdditionallyBudgetItems have two other methods,loadandupdate, that can be overridden by the user to handle arbitrary data
processing.  These are useful for creating budgets from "live" dynamic
noise measurements and the like.  The three core methods therefore
are:load(): initial loading of static dataupdate(**kwargs): update data/attributescalc(): return final data arrayGenerally these methods are not called directly.  Instead, theNoiseandBudgetclasses include arunmethod that smartly executes them
in sequence and returns aBudgetTraceobject for the budget.See the built-inBudgetItemdocumentation for more info
(e.g.pydoc3 gwinc.nb.BudgetItem)budget module definitionA budget module is a standard python module (single.pyfile) or
package (directory containing__inti__.pyfile) containingBudgetItemdefinitions describing the various noises and
calibrations of a budget, as well as the overall budget calculation
itself.  Each budget module should include onenb.Budgetclass
definition named after the module name.Here's an example of a budget module namedMyBudget.  It defines twoNoiseclasses and oneCalibrationclass, as well as the overallBudgetclass (nameMyBudgetthat puts them all together):$findMyBudget
MyBudget/
MyBudget/__init__.py
MyBudget/ifo.yaml
$# MyBudget/__init__.pyimportnumpyasnpfromgwincimportnbfromgwincimportnoiseclassSuspensionThermal(nb.Noise):"""Suspension thermal noise"""style=dict(label='Suspension Thermal',color='#ad900d',linestyle='--',)defcalc(self):n=noise.suspensionthermal.suspension_thermal(self.freq,self.ifo.Suspension)return2*nclassMeasuredNoise(nb.Noise):style=dict(label='Measured Noise',color='#838209',linestyle='-',)defload(self):psd,freq=np.loadtxt('/path/to/measured/psd.txt')self.data=self.interpolate(freq,psd)defcalc(self):returnself.dataclassMyCalibration(nb.Calibration):defcalc(self):returnnp.ones_like(self.freq)*1234classMyBudget(nb.Budget):noises=[SuspensionThermal,MeasuredNoise,]calibrations=[MyCalibration,]Thestyleattributes of the variousNoiseclasses define plot
style for the noise.This budget can be loaded with thegwinc.load_budget()function, and
processed as usual with theBudget.run()method:budget=load_budget('/path/to/MyBudget',freq)trace=budget.run()Other than the necessaryfreqinitialization argument that defines
the frequency array, any additional keyword arguments are assigned as
class attributes to the budget object, and to all of it's constituent
sub noises/calibrations/budgets.Note that theSuspensionThermalNoise class above uses thesuspension_thermalanalytic noise calculation function, which takes
a "suspension" Struct as input argument.  In this case, this
suspension Struct is extracted from theself.ifoStruct atself.ifo.Suspension.If a budget module defined as a package includes anifo.yamlparameter filein the package directory, theload_budget()function will automatically load the YAML data into anifogwinc.Structand assign it to thebudget.ifoattribute.The IFOs included ingwinc.ifoprovide examples of the use of the
budget interface (e.g.gwinc.ifo.aLIGO).the "precomp" decoratorTheBudgetItemsupports "precomp" functions that can be used to
calculate common derived values needed in multipleBudgetItems.
They are specified using thenb.precompdecorator applied to theBudgetItem.calc()method.  These functions are executed during theupdate()method call, supplied with the budgetfreqandifoattributes as input arguments.  The execution state of the precomp
functions is cached at the Budget level, to prevent needlessly
re-calculating them multiple times.  For example:fromgwincimportnbdefprecomp_foo(freq,ifo):pc=Struct()...returnpcdefprecomp_bar(freq,ifo):pc=Struct()...returnpcclassNoise0(nb.Noise):@nb.precomp(foo=precomp_foo)defcalc(self,foo):...classNoise1(nb.Noise):@nb.precomp(foo=precomp_foo)@nb.precomp(bar=precomp_bar)defcalc(self,foo,bar):...classMyBudget(nb.Budget):noises=[Noise0,Noise1,]WhenMyBudget.run()is called, all theprecompfunctions will be
executed, e.g.:precomp_foo(self.freq,self.ifo)precomp_bar(self.freq,self.ifo)But theprecomp_foofunction will only be calculated once even
though it's specified as needed by bothNoise0andNoise1.extracting single noise termsThere are various way to extract single noise terms from the Budget
interface.  The most straightforward way is to run the full budget,
and extract the noise data the output traces dictionary:budget=load_budget('/path/to/MyBudget',freq)trace=budget.run()quantum_trace=trace['Quantum']You can also calculate the final calibrated output noise for just a
single term using the Budgetcalc_noise()method:data=budget.calc_noise('Quantum')You can also calculate a noise at it's source, without applying any
calibrations, by using the Budget__getitem__interface to extract
the specific Noise BudgetItem for the noise you're interested in, and
running it'scalc_trace()method directly:data=budget['Quantum'].calc_trace()inspiral rangeTheinspiral_rangepackage can be used to calculate various common "inspiral range"
figures of merit for gravitational wave detector budgets.  Here's an
example of how to use it to calculate the inspiral range of the
baseline 'Aplus' detector:importgwincimportinspiral_rangeimportnumpyasnpfreq=np.logspace(1,3,1000)budget=gwinc.load_budget('Aplus',freq)trace=budget.run()range=inspiral_range.range(freq,trace.psd,m1=30,m2=30,)See theinspiral_rangepackage for more details.