Merge branch 'master' into 'master'

updating documentations

See merge request lscsoft/bilby!743

bilby/gw/prior_files/aligned_spins_waveform_tides_off.prior

+chirp_mass = Uniform(name='chirp_mass', minimum=3.56, maximum=3.68)
+mass_ratio = Uniform(name='mass_ratio', minimum=0.05, maximum=1)
+mass_1 = Constraint(name='mass_1', minimum=1.00, maximum=22.0) #optional
+mass_2 = Constraint(name='mass_2', minimum=1.00, maximum=2.95) #optional
+chi_1 = bilby.gw.prior.AlignedSpin(name='chi_1', a_prior=Uniform(minimum=0, maximum=0.5))
+chi_2 = bilby.gw.prior.AlignedSpin(name='chi_2', a_prior=Uniform(minimum=0, maximum=0.05))
+luminosity_distance = bilby.core.prior.PowerLaw(alpha=2, name='luminosity_distance', minimum=1, maximum=750, unit='Mpc')
+ra = Uniform(minimum=0, maximum=2 * np.pi, name='ra',  boundary='periodic')
+dec = Cosine(name='dec')
+cos_theta_jn = Uniform(name='cos_theta_jn', minimum=-1, maximum=1)
+psi = Uniform(name='psi', minimum=0, maximum=np.pi, boundary='periodic')
+phase = Uniform(name='phase', minimum=0, maximum=2 * np.pi, boundary='periodic')

bilby/gw/prior_files/aligned_spins_waveform_tides_on.prior

+chirp_mass = Uniform(name='chirp_mass', minimum=3.56, maximum=3.68)
+mass_ratio = Uniform(name='mass_ratio', minimum=0.05, maximum=1)
+mass_1 = Constraint(name='mass_1', minimum=1.00, maximum=22.0) #optional
+mass_2 = Constraint(name='mass_2', minimum=1.00, maximum=2.95) #optional
+chi_1 = bilby.gw.prior.AlignedSpin(name='chi_1', a_prior=Uniform(minimum=0, maximum=0.5))
+chi_2 = bilby.gw.prior.AlignedSpin(name='chi_2', a_prior=Uniform(minimum=0, maximum=0.05))
+luminosity_distance = bilby.core.prior.PowerLaw(alpha=2, name='luminosity_distance', minimum=1, maximum=750, unit='Mpc')
+ra = Uniform(minimum=0, maximum=2 * np.pi, name='ra',  boundary='periodic')
+dec = Cosine(name='dec')
+cos_theta_jn = Uniform(name='cos_theta_jn', minimum=-1, maximum=1)
+psi = Uniform(name='psi', minimum=0, maximum=np.pi, boundary='periodic')
+phase = Uniform(name='phase', minimum=0, maximum=2 * np.pi, boundary='periodic')
+lambda_1 = Uniform(name='lambda_2', minimum=0, maximum=5000)
+lambda_2 = Uniform(name='lambda_2', minimum=0, maximum=5000)

bilby/gw/prior_files/precessing_spins_waveform_tides_off.prior

+chirp_mass = Uniform(name='chirp_mass', minimum=3.56, maximum=3.68)
+mass_ratio = Uniform(name='mass_ratio', minimum=0.05, maximum=1)
+mass_1 = Constraint(name='mass_1', minimum=1.00, maximum=22.0)
+mass_2 = Constraint(name='mass_2', minimum=1.00, maximum=22.0)
+a_1 = Uniform(name='a_1', minimum=0, maximum=0.89)
+a_2 = Uniform(name='a_2', minimum=0, maximum=0.05)
+tilt_1 = Sine(name='tilt_1')
+tilt_2 = Sine(name='tilt_2')
+phi_12 = Uniform(name='phi_12', minimum=0, maximum=2 * np.pi, boundary='periodic')
+phi_jl = Uniform(name='phi_jl', minimum=0, maximum=2 * np.pi, boundary='periodic')
+luminosity_distance = bilby.gw.prior.UniformComovingVolume(name='luminosity_distance', minimum=1, maximum=750, unit='Mpc')
+ra = Uniform(minimum=0, maximum=2 * np.pi, name='ra',  boundary='periodic')
+dec = Cosine(name='dec')
+cos_theta_jn = Uniform(name='cos_theta_jn', minimum=-1, maximum=1)
+psi = Uniform(name='psi', minimum=0, maximum=np.pi, boundary='periodic')
+phase = Uniform(name='phase', minimum=0, maximum=2 * np.pi, boundary='periodic')

