README.jp

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


▼はじめに
HDS OPE file Editor (HOE)は、すばる望遠鏡高分散分光器 HDS とその他いくつか
の観測装置を使った観測を準備するためのツールです。観測に使用する観測手順書
(OPE file)またはサービス観測プロポーザル用のリクエストファイル(.shoe)を
天体リストから作成することを主たる目的としています。さらにファインディングチャートの
作成、エシェルフォーマットシミュレータ(EFS)、積分時間計算機(ETC)、他観測所も含めた
アーカイブデータの検索など、観測準備に必要な様々な機能を持ち合わせています。

ハワイ観測所 HDSホームページ
    http://www.naoj.org/Observing/Instruments/HDS/hoe/
にて最新版をダウンロード可能です。
また、ターミナルから以下のコマンド
  git clone https://github.com/chimari/hoe.git
で最新版のsourceクローンをお使いの環境に作成できます。


▼現在サポートしている観測装置
 - HDS (High Dispersion Spectrograph)
 - IRCS (Infrared Camera and Spectrograph)
 - HSC  (Hyper Suprime-Cam)
 - IRD  (InfraRed Doppler)

 (以下テストサポート)
 - KOOLS-IFU (Seimei telescope)
 - TriCCS (Seimei Telescope)

▼サービス観測のリクエストを出力できる観測装置
 - HDS (High Dispersion Spectrograph)
 - IRCS (Infrared Camera and Spectrograph)


▼環境
X Window Systemが稼働しているUNIX環境、もしくは MS Windows/macOS環境
でも利用が可能です。
Win/Mac用にはバイナリー配布をしています。

sourceからコンパイルするためにはGtk+2 (ver2.24以降)の開発環境が必要です。
その他に
 - OpenSSL
 - libssh2
 - libxml2
 - json-c
のライブラリおよびその開発環境がインストールされていることが必要となります。
Windows版msys2, macOSではhomebrewで上記環境を構築しコンパイルしています。
macOS, Windowsのバイナリー配布版には必要なライブラリはすべて同梱されています。

一部のネットワークセキュリテイソフト（ESET等）を使用している環境で、HTTP/HTTPS
を使用したネットワーク経由のデータダウンロードがスタックしたり遅くなってりすることがあります。
その場合は、セキュリティソフトのなかで
  C:\Program Files\Subaru Telescope\hskymon\hoe.exe  (Win)
  /Applications/hskymon.app/Contents/MacOS/hoe-bin   (mac)
を監視から除外するように設定してください。


▼make (linux, Solaris)
  - アーカイブを展開して作成されたディレクトリに移動

  - (git からsourceをクローンしたときのみ)
    % touch configure configure.ac aclocal.m4 Makefile.am Makefile.in

  - % ./configure
         (aclocal関連で文句を言われたら ./autogen.sh  を試してみてください)

  - % make

以上で実行ファイル"hoe"が作成されます。
この実行ファイルのみ(hoe)しか使用しませんので、適当なディレクトリにコピーし
てください。


▼天体リストとして入力できるファイル
[1] CSV(カンマ区切り)ファイル
入力するのは天体の座標リストです。以下のようなフォーマットにしたがった
テキスト形式のファイルを用意してください。

	HD94028     ,105128.1 ,+201639.0 ,2000,  <以下コメント>
	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,
           ………………………………

データはカンマ(,)区切りで、
      天体名, 赤経(RA), 赤緯(Dec), 座標分点, <コメント>
です。
注意するのは、RA/Dec をかならず秒の単位まで書き込むようにしてください。
(f09.2, f+010.2 等の浮動小数点として読み込み処理しています)。
天体名にはスペース等がふくまれても問題はありません。
コメントはあってもなくてもかまいません。ない場合はEpochのあとのカンマ
は必要ないです(あってもかまわない)。

ファイルの読み込みはメニューバーからできます。
また起動時に-iオプションで指定することも可能です。


[2] OPEファイル
Gen2準拠のOPEファイルからターゲットを読み込みできます。

   <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
           ………………………………

というようにパラメータリスト部で天体の定義がされている場合にそれを読み
込む形になります。
(天体名はすべて大文字に変換されます)


[3] Non-Sidereal Tracking File (TSC format)
望遠鏡の非恒星追尾ファイルをマニュアルで読み込むことができます。
ファイルは
  https://www.naoj.org/Observing/Telescope/Tracking/NonSidereal/
