##########################################################################
#   Subaru HDS++ OPE file Editor  (HOE)                                  #
#                         Document file                                  #
#                                                                        # 
#                                                                        # 
#                                  ver 6.0.2  2024/04/03                 # 
#                               Copyright (C) 2003-24 Akito Tajitsu      #
#      Subaru Telescope, National Astronomical Observatory of Japan      #
#                                        akito.tajitsu_at_nao.ac.jp      # 
##########################################################################


### Introduction ###
Subaru HDS++ OPE file Editor (HOE) is a program to prepare observations
on High Dispersion Spectrograph (HDS) and several other instruments of
8.2-m Subaru Telescope, NAOJ.
Its fundamental purpose is to make operation (OPE) files and Service
proposal requests (SHOE) for your observations. Furthermore, it works
as a finding chart (FC) creator,  an Echelle format simulator (EFS),
an exposure time calculator (ETC), and a query tool for archiving databases.

You can download the installers and the source code of this program
via
    http://www.naoj.org/Observing/Instruments/HDS/hoe/
. You can also make a clone of the latest version of its source code
via Git Hub, using
  git clone https://github.com/chimari/hoe.git
in your terminal.


### Current Supported Instruments ###
 - HDS  (High Dispersion Spectrograph)
 - IRCS (Infrared Camera and Spectrograph)
 - HSC  (Hyper Suprime-Cam)
 - IRD  (InfraRedr Soppler)

 (Test support)
 - KOOLS-IFU (Seimei telescope)
 - TriCCS (Seimei Telescope)

### Current Supported Instruments for Service proposal requests ###
 - HDS  (High Dispersion Spectrograph)
 - IRCS (Infrared Camera and Spectrograph)


### Environment ###
This program is running under UNIX OSs with X window systems,
Microsoft Windows (Windows 7 or later), and mac OS (64bit, Mavericks 
or later).

To compile this program from its source code, Gtk+-2.0 development 
environment is necessary at least. (For Win, using msys2).
The latest version of HOE (ver2.x) needs Gtk+-2.x (2.24 or later).
It also requires the libraries and the develop environment for 
 - openssl
 - libssh2
 - libxml2
 - json-c
. The binary version for mac OS and Windows are built under homebrew
and msys2 environment, respectively.
The binary installers for both environment include all of required 
libraries.

If you are using an internet security software (ESET etc.), you may
have problems on HTTP/HTTPS accesses on hoe (stacks, slowness...).
In such cases, please try to add
  C:\Program Files\Subaru Telescope\hoe\hoe.exe  (Win)
  /Applications/hoe.app/Contents/MacOS/hoe-bin   (mac)
to the exclusion list in your security software.

### How to Make (for UNIX, Linux & Solaris) ###
  - Extract archives, go to the extracted directory.

  - (Only if you cloned the source code via GitHub)
    % touch configure configure.ac aclocal.m4 Makefile.am Makefile.in

  - % ./configure

  - % make

Then, an executable file "hoe" should be built.
You can copy this file to other directory as you like.


### Input Text File ###
[1] CSV file
You should prepare target list text files for your observation.

	HD94028     ,105128.1 ,+201639.0 ,2000,  <Comments>
	BD+36 2165  ,111248.0 ,+354343.9 ,2000,  Mv=8.4  Fe/H=-2
	HD97916     ,111554.2 ,+020512.1 ,2000,  Mv=10.2 Fe/H=-2
	BD+51 1696  ,114635.2 ,+505254.7 ,2000   
	BD-13 3442  ,114650.7 ,-140643.5 ,2000,
           .....................