bilby/gw/prior_files/precessing_spins_waveform_tides_on.prior

+chirp_mass = Uniform(name='chirp_mass', minimum=3.56, maximum=3.68)
+mass_ratio = Uniform(name='mass_ratio', minimum=0.05, maximum=1)
+mass_1 = Constraint(name='mass_1', minimum=1.00, maximum=22.0)
+mass_2 = Constraint(name='mass_2', minimum=1.00, maximum=22.0)
+a_1 = Uniform(name='a_1', minimum=0, maximum=0.89)
+a_2 = Uniform(name='a_2', minimum=0, maximum=0.05)
+tilt_1 = Sine(name='tilt_1')
+tilt_2 = Sine(name='tilt_2')
+phi_12 = Uniform(name='phi_12', minimum=0, maximum=2 * np.pi, boundary='periodic')
+phi_jl = Uniform(name='phi_jl', minimum=0, maximum=2 * np.pi, boundary='periodic')
+luminosity_distance = bilby.gw.prior.UniformComovingVolume(name='luminosity_distance', minimum=1, maximum=750, unit='Mpc')
+ra = Uniform(minimum=0, maximum=2 * np.pi, name='ra',  boundary='periodic')
+dec = Cosine(name='dec')
+cos_theta_jn = Uniform(name='cos_theta_jn', minimum=-1, maximum=1)
+psi = Uniform(name='psi', minimum=0, maximum=np.pi, boundary='periodic')
+phase = Uniform(name='phase', minimum=0, maximum=2 * np.pi, boundary='periodic')
+lambda_1 = Uniform(name='lambda_2', minimum=0, maximum=5000)
+lambda_2 = Uniform(name='lambda_2', minimum=0, maximum=5000)

docs/bilby-output.txt

@@ -95,3 +95,11 @@ done via::
    result.save_posterior_samples()
 
 which will generate a file :code:`outdir/label_posterior.txt`.
+
+
+Visualising the results  
+--------------------
+Bilby also provides some useful built-in plotting tools. Some examples on how
+to visualise results using these tools (and  how to extend them) are shown in
+one of the tutorials at `visualising_the_results.ipynb  <https://git.ligo.org/lscsoft/bilby/-/blob/master/examples/tutorials/visualising_the_results.ipynb>`_.
+

docs/prior.txt

@@ -216,3 +216,64 @@ We provide default conversion functions for the BBH and BNS PriorDicts.
 For BBHs this generates all the BBH mass parameters so constraints can be placed on any mass parameters.
 
 For BNSs it also generates the tidal deformability parameters.
+
+-----------------
+Prior Examples 
+-----------------
+
+Here we show some examples of prior files for different waveform families.
+To constrain a certain parameter to a fixed value, you just need:
+
+.. code:: python
+
+  parameter_name = <value>
+
+------
+
+To constrain the prior to a certain range , you can use:
+
+.. code:: python
+
+ parameter_name = Constraint(name='parameter_name', minimum=<value>, maximum=<value>)
+
+------
+
+Note that to activate the tidal effect you need to specify in your configuration
+file:
+
+.. code:: python
+
+ frequency_domain_source_model=lal_binary_neutron_star 
+
+------
+
+
+Aligned spins waveform with tides off
+==============
+
+.. literalinclude:: /../bilby/gw/prior_files/aligned_spins_waveform_tides_off.prior
+
+Aligned spins waveform with tides on
+==============
+
+.. literalinclude:: /../bilby/gw/prior_files/aligned_spins_waveform_tides_on.prior
+
+Precessing spins waveform with tides off
+==============
+
+.. literalinclude:: /../bilby/gw/prior_files/precessing_spins_waveform_tides_off.prior  
+
+Precessing spins waveform with tides on
+==============
+
+.. literalinclude:: /../bilby/gw/prior_files/precessing_spins_waveform_tides_on.prior  
+
+
+-----------------
+Priors using a Jupyter notebook 
+-----------------
+
+Bilby saves as output the prior volume sampled. You might also find useful to
+produce priors directly from a Jupyter notebook. You can have a look at one of
+the Bilby tutorials to check how you define and plot priors in a Jupyter notebook:
+`making_priors.ipynb <https://git.ligo.org/lscsoft/bilby/-/blob/master/examples/tutorials/making_priors.ipynb>`_.