に記述に準拠したフォーマットである必要があります。
必ず、"GeoCentric" の座標を読み込むようにしてください。
hoe内部では GeoCentricを観測者基準座標(TopoCentric)に変換して扱います。
計算の範囲外の日時が設定されている場合は、Main Target Listで座標が赤字で
表示されます(範囲内の場合は青)。
Finding Chart上で天体の軌道を表示させることも可能です。


[4] Non-Sidereal Tracking File (JPL HORIZONS format)
TSCフォーマットと同様にNASA JPL の HIRIZONS
  https://ssd.jpl.nasa.gov/horizons.cgi
の出力ファイルを直接読み込むことができます。
必ず、
   "Epehmeris Type" = OBSERVER
   "Observer Location" = Geocentric
   "Table Settings" = 1. Astrometric RA & Dec, 20. Observer range
にした出力結果を読み込んでください。Tableには上記以外が含まれていてもよいですが、
各epochが一行に収まっている必要があります。
Dateのフォーマットはカレンダー形式、JDのどちらでもかまいません。
また、HORIZONSの出力ファイルをTSCフォーマットに変換して保存することもできます。


▼観測準備状況の保存およびロード
GUI上で設定を適宜編集しますが、その作業状況をすべてセーブすることができます。
*.hoeというコンフィグファイルを作成しますので、それも同時に保存しておくと便利
です。これらはすべてメニューバーのFileメニュー内からおこないます。


▼OPEファイルの出力
二種類のOPEファイルを作ることができます。
[1] Base OPE File
 各天体を観測するコマンドを使用モードごとに列挙しただけの簡単なOPEファイルを
 出力します。メニューの "File"→"Write Base OPE"から実行することができます。
 天体がたくさんあり、観測順序が決まっていないときなどはこのOPEファイルを
 使用すればよいです。

[2] Plan OPE file
 より詳細に観測プランにのっとったOPEファイルを作成します。すべてのdead time
 なども考慮した時間の割り振りがなされますので、実際の観測にはこちらが準備
 されていることが好ましいです。
 後述の観測プランの作成を参照してください。


▼観測プランの作成
メニューの "Edit"→"Obs.Plan Editor"で高度な観測計画の立案に対応する
"Obs. Plan Editor"を起動することができます。
このモードでは、各タスクの実行時間を自動的に(大雑把にですが)計算し、観測計画を
たてやすくなっています。
なお、日の出日の入り(薄明も)の計算も自動的にされますので、メインウインドウの
General TABにて観測日時を正確に入力しておく必要があります。

計画を作成したら、Obs.Plan Editorのメニューから"File"→"Write Plan OPE"を実行
することにより、計画にしたがったOPEファイルを自動作成することができます。
また、計画の内容をテキストファイルとして書き出すことも可能です。


▼Magnitudeの検索
天体リストを読み込んだあとでメニューの"Database"→"Catalog Matching"以下
から SIMBAD, GSC, PanSTARRS, SDSS, GAIA および 2MASSで検索を行うことにより、
天体リストにMagnitudeの情報を付加することができます。
Magnitude情報が付加されることにより
 - 各天体のS/Nをリストできる (メニューの"Update"→"Calc. S/N by ETC")
 - 明るい天体のSetupFieldにSV Filterを挿入するパラメータを自動的に付加できる
 - Plan OPEでは SVのExpTimeが自動で設定される。
 - プロポーザル申請システム(PROMS)に入力するためのリストを出力できる
 - S/Nリストを作成することにより、Service観測用のリクエストを出力できる
などのメリットがあります。 


▼Echelle Format Simulator for HDS
メニューの"Tool"→"Echelle Format Simulator"から実行。
ウェブのEFSと同様な機能をhoe単独で再現できます。
PDFへの出力も可能です。
Line listタブで注目したいラインの波長を記入しておけば、EFS上でその
場所を確認できます。


▼Exposure Time Calculator for HDS
ウェブのETCと同様な機能をhoe単独で再現できます。
Line listタブで注目したいラインの波長を記入しておけば、ETCタブでその
オーダーを確認できます。
 - メニューの"Tool"→"Exposure Time Calculator"
   ウェブのものとほぼ同じ機能です。
   結果はETCタブに表示されます。
 - Main Target 下部のView→ETCボタン
   リストで選択した天体のS/Nを計算します。
   ほぼメニューから起動したときと同じですが、ポップアップダイアログに
   天体のMag, Band, ExpTimeなどが自動で記入されます。
   結果はETCタブに表示されます。
 - メニューの"Update"→"Calc S/N by ETC"
   Main TagetリストでMagが入力されている天体について指定した波長域
   (デフォルトはRed CCDの一番青側のオーダー)でのS/Nを計算します。


