Theoretical Limits of Star Sensor Accuracy test programs and routines
version 0.4 of November 24, 2019 (fourth public release).

Copyright (C) 2016-2019 INPE - Instituto Nacional de Pesquisas Espaciais.


This package contains source code used to generate most figures and the
results presented in the "THEORETICAL LIMITS OF STAR SENSOR ACCURACY" paper,
plus supporting stellar spectra (from STScI) and some supporting programs.

The scripts and functions used to generate the data in this journal article have
been tested with Matlab R2015b and GNU Octave 5.1.0, on an MS-Windows machine
with 8 GB of RAM. To run these scripts and functions you will need Matlab or
GNU Octave or a compatible environment.


Figures 3, 4 and 5 were generated from script plot_BV_BB_script.m
This script saves the images in PDF format in the "outputs/" folder.

The values 23% for N >= 1, 6.4% for N >= 10 and 0.51% for N >= 100 described
in section 2.9 have been calculated with the script centroidsDistr.m, by
running the script with parameter iota set to 1, 10 and 100, respectively.

The plots shown in Figure 6 (in section 3.2) were generated by running the
plotFig6.m script. These plots are saved in the "outputs/" folder as .pdf files.

The values presented in Table 1 were computed using the calcTable1.m script.

Figure 7, shown in section 3.3 was generated by script plotFig7.m. To run it,
it is necessary to download at least one star catalog. In total, three star
catalogs have been used. They can be downloaded from:

  Hipparcos star catalog:
     hip_main.dat.gz => ftp://cdsarc.u-strasbg.fr/pub/cats/I/239
       To check your download:
           md5sum:  7b50b051364b3f846ba8d6cdf81a4fcb *hip_main.dat.gz
           md5sum:  5775d9f9d2f257420f6647a72556a0d2 *hip_main.dat
              hip_main.dat CRC-32 is 0xC47EF4AF
     Unzip it to the hipparcos/ folder and then run calc_HipBVI.m

  Tycho-2 star catalog:
      https://www.cosmos.esa.int/web/hipparcos/tycho-2   or
      ftp://cdsarc.u-strasbg.fr/pub/cats/I/259  (CDS in Vizier)
    Download tyc2.dat.00.gz to tyc.dat.19.gz, unzip them to the
    tycho2/ folder and run calc_Tycho2.m.

  2-MASS star catalog (with more than 470 million point sources):
     Due to its large size, to prepare it for Figure 7 can take many hours.
     Follow instructions in 2mass/01readme.txt.

Figure 8 was generated from plotFig8.m.


LICENSING:
 All the files in this package, with the exception of those in the "calspec/"
 and "2mass/winutil/" folders are distributed using the 3-clause BSD license
 (also known as the "New BSD License" or "Modified BSD License"),
 this is an OSI approved free open source software license:

   https://opensource.org/licenses/BSD-3-Clause

 See file LICENSE.txt for an explanation for the reasons of selecting this
 license and terms and conditions for use, modification and redistribution.