Cammas are the separator of each column.
      (Object Name), (RA), (Dec), (Epoch), <comments (if necessary>
You should write "until sec" of RA/Dec.
(They are regarded as floating point arguments [f09.2, f+010.2 etc.])
You can write some comments in the last column, if you want.

This file can be read from the menu or "-i" option in starting.


[2]OPE file
OPE files for Gen2 system can be available for objects inputs.

   <PARAMETER_LIST>

   TGT_BD44493=OBJECT="BD+44 493" RA=022649.60 DEC=+445746.80 EQUINOX=2000.00
   TGT_HD222304=OBJECT="HD222304" RA=033908.30 DEC=+502818.20 EQUINOX=2000.00
   TGT_HD224544=OBJECT="HD224544" RA=235849.20 DEC=+322254.10 EQUINOX=2000.00
   TGT_HD225132=OBJECT="HD225132" RA=000344.40 DEC=-172009.50 EQUINOX=2000.00
           ....................................

All characters in the object name will be capitalized.


[3] Non-Sidereal Tracking File (TSC format)
Non-Sidereal tracking files for TSC can also be available.
Files must follow the format described in
  https://www.naoj.org/Observing/Telescope/Tracking/NonSidereal/
. You should use "Geocentric" coordinate in TSC files.
They would be automatically converted into topocentric in the program.
When hoe's time and date are out of the range of the tracking 
calculation, the object's coordinate will be displayed with red characters
in the Main Target List TAB.
You can check the orbit of the non-sidereal target in the Finding Chart.


[4] Non-Sidereal Tracking File (JPL HORIZONS format)
hoe can also load NASA JPL HIRIZONS output files.
  https://ssd.jpl.nasa.gov/horizons.cgi
Please note that you should set 
   "Epehmeris Type" = OBSERVER
   "Observer Location" = Geocentric
   "Table Settings" = 1. Astrometric RA & Dec, 20. Observer range
for your input.
Either calendar date or JD is acceptable for date format.
From the main menu, HORIZONS files can be converted into the TSC format.


### Save and Re-edit ###
And all settings of this program can be saved into *.hoe file 
("Save Config" in the menu).
Its very useful to terminate/restart your preparation works.


### Write OPE files ###
HOE can make two types of OPE files.
[1] Base OPE File
  Use "File"-->"Write Base OPE".
  Simple OPE files in which includes a series of observation commands 
  (SetupField and GetObject) for combinations of  all of your targets
  and employed setups.
  If you have many targets and the order is not defined, use this type
  for your observation.

[2] Plan OPE File
  Using Obs. Plan Editor, hoe can create OPE files in which more 
  detailed observation plans are described.
  In this type of OPE files elapsed times are automatically calculated.
  So, this is much better for your actual observation use.
  See the next section how to use it.


### Obs Plan Editor ###
Obs. Plan Editor pops up with "Edit"-->"Obs. Plan Editor".
This Editor calculate elapsed times for all observing tasks,
sunset/rise, and twilight times. So, you should input exact obs date 
in General TAB of the main GUI.

After build your observational plan, please choose "File"->"Write Plan 
OPE" in the menu bar of the editor. Then, an OPE file following
your plan will be created.
You can also save your observing plan description into a text file.


### Magnitude Search ###
After created/loaded your main target list, you can add information for
targets' magnitude in to the list using "Database"-->"Catalog Matching"
(SIMBAD/GSC/PanSTARRS/SDSS/GAIA/2MASS).
When the list has magnitude information,
 - You can list S/N for each target using "Update"-->"Calc. S/N by ETC".
 - SV Filter parameters are automatically set in each SetupFiled command.
 - Automatic Exptime_SV in Obs. Plan Editor.
 - You can create a target list file for PROMS (Subaru Proposal System).
 - You can create a request file for Service proposals.


### Echelle Format Simulator (EFS) for HDS ###
Use "Tool"-->"Echelle Format Simulator".
Its function is the almost same as that of the web version.
If you input your focusing line wavelength information into Line List TAB,
they will be displayed on EFS.
PDF output is also available from EFS GUI.


### Exposure Time Calculator (ETC) for HDS ###
hoe has stand-alone ETC function.
If you input your focusing line wavelength information into Line List TAB,
they will be displayed on ETC.
 - Main menu "Tool"-->"Exposure Time Calculator"
   It is almost same one as that of the web version.
   The result will be displayed into ETC TAB.
 - "View"-->"ETC" button at the bottom of Main Target TAB will calculate
   S/N for the selected target. 
   Mag, Band, and Exptime will be automatically inserted in the pop up
   dialog.
   The result will be displayed into ETC TAB.
 - Main menu "Update"-->"Calc. S/N by ETC" will calculate S/Ns at
   appointed wavelength) for all objects with Mag in Main Target List.
   

### Finding Charts ###
For the selected object in Main target TAB, "View"-->"FC" button will
create finding charts via network.
The result can be written into PDF files.
The proper motions of targets are included in center coordinates of FC.


### Elevation Plot ###
For the selected object in Main target TAB, "View"-->"Plot" button will
create elevation (or azimuth. atmospheric dispersion etc.) plot.
The result can be written into PDF files.


### Database Query ###
The objects loaded into Main Target List can be queried with some 
astronomical databases / archives.
 - "Database"-->"Data Archive List Query"
   Check observed data with SMOKA, HST, ESO, and Gemini data archives.
   The resultant list will be stored into DB/Main Target TAB (for only
   one query limited).
 - "Database"-->"Catalog Matching"
   Check catalog matching with SIMBAD, NED, LAMOST, GSC, PanSTARRS, 
   SDSS, GAIA, and 2MASS databases.
   Basically, the brightest target will be picked up as a counter part
   in the database.
   Proper motions of targets are ignored.
   The resultant list will be stored into DB/Main Target TAB. The results
   for each database can be switched with combo switch at the upper-right
   of the TAB.
   Mags with selected band are added into Main Target List (except for NED
   and LAMOST).


### Upload OPE file to Gen2 ###
You can upload OPE files to the summit Gen2 system directly via this 
program.

You should use this function only inside of STN.
All passwords for proposal IDs used in hoe will be saved in a HOME$/.hoe file
by ASCII text.
Because they are not saved in each *.hoe file, you have to re-enter passwords
after transfered *.hoe files to to other's environment.


### Copyright ###
   The code in this distribution is Copyright 2003-2018 by Akito Tajitsu.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3, or (at your option)
   any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

   In addition, as a special exception, A.Tajitsu gives permission to link 
   this code of this program with the OpenSSL library (or with modified
   versions of OpenSSL that use the same license as OpenSSL), and distribute
   linked combinations including the two. You must obey the GNU General 
   Public License in all respects for all of the code used other than OpenSSL.
   If you modify this file, you may extend this exception to your version of 
   the file, but you are not obligated to do so. If you do not wish to do so,
   delete this exception statement from your version.