▼Finding Chartの作成
Main Targetタブで選択した天体について、"View"→"FC"ボタンでFinding 
Chartを作成することができます(要ネットワーク)。 
また、結果をPDFファイルにセーブすることもできます。
FCの中心座標は天体の固有運動を考慮した観測日のものになります。


▼天体高度のプロット
Main Targetタブで選択した天体について、"View"→"Plot"ボタンで天体高度
(他 Az, 大気分散など)のChartを作成することができます。 
また、結果をPDFファイルにセーブすることもできます。


▼スカイモニター
メニューの"Tool"→"Sky Monitor"で起動します。
基本的にはhskymonの簡易版ですが、観測プランに応じた望遠鏡の動きをプロット
することができます。


▼データベースの検索
読み込んだMain Targetリストの天体について、各種データベースでの検索を
行うことができます。
 - "Database"→"Data Archive List Query"
   SMOKA, HST, ESO , Geminiの各データアーカイブで取得されたデータが
   あるかどうか検索をします。
   リストはDB/Main Tagetタブに表示されますが、毎回検索結果は上書きされます。
 - "Database"→"Catalog Matching"
   Main Targetリストの各天体についてSIMBAD, NED, LAMOST, GSC, PanSTARRS, 
   SDSS, GAIA, 2MASSの各カタログ内でマッチする天体を探します。
   基本的には検索範囲内で最も明るい天体が選択されます。
   Proper Motionは考慮していません。
   リストはDB/Main Tagetタブに表示され、データベースごとにいつでも結果を
   切り替えて見ることができます。
   NED, LAMOST以外のデータベースでは、選択したバンドのMagをMain Targetリスト
   に付加します。
   

▼Gen2へのOPEファイルのアップロード
ハワイ観測所内部のネットワークに接続している場合は、GUI上から任意の
OPEファイルを山頂Gen2 system (sumdaの~/Procedure/)へアップロードできます。
この機能を利用するにはGeneral タブで正しいIDおよびパスワードを入力してから
メニューで"File"→"Upload OPE"を実行してください。

なお、OPEファイルはsumdaの~/Procedure/ディレクトリに転送されます。
転送先にすでに同名のファイルがある場合は自動的に上書きされます。
また、パスワードはセキュリティの観点から各自の環境のHOME$/.hoeファイルに
一括して保存されます(平文です)。*.hoeファイルをメールでやり取りした場合は、
それぞれの環境で再入力が必要となります。


▼注意する点
  - スタンダード以外のセッティングを使用する場合は、フラットの設定は
    いちばん近いスタンダードセッティングのものを流用するだけですので、
    実際には現場での微調整が必要です。

  - Binningに応じて FlatおよびComparisonの積分時間を調整していますが、
    不十分かもしれません。
    (1x1 binningの積分時間)/(x方向のbinning)/(y方向のbinning)
    を整数化したものを使用しています。


▼著作権
   The code in this distribution is Copyright 2003-2018 by Akito Tajitsu

   このプログラムはフリーソフトウェアです。あなたはこれを、 Free Software　
   Foundation によって発行されたGNU一般公衆利用許諾書 (バージョン3、
   または(任意に)それ以降のバージョンのどちらか)の定める条件に従って、
   これを再配布、そして(あるいは)修正することができます。

   このプログラムは有用であることを願って配布されますが、*全くの無保証*です。
   *商業可能性の保証*や*特定の目的への適合性*は、言外に示されたものも含め
   全く存在しません。詳しくはGNU一般公衆利用許諾書をご覧ください。

   あなたはこのプログラムとともにGNU一般公衆利用許諾書の複製を一部受け取った
   はずです。もし受け取っていなければ、Free Software Foundationまで請求
   してください(宛先は Free Software Foundation, Inc.,
   51 Franklin St., Fifth Floor, Boston, MA 02110-1301 USA)。

   加えて特別な例外として、A.TajitsuはこのプログラムのコードをOpenSSLライブ
   ラリ(あるいはOpenSSLと同じライセンスが適用されたOpenSSLの改変された
   バージョン)とリンクし、リンクされた両者を含む結合著作物を頒布する許可を
   あたえます。
   あなたはOpenSSL以外で使われているすべてのコードに関しては全面的にGNU一般
   公衆利用許諾書に従わなければなりません。あなたがこのファイルを改変したな
   らば、あなたはこのバージョンのファイルに引き続き設けることもできますが、
   そうする義務はありません。もし例外を設けたくなければ、この例外条項をあな
   たのバージョンからは削除してください。