DESCRIPTION OF FOLDERS AND FILES:

   2mass/        => Functions and scripts for preprocessing the 2MASS
                    point source catalog.
   2mass/winutil => A small program (nosleep) included in this package to
                    prevent Windows from putting the computer into sleep mode
                    during long computations.
   calspec/      => Calibration files from the CALSPEC library.
   hipparcos/    => Folder to place the uncompressed Hipparcos star catalog
                    (file hip_main.dat).
   outputs/      => Figures and intermediate data saved by the scripts and
                    functions described here.
   tycho2/       => Folder to place the uncompressed Tycho-2 star catalog
                    sections (files tyc2.dat.00 to tyc2.dat.19).

   00_readme.txt              => This file.
   Bessell2012.m              => Spectral bands (or passbands) defined by
                                 Bessell (2012), used by plot_BV_BB_script.m.
   calc_2MASS.m               => Computes estimates of the star sensor accuracy
                                 limits using the 2MASS star catalog.
                                 Used by plotFig7.m.
   calc_BlackBody_mags.m      => Computes magnitudes in two spectral bands
                                 (passbands) for black-bodies, through numerical
                                 integration.
                                 Used by calc_star_celb.m, calcTable2.m,
                                 calcTable2_Hip.m, lower_bound_from_2mass.m and
                                 lower_bound_from_starcat.m
   calc_covtrace.m            => Computes the trace of covariance matrices.
                                 Used by plotFig7.m
   calc_equiv_black_bodies.m  => Computes the equivalent black-body models for
                                 each star in a star catalog.
                                 Used by calc_star_celb.m, calcTable2.m,
                                 calcTable2_Hip.m and
                                 lower_bound_from_starcat.m.
   calc_HipBVI.m              => Computes estimates of the star sensor accuracy
                                 limits using the Hipparcos star catalog.
                                 Used by calcTable2.m and plotFig7.m.
   calc_mag.m                 => Computes stellar magnitude in a given spectral
                                 band by numerical integration.
                                 Used by calc_star_celb.m
   calc_star_celb.m           => Computes the lower bound of centroiding error
                                 for a given star.
                                 Used by calcTable1.m and plotFig6.m.
   calc_Tycho2.m              => Computes estimates of the star sensor accuracy
                                 limits using the Tycho-2 star catalog.
                                 Used by plotFig7.m.
   calcFisherMat.m            => Computes the Fisher information from a set of
                                 vectors.
                                 Used by calcTable2.m, calcTable2_Hip.m and
                                 lower_bound_from_starcat.m.
   calcTable1.m               => Computes Table 1 shown in section 3.2 -
                                 "Adequacy of black-body approximation".
   calcTable2.m               => Computes Table 2 shown in section 3.4 -
                                 "Effects of limited FOV on star sensor
                                  accuracy".
   calcTable2_Hip.m           => Lightweight but less accurate version of
                                 calcTable2.m based on the Hipparcos star
                                 catalog.
   centroidsDistr.m           => Used to compute values shown in the phrase
                                 "Numerical tests have shown, assuming that the
                                 centroiding error for exactly N detected
                                 photons follow a Gaussian distribution..." in
                                 section 2.9 - "Lower bound on centroiding error
                                 for single stars" of the research paper.
   dirlist.txt                => A file listing all the files in this package
                                 with their file sizes, CRC-32 and last
                                 modification dates.
   isoctave.m                 => Returns true if running in GNU-Octave.
                                 Used by plotFig6.m, plotFig7.m, plotFig8.m,
                                 plot_BV_BB_script.m, setup_octave_savemat.m
                                 and files in the "2mass/" folder.
   LICENSE.txt                => File describing terms and conditions for
                                 reuse, distribution and modifications.
   loadBands.m                => Returns a structure with the definition of many
                                 spectral bands (in terms of energy response)
                                 and another struct with zero-points.
                                 Used by calc_star_celb.m, calcTable2.m,
                                 calcTable2_Hip.m, lower_bound_from_2mass.m and
                                 lower_bound_from_starcat.m.
   loadConsts.m               => Returns a structure with some physical and
                                 mathematical constants.
                                 Used by calc_star_celb.m, calcTable2.m,
                                 calcTable2_Hip.m, lower_bound_from_2mass.m,
                                 lower_bound_from_starcat.m and
                                 plot_BV_BB_script.m.
   lower_bound_from_2mass.m   => Helper function for calc_2MASS.m, similar to
                                 lower_bound_from_starcat.m.
                                 Used by calc_2MASS.m.
   lower_bound_from_starcat.m => Computes an estimate of the lower bound on star
                                 sensor accuracy, using data from a star catalog
                                 specified by an input parameter.
                                 Used by calc_HipBVI.m, calc_Tycho2.m,
                                 calcTable2.m and calcTable2_Hip.m.
   merge_input_params.m       => Helper function that merges input parameters
                                 in an input argument structure of the
                                 calling function with default parameters
                                 provided by the calling function.
                                 Used by calc_star_celb.m,
                                 lower_bound_from_2mass.m and
                                 lower_bound_from_starcat.m.
   plotFig6.m                 => Plots Figure 6 shown in section 3.2 of the
                                 journal article.
   plotFig7.m                 => Plots Figure 7 shown in section 3.3 of the
                                 journal article.
   plotFig8.m                 => Plots Figure 8 shown in section 3.4 of the
                                 journal article.
   plot_BV_BB_script.m        => Plots figures 3, 4 and 5 shown in section 2.5
                                 of the journal article.
   readHipparcos.m            => Processes the Hipparcos main catalog
                                 (hip_main.dat).
                                 Used by calc_HipBVI.m.
   readTycho2.m               => Processes the Tycho-2 star catalog.
                                 Used by calc_Tycho2.m.
   read_calspec.m             => Function used to read CALSPEC FITS files with
                                 stellar spectra.
                                 Used by calc_star_celb.m, Refmagx_Vega.m,
                                 test_read_calspec_int.m and VegaRefmag.m.
   read_calspec_int.m         => Helper function for read_calspec.m, for systems
                                 without a fitsread function.
                                 Used by read_calspec_int.m and
                                 test_read_calspec_int.m.
   Refmagx_Vega.m             => Computes reference fluxes in a spectral band
                                 using star Vega as a reference.
                                 Used by plot_BV_BB_script.m.
   setup_octave_savemat.m     => Changes default format used when saving .mat
                                 files in GNU-Octave.
                                 Used by calc_2MASS.m, calc_HipBVI.m,
                                 calc_Tycho2.m, calcTable2.m and
                                 calcTable2_Hip.m
   string2double.m            => Converts a string to a scalar real value in
                                 double precision.
                                 Used by readHipparcos.m and readTycho2.m.
   test_read_calspec_int.m    => Used to test correctness of read_calspec_int.m.
   VegaRefmag.m               => Computes reference flux in a spectral band
                                 using star Vega as reference.
                                 Used by calc_star_celb.m,
                                 calcTable2.m, calcTable2_Hip.m,
                                 lower_bound_from_2mass.m and
                                 lower_bound_from_starcat.m.


Release notes:

 v0.4 - 2019-11-24:
   - Included calcTable2.m and calcTable2_Hip.m
   - Updated plotFig7.m and plotFig8.m.

 v0.3 - 2019-11-12:
   - Updating plotFig8 with more up to date star sensors.
   - Replacing ordinate variable in plotFig7.m.
   - Replacing diameter and exposure time in calcTable1.m

 v0.2 - 2019-09-25 => Replacing ordinate variable in plotFig7.m.

 v0.1 - 2019-09-18 => First public release (before peer review).


Acknowledgments:

 The author of this program wishes to express gratitude to the many people
 and institutions that in a way or the other contributed and gave support
 for this research to become a reality, in special, for many people from
 INPE, CNPq, CAPES, AEB, MCTIC and Texas A&M University.
