From 8e68e4a619b4dd1d2b0441ca1a85d87de0312225 Mon Sep 17 00:00:00 2001
From: Gregory Ashton <gregory.ashton@ligo.org>
Date: Mon, 6 Jul 2020 09:52:51 +1000
Subject: [PATCH] Improve the documentation for get_optimal_setup_functions
Closes # 72
---
pyfstat/optimal_setup_functions.py | 41 +++++++++++++++++++++++++++---
1 file changed, 37 insertions(+), 4 deletions(-)
diff --git a/pyfstat/optimal_setup_functions.py b/pyfstat/optimal_setup_functions.py
index 43fd89b..6883788 100644
--- a/pyfstat/optimal_setup_functions.py
+++ b/pyfstat/optimal_setup_functions.py
@@ -18,17 +18,28 @@ def get_optimal_setup(
):
""" Using an optimisation step, calculate the optimal setup ladder
+ The details of the methods are described in Sec Va of arXiv:1802.05450.
+ Here we provide implementation details. All equation numbers refer to
+ arXiv:1802.05450.
+
Parameters
----------
NstarMax : float
+ The ratio of the size at the old coherence time to the new coherence
+ time for each step, see Eq. (31). Larger values allow a more rapid
+ "zoom" of the search space at the cost of convergence. Smaller values
+ are more conservative at the cost of additional computing time. The
+ exact choice should be optimized for the problem in hand, but values
+ of 100-1000 are typically okay.
Nsegs0 : int
The number of segments for the initial step of the ladder
- minStartTime, maxStartTime : int
- GPS times of the start and end time of the search
+ tref, minStartTime, maxStartTime : int
+ GPS times of the reference, start, and end time.
prior : dict
Prior dictionary, each item must either be a fixed scalar value, or
a uniform prior.
- detector_names : list of str
+ detector_names : list or str
+ Names of the detectors to use
Returns
-------
@@ -66,7 +77,29 @@ def get_optimal_setup(
def _get_nsegs_ip1(
nsegs_i, NstarMax, tref, minStartTime, maxStartTime, prior, detector_names
):
- """ Calculate Nsegs_{i+1} given Nsegs_{i} """
+ """ Calculate Nsegs_{i+1} given Nsegs_{i}
+
+ Perform the optimization step to calculate nsegs and i+1 given the setup
+ and i. The "Powell" minimiization method from scipy is used. Below, we give
+ help for parameters unique to _get_nsegs_ip1, for help with other
+ parameters see get_optimal_setup
+
+ Parameters
+ ----------
+ nsegs_i: int
+ The number of segments at step i
+
+ Returns
+ -------
+ nsegs_ip1: int
+ The number of segments at i + 1
+
+ Raises
+ ------
+ ValueError: Optimisation unsuccesful
+ A value error is raised if the optimization step fails
+
+ """
log10NstarMax = np.log10(NstarMax)
log10Nstari = np.log10(
--
GitLab