/***********************CXBN NANO-SAT SIMULATOR*********************************************************/
Lance Simms
LLNL 2012

PURPOSE::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

This software attempts to simulate the orbital propagation and spacecraft 
dynamics of the CXBN.  

Orbital Propagation ---
For the orbital progpagation, it uses the pyephem module.  A TLE supplied in 
the TLE directory determines the orbital parameters of the satellite.  This 
TLE file can be changed on the command line using the --TLE_File keyword.  
The default value is TLE/CXBNTLE.txt.

Spacecraft dynamic ---
For the spacecraft dynamics, it uses code created by Lance Simms at LLNL 
during the year of 2011.  This code consists mainly of a finite-difference 
Euler equation solver.  The inputs to the Euler equation solver are the 
external gravity gradient and aerodynamic torques, along with the applied 
control torques.  These control torques are calculated based upon simulated 
readings from the spacecraft magnetometers, gyros, and solar panels.  

Two central functions for the spacecraft dynamics are:

1. ReturnCoarseSunTorque() - This function computes a torque that is meant 
   to align the z-axis of the spacecraft with the sun pointing vector.  It 
   does not attempt to control the spin rate of the spacecraft.  That 
   component still needs to be written.  

   This function has been ported to the CXBN control software as the 
   function -> SunAcquisitionWithSolarPanels.c

2. ReturnMagFieldAlignTorque () - This function computes a torque that 
   attempts to align the z-axis of the spacecraft with the magnetic field 
   vector during the detumbling phase.  Again, it makes no attempt to 
   control the spin rate of the spacecraft about this axis.

   This function has been ported to the CXBN control software as the 
   function -> Detumble.c

DEPENDENCIES:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

This code assumes a lot of other software installed.  The simplest way to 
make sure that all dependencies are in place is just to install Pyraf.  
To obtain and install Pyraf, visit:

http://www.stsci.edu/institute/software_hardware/pyraf

An installation of pyraf will include all of the sub-dependencies.  In case 
the user does not wish to install Pyraf (highly recommended), here is 
a list of the sub-dependencies that are needed, listed by the directory:

------- SatelliteControl.py (PRIMARY SIMULATION CODE)
* pyephem - http://rhodesmill.org/pyephem/

* numpy - http://numpy.scipy.org/
 
* matplotlib - http://matplotlib.sourceforge.net/

* pylab - http://www.scipy.org/PyLab

* cgkit (included in cgkit subdirectory)

additionally, one must have the following files present (See details below about Magnetic Field)

* CXBNNanoSatSimulation/WMM/wmm (this file can be made using the makefile. I.e. type 'make
  This file can be made using the makefile.  I.e. type (needs gcc and glibtool.  glibtool 
  is default installed on Macs)
  > cd, 'WMM/'
  > make clean
  > make

* CXBNNanoSatSimulation/EGM9615.BIN
  This file can be used as is.

* CXBNNanoSatSimulation/WMM.COF
  This file can be used as is.

---------
Matt Wampler-Doty has also created a number of other pieces of code that may be relevant 
to CXBN...
 
By directory:

  2DWorld - Needs matplotlib, basemap
  archeology - Needs gfortran, pdflatex
  documentation - Needs pdflatex
  World - needs PyOpenGl, pygame, matplotlib
          You can get basemap here: http://sourceforge.net/projects/matplotlib/files/matplotlib-toolkits/basemap-1.0.1/

Ubuntu Installation instructions:
	> sudo apt-get install python-pip libtool gfortran texlive-latex-base python-pygame python-opengl python-numpy
	> sudo pip install matplotlib pyephem http://sourceforge.net/projects/matplotlib/files/matplotlib-toolkits/basemap-1.0.1/basemap-1.0.1.tar.gz/download

TLE::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
The SatelliteControl program uses PyEphem and a user supplied TLE file to propagate the satellite in 
its orbit.  The TLE is located in the ./TLE directory.  By default, the file used is "CXBNTLE.txt".  
To change this, one must go into SatelliteControl and edit the line where this file is opened (i.e. 
change the name of the file to point to another one).

MAGNETIC FIELD:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
The magnetic field is obtained by using the World Magnetic Model (WMM).  The WMM approximates the 
magnetic field at a given latitude, longtidue, and altitude using a spherical harmonic expansion of 
the potential arising from the liquid iron core of the Earth.

SatelliteControl makes a call to CXBN_Utilities to obtain the magnetic field, and CXBN_Utilities 
essentially makes a command line call of 

./WMM/wmm (Latitude) (Longitude) (Altitude) (Time)

This command returns the three components of the magnetic field vector in ECI coordinates, in 
Nanoteslas.  CXBN_Utilities returns the magnetic field in Teslas.

To write out the magnetic field that would be measured in the body frame of the satellite (i.e. 
the body frame) to a file, run the program with the --WriteBField=1 directive.  The file is written 
to 

./Data/BFieldVsTime.txt

And contains the lines

[Time] [B_x] [B_y] [B_z]

where B is in Teslas.  Note that the magnetic field of the Earth is not calculated at each individual 
time step.  This would be way too intensive computationally.  Instead, it is calculated every 
del_t_mag_field seconds.  This value is hard-coded, and is currently set at 0.5 seconds.  The 
magnetic field of the Earth does not change appreciably during this time, even for a satellite 
moving at 5 km/s.

RUNNING THE CODE:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

The CXBN simulator can be executed from the command line as:

./SatelliteControl.py

Note that in order to have this work, one must have python installed at the 
location /usr/stsci/pyssg/Python-2.5.4/bin/python, as is the case if Pyraf 
has been installed.  

If this is not the case, one must change the first line of 
SatelliteControl.py to point to the installation of python on the machine 
being used.

There are many command line options.  Examine the header of SatelliteControl to find out what these 
are and see examples of how to use them.  For instance, to align with the sun, one would type

./SatelliteControl.py --TrackSun=1

OUTPUTS::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

The software generates plots of :

1. The angular velocity vs. time
2. The magnetic field vector (in the spacecraft reference frame) vs. time
   (If the keyword --UseMagTorque == 1)
3. The separation of the z-axis from the sun-pointing vector vs. time
   (If the keyword --TrackSun == 1)

REMAINING STEPS::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

The code is unfinished as it stands.  To examine what has been done, see 

documentation/SatelliteControl.pdf

