Swiss Ephemeris 应用程序编程接口

版权 Astrodienst AG 1997-2016.
本文档描述 Swiss Ephemeris DLL 专业程序员接口. 

Swiss Ephemeris 是由它的作者提供在一个双重授权系统下. 在其软件中使用 Swiss Ephemeris 任何部分的软件开发者, 必须选择两个许可模型之一, 它们是
  a) GNU 公共许可版本2 或以上
  b) Swiss Ephemeris 专业许可

选择必须在软件开发者分发含有 Swiss Ephemeris 部分的软件给其它人之前作出, 并在任何使用开发的软件的公共服务激活之前.

如果开发者选择 GNU GPL 软件许可, 他或她必须履行该许可证的条件, 其中包括把整个软件项目放入 GNU GPL 或一个兼容的许可证下的义务. 参见http://www.gnu.org/licenses/old-licenses/gpl-2.0.html

如果开发者选择 Swiss Ephemeris 专业许可, 他必须按照 http://www.astro.com/swisseph/ 中的说明并从 Astrodienst 购买 Swiss Ephemeris 专业版并签订相应的许可合同.

 
0. 获取行星位置的编程步骤

1. 星历文件相关函数
1.1 swe_set_ephe_path()
1.2 swe_close()
1.3 swe_set_jpl_file()
1.4 swe_version()
1.5 swe_get_library_path()

2. 函数 swe_calc_ut() 和 swe_calc()
2.1. 调用参数
2.2. 星体 ( int ipl )
2.3. 标志位选择的选项 (long  iflag)
2.4. 位置和速度(double xx[6])
2.5. 错误处理和返回值

3. 函数 swe_get_planet_name()

4. 恒星函数
4.1 swe_fixstar_ut
4.2 swe_fixstar()
4.3 swe_fixstar_mag()

5. 开普勒元素, 拱点和节点, 轨道周期
5.1 swe_nod_aps_ut
5.2 swe_nod_aps()
5.3 swe_get_orbital_elements()
5.4 swe_orbit_max_min_true_distance()

6. 食, 升, 落, 中天, 行星现象
6.0. 典型的食计算示例
6.1. swe_sol_eclipse_when_loc()
6.2. swe_sol_eclipse_when_glob()
6.3. swe_sol_eclipse_how ()
6.4. swe_sol_eclipse_where ()
6.5. swe_lun_occult_when_loc()
6.6. swe_lun_occult_when_glob()
6.7. swe_lun_occult_where ()
6.8.a. swe_lun_eclipse_when_loc ()
6.8.b. swe_lun_eclipse_when ()
6.9. swe_lun_eclipse_how ()
6.10. swe_rise_trans() 和 swe_rise_trans_true_hor() (升, 落, 中天)
6.11. swe_pheno_ut() 和 swe_pheno(), 行星现象
6.12. swe_azalt(),水平座标, 方位角, 海拔高度
6.13. swe_azalt_rev()
6.14. swe_refrac(), swe_refract_extended(),折射
6.15. 偕日升等: swe_heliacal_ut()
6.16. 星等能见度上限: swe_vis_limit_mag()
6.17. 偕日细节: swe_heliacal_pheno_ut()

7. 日期和时间转换函数
7.1 计算日期和儒略日: swe_julday(), swe_date_conversion(), /swe_revjul()
7.2. UTC 和儒略日: swe_utc_time_zone(), swe_utc_to_jd(), swe_jdet_to_utc(), swe_jdut1_to_utc()
7.3. 处理闰秒和文件 seleapsec.txt
7.4. 平太阳时对真太阳时: swe_time_equ(), swe_lmt_to_lat(), swe_lat_to_lmt()

8. Delta T 相关函数
8.1 swe_deltat_ex()
8.2 swe_deltat()
8.3 swe_set_tid_acc(), swe_get_tid_acc()
8.4. swe_set_delta_t_userdef()
8.4. Delta T 的未来更新和文件 swe_deltat.txt

9. 行星位置函数 swe_set_topo()

10. 恒星模式函数
10.1. swe_set_sid_mode()
10.2. swe_get_ayanamsa_ex_ut(), swe_get_ayanamsa_ex(), swe_get_ayanamsa() 和 swe_get_ayanamsa_ut()

11. 星历文件相关函数(已移至1.)

12. Swisseph 函数中的地理经度的标志
12.1. 地理VS地心纬度

13. 宫头计算
13.1 swe_houses()
13.2 swe_houses_armc()
13.3 swe_houses_ex()
13.4 swe_house_name()

14. 行星的宫位: swe_house_pos()
14.1. 用 swe_house_pos() 或 swe_gauquelin_sector() 计算行星的高魁林盘

15. 用 swe_sidtime() 和 swe_sidtime0() 计算恒星时

16. SWISSEPH 函数概述
16.1. 行星和恒星的计算
16.2. 食和行星现象
16.3. 日期和时间转换
16.4. 初始化, 设置和关闭函数
16.5. 宫计算
16.6. 辅助函数
16.7. 其它可能有用的函数

17. SWISSEPH DLLs
17.1 脑残编译器的 DLL 接口

18. 在 Visual Basic 5.0 中使用 DLL

19. 在 Borland Delphi 和 C++ Builder 中使用 DLL
19.1 Delphi 2.0 及更高版本(32-位)
19.2 Borland C++ Builder

20. 在 Perl 中使用 Swiss Ephemeris

21. C 示例程序
21. 源代码分发

22. PLACALC 兼容 API

23. 文档文件

24. 不同硬件和编译器中的 Swisseph

25. 调试和跟踪 Swisseph
25.1. 如果你使用DLL
25.2 如果你使用源代码

附录
更新和发布历史
版本2.04 升级到 2.05 的更改
版本2.03 升级到 2.04的更改
版本2.02.01 升级到 2.03的更改
版本2.02 升级到 2.02.01的更改
版本2.01 升级到 2.02的更改
版本2.00 升级到 2.01的更改
版本1.80 升级到 2.00的更改
版本1.79 升级到 1.80的更改
版本1.78 升级到 1.79的更改
版本1.77 升级到 1.78的更改
版本1.76 升级到 1.77的更改
版本1.75 升级到 1.76的更改
版本1.74 升级到 1.75的更改
版本1.73 升级到 1.74的更改
版本1.72 升级到 1.73的更改
版本1.71 升级到 1.72的更改
版本1.70.03 升级到 1.71的更改
版本1.70.02 升级到 1.70.03的更改
版本1.70.01 升级到 1.70.02的更改
版本1.70.00 升级到 1.70.01的更改
版本1.67 升级到 1.70的更改
版本1.66 升级到 1.67的更改
版本1.65 升级到 1.66的更改
版本1.64.01 升级到 1.65.00的更改
版本1.64 升级到 1.64.01的更改
版本1.63 升级到 1.64的更改
版本1.62 升级到 1.63的更改
版本1.61.03 升级到 1.62的更改
版本1.61 升级到 1.61.01的更改
版本1.60 升级到 1.61的更改
版本1.51 升级到 1.60的更改
版本1.50 升级到 1.51的更改
版本1.40 升级到 1.50的更改
版本1.31 升级到 1.40的更改
版本1.30 升级到 1.31的更改
版本1.27 升级到 1.30的更改
版本1.26 升级到 1.27的更改
版本1.25 升级到 1.26的更改
版本1.22 升级到 1.23的更改
版本1.21 升级到 1.22的更改
版本1.20 升级到 1.21的更改
版本1.11 升级到 1.20的更改
版本1.10 升级到 1.11的更改
版本1.04 升级到 1.10的更改
版本1.03 升级到 1.04的更改
版本1.02 升级到 1.03的更改
版本1.01 升级到 1.02的更改
版本1.00 升级到 1.01的更改

附录A
少了什么?

索引

0. 获取行星位置的编程步骤

要用 SWISSEPH 计算一个星体或点, 必须按以下步骤(以 swetest.c 为例). 这些函数的细节将在以后章节中说明.

1.  设置星历文件的目录路径, 例如:
 swe_set_ephe_path(”C:\\SWEPH\\EPHE”);

2. 根据出生日期来计算儒略日数:
 jul_day_UT = swe_julday(year, month, day, hour, gregflag);

3.  计算一个行星或其它星体:
 ret_flag = swe_calc_ut(jul_day_UT, planet_no, flag, lon_lat_rad, err_msg);
  或计算恒星:
 ret_flag = swe_fixstar_ut(star_nam, jul_day_UT, flag, lon_lat_rad, err_msg);

 注意:
 函数swe_calc_ut() 和 swe_fixstar_ut() 是Swisseph 版本 1.60引入的.
 如果你使用Swisseph 1.60 以前的版本或者你想要处理星历时, 你必须按以下方式来处理:

 首先, 如果需要, 转换世界时(UT)为星历时(ET):
 jul_day_ET = jul_day_UT + swe_deltat(jul_day_UT);

 然后计算行星或其它星体:
 ret_flag = swe_calc(jul_day_ET, planet_no, flag, lon_lat_rad, err_msg);
 或恒星:
 ret_flag = swe_fixstar(star_nam, jul_day_ET, flag, lon_lat_rad, err_msg);

5. 在你完成计算后调用swe_close() 来关闭所有文件并释放内存;

以下是一个最小的示例程序, 它是在分发的源代码中的swemini.c中

#include "swephexp.h"  /* this includes  "sweodef.h" */
int main()
{
  char *sp, sdate[AS_MAXCH], snam[40], serr[AS_MAXCH]; 
  int jday = 1, jmon = 1, jyear = 2000;
  double jut = 0.0;
  double tjd_ut, te, x2[6];
  long iflag, iflgret;
  int p;
  swe_set_ephe_path(NULL);
  iflag = SEFLG_SPEED;
  while (TRUE) {
    printf("\nDate (d.m.y) ?");
    gets(sdate);
  /* 用户只输入了一个点. 就停止*/
    if (*sdate == '.')
      return OK;
    if (sscanf (sdate, "%d%*c%d%*c%d", &jday,&jmon,&jyear) < 1) exit(1);
     /*
      * 我们有了年月日, 将其转换为儒略日数
      */
    tjd_ut = swe_julday(jyear,jmon,jday,jut,SE_GREG_CAL);       
     /*
      * 加上delta_t来从世界时计算历书时
      * 对于小于 Swisseph v 1.60 的不需要
      */
       /* te = tjd_ut + swe_deltat(tjd_ut); */
    printf("date: %02d.%02d.%d at 0:00 世界时\n", jday, jmon, jyear);
    printf("planet     \t经度\t纬度\tdistance\tspeed 经度\n");
     /*
      * 遍历所有行星
      */
    for (p = SE_SUN; p <= SE_CHIRON; p++) {
      if (p == SE_EARTH) continue;
  /*
   * 计算行星 p 的坐标
   */
iflgret = swe_calc_ut(tjd_ut, p, iflag, x2, serr);
         /* Swisseph版本低于1.60
          *用以下语句代替*/
/* iflgret = swe_calc(te, p, iflag, x2, serr); */
       /*
        * 如果有问题, 返回一个负值
        * 且错误信息在serr中.
        */
      if (iflgret < 0)
 printf("error: %s\n", serr);
       /*
        * 得到行星 p 的名字
        */
      swe_get_planet_name(p, snam);
       /*
        * 显示坐标
        */
      printf("%10s\t%11.7f\t%10.7f\t%10.7f\t%10.7f\n",
      snam, x2[0], x2[1], x2[2], x2[3]);
    }
  }
  return OK;
}


1. 星历文件相关函数
1.1 swe_set_ephe_path()
这是调用其它Swiss Ephemeris函数前首先要调用的函数. 即使你不想设置星历文件路径并使用莫希尔星历, 不过仍然推荐调用swe_set_ephe_path(NULL), 因为该函数进行重要的初始化. 如果你不这样做, Swiss Ephemeris 也可以工作, 但结果可能不是100% 的正确.

如果Swiss Ephemeris使用的环境变量SE_EPHE_PATH 存在于环境中, 它的内容用于查找星历文件. 该变量可以包含一个路径名, 或由分号;(Windows)或(Unix)分开的目录名列表.
void swe_set_ephe_path(char *path);
 
通常应用程序会设置它自己的星历文件, 例如:
swe_set_ephe_path(”C:\\SWEPH\\EPHE”);

参数可以是单个的路径名或一个可以顺序搜索的目录列表. 如果环境变量SE_EPHE_PATH 存在且非空, 该调用参数将被忽略.
如果你希望确保你的程序中的设置优先于任何环境变量的设置, 你可以用putenv() 来设置它为一个空串.

如果路径名长于256 字节, swe_set_ephe_path() 设置路径\SWEPH\EPHE 来代替它.
如果环境变量不存在且没有调用过swe_set_ephe_path(), 就使用内置的星历路径. 在 Windows 是”\sweph\ephe” 相对于当前工作盘, 在 Unix 是"/users/ephe".
小行星星历在星历目录下的子目录ast0, ast1, ast2 .. ast9 中搜索, 而且如果没找到则在星历目录本身中查找. 编号为0 – 999 的小行星在目录ast0中, 那些编号1000 – 1999 的小行星在目录 ast1 中查找, 等等.

当用户安装了多个使用Swiss Ephemeris的应用程序又希望星历文件位于不同的应用程序特定的目录中时, 环境变量SE_EPHE_PATH 是最方便的. 可以通过设置环境变量来强制所有不同的程序使用相同的星历目录. 这样做让他们为所有不同的应用程序使用一组已安装的星历文件. 开发者会接受这种方法并允许有经验的用户利用它.
1.2 swe_close()
/* close Swiss Ephemeris */
void swe_close(void);

在计算结束后你可以用Swiss Ephemeris DLL 释放资源(打开的文件和分配的内在).
以下参数将会在调用swe_calc()后保留下来:
? 用 swe_set_ephe_path() 设置的星历路径
? 用 swe_set_jpl_file()设置的星历文件名
? 用 swe_set_topo() 设置的地理位置
? 用 swe_set_sid_mode() 设置的恒星模式

一但你调用swe_calc() 或 swe_fixstar(), Swiss Ephemeris 再次重新打开.
1.3 swe_set_jpl_file()

/* set name of JPL 星历 file */
void swe_set_jpl_file(char *fname);

如果你使用JPL 星历, SwissEph 使用uses the default file name which is defined in swephexp.h 中定义的 SE_FNAME_DFT. Currently, it has the value ”de406.eph” or ”de431.eph”.
如果需要一个不同的JPL 星历文件, 调用函数swe_set_jpl_file() 使程序知道文件名, 例如
swe_set_jpl_file(”de405.eph”);

该文件必须存在于你的程序使用的星历路径中.
如果文件名长于256 字节, swe_set_jpl_file() 切去大于256 字节的部分. 在第一次调用swe_calc()时将会发生错误, 然后它将返回零值和一条错误信息.

1.4 swe_version()

/* 找出 version number of your Swiss Ephemeris version */
char *swe_version(char *svers);
/* svers is a string variable with sufficient space to contain the version number (255 char) */

该函数返回一个指向字符串 svers的指针, 该串中包含了你的程序使用的Swiss Ephemeris 的版本号.

1.5 swe_get_library_path()

/* 找出 the library path of the DLL or executable */
char *swe_get_library_path(char *spath);
/* spath is a string variable with sufficient space to contain the library path (255 char) */

该函数返回一个指向字符串 spath 的指针, 该串中包含了你的执行文件所在的路径. 如果是使用的DLL, 则 spath 包含了DLL所在路径.

 2. 函数 swe_calc_ut() 和 swe_calc()
在调用这两个函数之一或任何Swiss Ephemeris 函数前, 强烈建议调用函数 swe_set_ephe_path(). 即使你想设置星历路径并使用莫希尔星历表, 仍然推荐调用swe_set_ephe_path(NULL), 因为该函数进行重要的初始化. 不这样做, Swiss Ephemeris 也可以工件但结果可能不是100% 的正确.
2.1. 调用参数
swe_calc_ut() 是在Swisseph 版本1.60 中引入并使行星计算更为简便. 关于需要的步骤, 参见章节  获取行星位置的编程步骤.
swe_calc_ut() 和 swe_calc() 工作方式完全相同只是swe_calc() 要求历书时 (更准确地说: 力学时 ) 作为参数而 swe_calc_ut() 则要求世界时. 对于占星术的计算, 你可能只需要swe_calc_ut()并且将不必再思考关于世界时和历书时的转换.
swe_calc_ut() 和 swe_calc() 计算行星、小行星位置, 月球交点和远地点. 它们定义如下:

int swe_calc_ut ( double tjd_ut, int ipl, int iflag, double* xx, char* serr),
其中
tjd_ut =儒略日, 世界时   //世界时间，格林尼治（平均）时
ipl =星体编号                  //星体编号
iflag =一个 32 位整, 型包了含用于指明需要哪种类型的计算的标志位
xx  = 6元素双精度数组包含了经度, 纬度, 距离, 经度速度, 纬度速度和距离速度.
serr[256] =发生错误时返回错误信息的字符串.

而且
int swe_calc(double tjd_et, int ipl, int iflag, double *xx, char *serr),
相同但
tjd_et = 儒略日, 历书时,  其中tjd_et = tjd_ut + swe_deltat(tjd_ut)

关于这此变量的详细说明将在以后章节中给出.

2.2. 星体( int ipl )
要告诉 swe_calc() 想计算哪一个天体或要素, 使用一组固定的星体编号. 星体编号在swephexp.h中定义:
/* swe_calc() 中的 ipl 参数使用的行星编号*/
#define SE_ECL_NUT -1     
#define SE_SUN           0      
#define SE_MOON          1      
#define SE_MERCURY       2      
#define SE_VENUS         3      
#define SE_MARS          4      
#define SE_JUPITER       5      
#define SE_SATURN        6      
#define SE_URANUS        7      
#define SE_NEPTUNE       8      
#define SE_PLUTO         9      
#define SE_MEAN_NODE     10     
#define SE_TRUE_NODE     11
#define SE_MEAN_APOG     12     
#define SE_OSCU_APOG     13   
#define SE_EARTH         14
#define SE_CHIRON        15
#define SE_PHOLUS        16
#define SE_CERES         17
#define SE_PALLAS        18
#define SE_JUNO          19
#define SE_VESTA         20
#define SE_INTP_APOG         21
#define SE_INTP_PERG         22

#define SE_NPLANETS         23
#define SE_FICT_OFFSET   40
#define SE_NFICT_ELEM            15
#define SE_AST_OFFSET 10000

/* Hamburger or Uranian "planets" */
#define SE_CUPIDO        40
#define SE_HADES         41
#define SE_ZEUS          42
#define SE_KRONOS        43
#define SE_APOLLON       44
#define SE_ADMETOS       45
#define SE_VULKANUS      46
#define SE_POSEIDON      47

/* other fictitious bodies */
#define SE_ISIS          48
#define SE_NIBIRU        49
#define SE_HARRINGTON       50
#define SE_NEPTUNE_LEVERRIER  51
#define SE_NEPTUNE_ADAMS     52
#define SE_PLUTO_LOWELL      53
#define SE_PLUTO_PICKERING    54

额外的小行星
其它小行星的星体编号大于SE_AST_OFFSET (=10000) 且必须按以下方式构成:
ipl = SE_AST_OFFSET + Minor_Planet_Catalogue_number;
例如Eros :  ipl = SE_AST_OFFSET +  433

小行星的名称和总目号(catalogue numbers) 可以在文件 seasnam.txt 中找到.

示例如下:

5 Astraea 
6 Hebe 
7 Iris 
8 Flora
9 Metis
10 Hygiea 
30 Urania 
42 Isis not identical with "Isis-Transpluto"
153 Hilda (has an own asteroid belt at 4 AU)
227 Philosophia 
251 Sophia 
259 Aletheia 
275 Sapientia 
279 Thule (asteroid close to 木星)
375 Ursula 
433 Eros 
763 Cupido different from Witte's Cupido
944 Hidalgo 
1181 Lilith (not identical with Dark Moon 'Lilith')
1221 Amor 
1387 Kama 
1388 Aphrodite 
1862 Apollo (different from Witte's Apollon)
3553 Damocles highly eccentric orbit betw. Mars and Uranus
3753 Cruithne ("second moon" of earth)
4341 Poseidon Greek 海王星 (different from Witte's Poseidon)
4464 Vulcano fire god (different from Witte's Vulkanus and intramercurian Vulcan)
5731 Zeus Greek 木星 (different from Witte's Zeus)
7066 Nessus third named Centaur (beween Saturn and 冥王星)


各小行星有两个星历文件, 一个长和一个短:

se09999.se1 小行星编号9999的长星历, 3000 BC – 3000 AD
se09999s.se1 小行星编号9999的短星历, 1500 – 2100 AD

较大的文件的大小大约是短星历的10 倍. 如果用户不想1500年前的星历他可以使用短文件. 如果是这样, 只拷贝文件名尾部为”s.se1” 到你的硬盘. Swe_calc() 将尝试打开长文件并在失败后自动使用短文件.
小行星星历在星历目录下的子目录 ast0, ast1, ast2 .. ast9 中搜索, 而且如果没找到则在星历目录本身中查找. 编号为0 – 999 的小行星在目录ast0中, 那些编号1000 – 1999 的小行星在目录 ast1 中查找, 等等.
注意  并非所有小行星  可以在 Swiss Ephemeris 的整个期间内计算.他们中的某些星的轨道对于主行星的扰动是非常敏感的. 例如 CHIRON 星, 因为与土星的接近而不能计算公元 650 以前及公元 4650以后的数据. 在这个时间范围之外 Swiss Ephemeris 返回错误码, 一条错误信息, 以及位置值0. 注意, 用户必须在自己的程序中处理这种情况. 为Jesus 或 Alexander 计算 Chiron transits the Great 将得不到正确结果.
相同的还有 Pholus 星3850 BC, 以及许多其它的小行星, 例如 1862 Apollo. 它在1870 AD 前当它靠近金星很近时变得混乱,. Swiss Ephemeris 不提供几个世纪前的 Apollo 的位置!


注意小行星名称
小行星的名字在文件 seasnam.txt 中列出. 该文件位于星历文件所在目录.
虚构的行星

虚构的行星的星体编号大于或等于40. 用户可以定义他们自己的虚构的行星. 这些行星的轨道参数必须写入文件 seorbel.txt. 函数 swe_calc() 搜索由 swe_set_ephe_path() 设置的星历路径中的文件 seorbel.txt. 如果没有找到轨道参数文件, swe_calc() 使用前面提及的 Uranian planets 和一些其它星体的内置的轨道参数. 虚构的行星的星体编号定义为

ipl = SE_FICT_OFFSET_1 + number_of_elements_set;

例如对于Kronos: ipl = 39 + 4 = 43.

文件seorbel.txt 具有以下结构:

    #虚构的行星的轨道参数
    # 27 Jan. 2000
    #
    # This file is part of the Swiss Ephemeris, from Version 1.60 on.
    #
    # Warning! These planets do not exist!
    #
    # The user can add his or her own elements.
    # 960 is the maximum number of 虚构的行星.
    #
    # The elements order is as follows:
    # 1. epoch of elements (儒略日)
    # 2. equinox (儒略日 或 "J1900" 或 "B1950" 或 "J2000" 或 “JDATE”)
    # 3. 平近点角 at epoch
    # 4. semi-axis
    # 5. eccentricity
    # 6. argument of 近日点 (ang. distance of 近日点 from node)
    # 7. 升交点
    # 8. inclination
    # 9. name of planet
    #
    # use '#' for comments
    # to compute a body with swe_calc(), use 行星编号
    # ipl = SE_FICT_OFFSET_1 + number_of_elements_set,
    # 例如 number of Kronos is ipl = 39 + 4 = 43
    #
    # Witte/Sieggruen planets, refined by James Neely
J1900, J1900, 163.7409, 40.99837, 0.00460, 171.4333, 129.8325, 1.0833, Cupido   # 1
J1900, J1900,  27.6496, 50.66744, 0.00245, 148.1796, 161.3339, 1.0500, Hades    # 2
J1900, J1900, 165.1232, 59.21436, 0.00120, 299.0440,   0.0000, 0.0000, Zeus     # 3
J1900, J1900, 169.0193, 64.81960, 0.00305, 208.8801,   0.0000, 0.0000, Kronos   # 4
J1900, J1900, 138.0533, 70.29949, 0.00000,   0.0000,   0.0000, 0.0000, Apollon  # 5
J1900, J1900, 351.3350, 73.62765, 0.00000,   0.0000,   0.0000, 0.0000, Admetos  # 6
J1900, J1900,  55.8983, 77.25568, 0.00000,   0.0000,   0.0000, 0.0000, Vulcanus # 7
J1900, J1900, 165.5163, 83.66907, 0.00000,   0.0000,   0.0000, 0.0000, Poseidon # 8
    #
    # Isis-Transpluto; elements from "Die Sterne" 3/1952, p. 70ff.
    # Strubell does not give an equinox. 1945 is taken 为了
    # reproduce the as best as ASTRON ephemeris. (This is a strange
    # choice, though.)
    # The epoch according to Strubell is 1772.76.
    # 1772 is a leap year!
    # The fraction is counted from 1 Jan. 1772
2368547.66, 2431456.5, 0.0, 77.775, 0.3, 0.7, 0, 0, Isis-Transpluto             # 9
    # Nibiru, elements from Christian Woeltge, Hannover
1856113.380954, 1856113.380954, 0.0, 234.8921, 0.981092, 103.966, -44.567, 158.708, Nibiru # 10
    # Harrington, elements from Astronomical Journal 96(4), Oct. 1988
2374696.5, J2000, 0.0, 101.2, 0.411, 208.5, 275.4, 32.4, Harrington             # 11
    # according to W.G. Hoyt, "Planets X and 冥王星", Tucson 1980, p. 63
2395662.5, 2395662.5, 34.05, 36.15, 0.10761, 284.75, 0, 0, Leverrier (海王星)  # 12
2395662.5, 2395662.5, 24.28, 37.25, 0.12062, 299.11, 0, 0, Adams (海王星)      # 13
2425977.5, 2425977.5, 281, 43.0, 0.202, 204.9, 0, 0, Lowell (冥王星)             # 14
2425977.5, 2425977.5, 48.95, 55.1, 0.31, 280.1, 100, 15, Pickering (冥王星)      # 15
J1900,JDATE, 252.8987988 + 707550.7341 * T, 0.13744, 0.019, 322.212069+1670.056*T, 47.787931-1670.056*T, 7.5, Vulcan # 16
# Selena/White Moon
J2000,JDATE, 242.2205555, 0.05279142865925, 0.0, 0.0, 0.0, 0.0, Selena/White Moon, geo # 17

所有轨道参数除了时期(epoch)和分点(equinoxes)可能还有T项, 其中
T = (tjd – epoch) / 36525.
(参见, 如, Vulcan, 倒数第二个元素集(不是“天王星”vulcanus 而是水星内假想行星Vulcan).) ”T * T”, ”T2”, ”T3” 也是允许的.
分点既可以是儒略日或”J1900” 或 ”B1950” 或 ”J2000” 或, 如果要求的是分点的日期, 可以是”JDATE”. 如果你使用T 项, 注意的岁差必须考虑JDate, 而它已经被固定分点忽略.

平近点角不需要T 项, 换言之对于星体的速度, 因为我们的程序可以从半轴和重力计算它. 但是, 平近点角 T 项必须添加到 Vulcan 因为它的速度与物理定律不一致. 在此情况下, 程序使用元素中给出的速度且并不在内部计算它.

从版本1.62 开始, 程序也接受在地球上空移动的虚拟星体的轨道参数. 作为例子, 研究上面的 seorbel.txt 摘要中的最后元素集. 在星体名称后, 添加了”, geo”.

倾角和章动

一个特殊的星体编号 SE_ECL_NUT 用于计算黄赤交角和章动. 当然章动已经由 swe_calc() 内部添加到星体坐标, 但在有时候我们需要得到它的单独的值.

iflgret = swe_calc(tjd_et, SE_ECL_NUT, 0, x, serr);

x 通常是具有六个成员的双精度数组. 它们将被填充如下:

x[0] = 真黄赤交角 (包括章动)
x[1] = 平黄赤交角
x[2] = 黄经章动
x[3] = 黄赤交角章动
x[4] = x[5] = 0

 2.3. 标志位选择的选项 (long  iflag)
2.3.1. 标志位的使用

如果位没有被设置, 也就是如果  iflag == 0, swe_calc() 计算通常的占星星历(如书店中可见的) 应用, 即相对于真日期分点的地心黄道坐标视星体位置（经度、纬度和距离）.
如果需要星体的速度, 设置 iflag = SEFLG_SPEED
对于作为数字点的月平交点和远地点, 没有视位置. Swe_calc() 为这些点返回真位置.
如果你需要另一些类型的计算, 使用以下段落中解释的标志(c.f. swephexp.h). 它们的名字以SEFLG_开头. 要组合它们, 你必须象以下例子中那样将它们连接起来:
iflag = SEFLG_SPEED | SEFLG_TRUEPOS;  (或者: iflag = SEFLG_SPEED + SEFLG_TRUEPOS;) // C
iflag = SEFLG_SPEED or SEFLG_TRUEPOS;( 或者: iflag = SEFLG_SPEED + SEFLG_TRUEPOS;) // Pascal

使用该 iflag 的值, swe_calc() 将用速度计算真位置(即不占用光的时间).
此标志位, 在文件 swephexp.h 中定义, 如下:

#define SEFLG_JPLEPH     1L // 使用 JPL 星历
#define SEFLG_SWIEPH     2L // 使用SWISSEPH 星历, 默认
#define SEFLG_MOSEPH     4L // 使用莫希尔星历

#define SEFLG_HELCTR          8L //返回日心位置
#define SEFLG_TRUEPOS  16L //返回真位置而不是视位置
#define SEFLG_J2000           32L //无岁差, 即给定的 J2000 分点无岁差，
#define SEFLG_NONUT           64L // 无章动, 日期的即平分点
#define SEFLG_SPEED3          128L // 来自三个位置的速度(不要使用它, SEFLG_SPEED 更快
    // 且更精确.)
#define SEFLG_SPEED           256L //高精度速度(analyt. comp.)
#define SEFLG_NOGDEFL  512L //关闭引力偏转
#define SEFLG_NOABERR  1024L //关闭“年度”光行差
#define SEFLG_天体测量学 (SEFLG_NOABERR|SEFLG_NOGDEFL) // 天体位置
#define SEFLG_赤道 2048L //需要赤道位置
#define SEFLG_XYZ             4096L //笛卡尔坐标，非极坐标
#define SEFLG_RADIANS        8192L //坐标为弧度，不是度
#define SEFLG_BARYCTR        16384L // 重心位置
#define SEFLG_TOPOCTR  (32*1024L) // 观测点位置
#define SEFLG_SIDEREAL (64*1024L) //恒星位置
#define SEFLG_ICRS (128*1024L) // ICRS (DE406参考系)
#define SEFLG_DPSIDEPS_1980     (256*1024) /*再现JPL地平线
                                      * 1962 -现在 到 0.002 arcsec. */
#define SEFLG_JPLHOR    SEFLG_DPSIDEPS_1980
#define SEFLG_JPLHOR_APPROX     (512*1024)   /*近似于JPL 地平线 1962 – 现在 */

2.3.2. 星历标志

此标志选择一个星历: (在 swephexp.h 中定义)

SEFLG_JPLEPH           /* 使用 JPL 星历 */
SEFLG_SWIEPH           /* 使用 Swiss星历*/
SEFLG_MOSEPH           /* 使用莫希尔星历 */

如果未指定此标志, swe_calc() 尝试计算默认的星历. 默认的星历文件在 swephexp.h 中定义:
#define SEFLG_DEFAULTEPH SEFLG_SWIEPH
在此情况下默认的星历为 Swiss Ephemeris. 如果你没有在 iflag 中指定一个星历文件, swe_calc() 试着计算 Swiss Ephemeris 位置. 如果它没有找到需要的 Swiss Ephemeris 文件, 它就计算莫希尔星历位置.
2.3.3. 速度标志

如果你没有添加速度标志 Swe_calc() 将不计算速度
iflag |= SEFLG_SPEED;
由于速度的计算通常是很快的, 因此，你可能会设置这一点为默认，即使你不需要速度.

2.3.4. 坐标系, 度和弧度

SEFLG_赤道  返回赤道位置: 赤经和赤纬.
SEFLG_XYZ   返回x, y, z 坐标而不是经度, 纬度和距离.
SEFLG_RADIANS   返回弧度位置, 不是度.

例如要计算赤经和赤纬, 如下:
iflag = SEFLG_SWIEPH | SEFLG_SPEED | SEFLG_赤道;
2.3.5. 特殊标记(超越一般兴趣)
a. 真位置或视位置
常见的星历提供了视地心位置. 由于光从行星到达地球需要一些时间, 你看到的行星的实际位置并不在那里, 而是几分钟或几个小时前的. 星象学使用的位置是我们看到的位置. ( 更确切地说: 我们将看到的位置, 如果我们站在地球的中心，可以看到天空的话. 实际上, 观察者的地理位置也可能是重要的而且观测点位置可以计算, 但这通常不考虑在星象学中.). 地球的地心位置(SE_EARTH) 返回零.
要计算行星的真几何位置, 忽视光运行的时间, 你必须添加标志 SEFLG_TRUEPOS.
b. 观测点位置
要计算观测点位置, 即观察者的位置(出生位置) 而不是地球中心位置, 按以下方法:
? 调用 swe_set_topo(geo_lon, geo_lat, altitude_above_sea)  (地理经度和纬度的单位必须是度, 海拔高度为米.)
? 添加标志 SEFLG_TOPOCTR 到 iflag
? 调用 swe_calc(...)
c. 日心位置
要计算日心位置, 添加 SEFLG_HELCTR.
所有行星包括月亮的日心位置都可以计算. 对于太阳, 月球交点和月球远地点的坐标返回零; 不返回错误信息.
d. 重心位置
SEFLG_BARYCTR 产生的坐标是指太阳系质心. 然而, 这个选项没有完全实现.  它被用于开发过程中的程序测试.  它只工作于 JPL 和 Swiss Ephemeris, 而不能用于莫希尔星历; 且仅用于自然的星体, 而不能用于交点和远地点.
此外, Swiss Ephemeris 的太阳质心只有0.1的精度. 更高的精度将耗用大量的存储, 另一方面, 不需要精确的地心和日心位置. 对于更精确的重心位置,  将使用 JPL 星历文件.
可以计算所有行星包括太阳和月亮的重心位置. 月球交点和月球远地点的坐标值将返回零; 无错误信息出现.
e. 天体位置
有时候由天文年历给出的天体位置, 是进行了光时间校正计算的, 但年历中光行差和光偏转被太阳忽视. 这可以由 SEFLG_NOABERR 和 SEFLG_NOGDEFL 来完成. 对于位置相关的2000的平分点, 你必须设置 SEFLG_J2000 和 SEFLG_NONUT.
f. 日期的真和平分点
Swe_calc() 通常计算的位置是指日期的真分点(即带有章动). 如果你想要平分点, 你可以关闭章动, 使用标志位 SEFLG_NONUT.
g. J2000 位置和涉及到其他分点的位置
Swe_calc() 通常计算的位置是指日期的分点. SEFLG_J2000 给出的数据就是分点 J2000. 对于位置中提到的其他分点, SEFLG_SIDEREAL 必须设置且分点已由swe_set_sid_mode()指定. 更多信息, 参阅此函数的说明.
h. 恒星位置
要计算恒星位置, 设置标志位SEFLG_SIDEREAL 并用函数 swe_set_sid_mode() 来定义你要的岁差(岁差). 更多信息, 参见该函数说明.
i. JPL Horizons 位置
对于行星的视位置, JPL Horizons以一种与天文年历不同的方法而且从IERS 规范 2003 和 2010. 它使用旧的岁差模型 IAU 1976 (Lieske) 和章动 IAU 1980 (Wahr) 并通过添加日常测量的天体偏移(delta_psi 和 delta_epsilon)到章动来修正结果位置. (IERS规范1996, p. 22) 虽然这种方法在一些方面是比较准确的, 但它没有被引用到相同的坐标系统. 更多细节参见Swiss Ephemeris 中的文档 swisseph.doc 或 http://www.astro.com/swisseph/swisseph.htm , ch. 2.1.2.2.

JPL Horizons 的视位置可以使用标志SEFLG_JPLHOR以约0.001角秒的精度再现. 为了得到最佳结果, 每日地球方位参数(EOP) delta_psi 和 delta_eps 相对 IAU 1980岁差/章动模型必须下载并保存到由swe_set_ephe_path()定义的星历路径中. EOP 文件可以在IERS 网站找到:
http://www.iers.org/IERS/EN/DataProducts/EarthOrientationData/eop.html
需要以下文件:
1. EOP 08 C04 (IAU1980) – 一个文件 (1962-现在)
http://datacenter.iers.org/eop/-/somos/5Rgv/document/tx14iers.0z9/eopc04_08.62-now
把该文件放入你的星历路径并更名为“eop_1962_today.txt”.
2. finals.data (IAU1980)
http://datacenter.iers.org/eop/-/somos/5Rgv/document/tx14iers.0q0/finals.data
把该文件放入你的星历路径并更名为“eop_finals.txt”.

如果Swiss Ephemeris 没有找到这些文件, 它默认的标志为SEFLG_JPLHORA, 它是一个非常好的Horizons近似值, 至少从1962 到现在.
SEFLG_JPLHORA可独立使用，适用于整个Swiss Ephemeris时间范围.

注意, Horizons 模式仅工作于行星和恒星. 对于月球交点和拱点, 我们使用我们的标准方法.


2.4. 位置和速度 (double xx[6])

swe_calc() 按以下顺序返回位置的坐标和速度:

黄道位置 赤道位置 ( SEFLG_赤道 )
经度 赤经
纬度 赤纬
天文单位距离 天文单位距离
经向速度 (度/天) 赤经速度 (度/天)
纬向速度(度/天) 赤纬速度 (度/天)
距离速度(天文单位/天) 距离速度(天文单位/天)

如果你需要直角坐标( SEFLG_XYZ ), swe_calc() 返回天文单位的 x, y, z, dx, dy, dz.
一但你计算了一个行星, 例如, 在黄道坐标系, 它的赤道位置或直角坐标也是可获得的.  你可以很便宜地得到他们( 使用很少的CPU 时间), 以相同的参数再次调用swe_calc() , 但添加SEFLG_赤道 或 SEFLG_XYZ 到 iflag. swe_calc() 将不会再次进行计算, 只是从内部存储中返回指定的数据.

2.5. 错误处理和返回值
swe_calc() (以及 swe_calc_ut(), swe_fixstar() 和 swe_fixstar_ut() ) 返回一个32-位的整型值. 如果函数调用成功, 该值>= 0, 如果发生致命错误该返回值< 0. 另外一个错误的字符串或警告会在字符串参数 serr 中返回.

一个致命错误码(< 0) 和一个错误串在以下一种情况下以返回:

? 如果指定了非法的星体编号
? 如果指定的儒略日超过了星历限制
? 如果星历文件的长度不正确(文件损坏)
? 发生文件读取错误, 例如一个文件索引点到一个位置超过了文件长度( 文件中的数据错误)
? 如果星历文件中的版权部分被删除.

如果发生以上错误中的任何一个,

? 函数的返回值为-1,
? 位置和速度变量设置为零,
? 错误类型在错误串serr中指明.

如果函数运行成功, 返回码包含的标志位指明哪种类型的计算已经完成. 该值通常等于iflag, 但有时可能会与之不同. 如果iflag 指定的选项不能完成或是无意义的, swe_calc 只完成它可以完成的部分. 例如, 如果你指定使用JPL 星历, 但 swe_calc 不能找到星历文件, 它尝试使用任何可用的星历进行计算. 实际使用的星历表将在swe_calc的返回值中指明. 因此, 要确信swe_calc () 找到了要求的星历, 你需要进行检查, 例如:
if (return_code > 0 && (return_code & SEFLG_JPLEPH))
然而, 通常只需要在程序最开始进行一次星历检查就足够了.

在此情况下, 也会有一个警告在错误串serr中, 内容为:
warning: SwissEph file 'sepl_18.se1' not found in PATH '…' ; using Moshier eph.;

除此之外, 返回码为正值时不需要检查, 但检查返回码可能对于调试程序或理解函数确切的做了些什么是有用的.

一些标志可能因与其它标志不兼容而被移除, 例如:

? 如果组合指定了两个或更多的星历(SEFLG_JPLEPH, SEFLG_SWIEPH, SEFLG_MOSEPH).
? 如果观测点标志(SEFLG_TOPOCTR) 与日心标志(SEFLG_HELCTR) 或质心标志(SEFLG_BARYCTR) 同时指定.
? 等等.

一些标志可能在以下情况下被添加:
? 如果未指定星历标志, 返回值中将包含SEFLG_SWIEPH.
? 在 J2000 计算(SEFLG_J2000) 或其它恒星计算(SEFLG_SIDEREAL)时, 非章动标志(SEFLG_NONUT) 被添加
? 在日心(SEFLG_HELCTR) 和质心 (SEFLG_BARYCTR) 计算时, 标志“无偏差” (SEFLG_NOABERR) 和 “无光偏转” (SEFLG_NOGDEFL) 被添加.

3. 函数swe_get_planet_name()
该函数允许查找一个给定行星编号的行星或小行星名字. 该函数定义如下
char* swe_get_planet_name(int ipl, char *spname);

如果要查找一个小行星, 函数按以下方式进行:

? 首先在小行星文件中查找名字.
? 因为许多小行星, 特别是那些具有高总目号(catalogue number)的小行星, 还没有名字(或者只有一个初步命名如 1968 HB), 而且因为 IAU 的小行星中心经常添加新的名字, 就会发生这种情况，虽然小行星已经被给予了一个名字，但在小行星文件中确没有名字. 对于这一点, 我们有文件seasnam.txt, 这是一个包含所有通常是最新的命名的小行星列表的文件. 如果 swe_calc() 找到一个初步命名, 它会在该文件中查找名字.

文件seasnam.txt 可以由用户更新. 要更新该文件, 从小行星中心http://cfa-www.harvard.edu/iau/lists/MPNames.htmld下载名字列表, 更名它为seasnam.txt 并移动它到你的星历文件目录中.

文件 seasnam.txt 的内容不需要任何方式的排序. 但必须是每个小行星一行, 首先是它的总目号(catalogue number), 然后是它的名字. 小行星编号可以由括号括起来也可以不用括号.
示例:

(3192) A'Hearn
(3654) AAS
(8721) AMOS
(3568) ASCII
(2848) ASP
(677) Aaltje
  ...
4. 恒星函数
4.1 swe_fixstar_ut
函数 swe_fixstar_ut() 在 Swisseph 版本 1.60 中引入. 它与swe_fixstar() 完全相同除了它要求世界时而不是历书时作为输入值. (参见 swe_calc_ut() 和 swe_calc())
函数 swe_fixstar_ut() 和 swe_fixstar() 计算恒星. 它们定义如下:

long swe_fixstar_ut(char* star, double tjd_ut, long iflag, double* xx, char* serr);
其中
star =要搜索的恒星名字, 返回找到的恒星的名字
tjd_ut =世界时的儒略日
iflag =包含了一系列标志的整型用于指明需要哪种类型的计算
xx = 6 元素双精度数组包含经度, 纬度, 距离, 经度速度, 纬度速度, 和距离速度.
serr[256] =发生错误时包含错误信息的字符串.
 更多信息, 参见下面4.2. swe_fixstar()

4.2 swe_fixstar()
long swe_fixstar(char *star, double tjd_et, long iflag, double* xx, char* serr);
相同, 但  tjd_et=历书时的儒略日

参数star 必须提供至少41 个字符为返回恒星名字. 如果找到了星体, 它的名字按以下格式返回于该字段中:
传统名称, 专门名称 例如 "Aldebaran,alTau".

函数有三种模式从文件fixstars.cat中搜索一个星体:

? star 包含一个正数(ASCII 串格式, 例如 "234"):使用文件 fixstars.cat 中的第234个非注释行. 注释行以# 开头并被忽略.
? star 包含一个传统的名字: 文件 fixstars.cat 中的第一个星使用其适合给定名称的传统名称. 比较前所有的名字都被映射为小写. 如果 star 有 n 个字符, 只比较传统名称开头n 个字符. 如果一个逗号出现在一个非零长度的传统名称后面,搜索前逗号被去掉. 这允许在下一次调用中重复使用前一次调用返回的星名的.
? star 开始于一个逗号, 跟随着一个专门名称, 例如 ",alTau":在命名字段中具有此名称的恒星将返回(第二个字段 ). 字母的大小写在比较专门名称时会被观测到.

对于正确拼写命名名字, 参见fixstars.cat. 命名名字通常是由一个希腊字母和一个星座的名字组成的. 希腊字母原本是用来写用于记录星座的星的数字的. 我们在fixstars.cat中使用的命名名字的缩写都是由两个小写字母组成的希腊字母 (例如 ”al” 对于 ”alpha”) 和三个星座的字母(例如 ”Tau” for ”Tauri”).

函数和 DLL 会再生受损的包含非法数据和星名超过可接受长度的 fixstars.cat 文件. 这样的字段被切短到可接受的长度.
在文件 fixstars.cat中有两个特殊的入口:

? 一个是银河中心的入口, 名为"Gal. Center" 带一个空格.
? 一个名为"AA_page_B40" 星体它是天文年历星体计算样本  (我们过去两年的圣经), 第 B40 页.

你必须编辑星体总目并移动你喜欢的星到文件的项部. 这将加快你计算的速度. 每次调用swe_fixstar()时搜索模式是线性的通过整个文件.
至于其他参数的解释, 参见swe_calc().
重心位置未实现. 地心和以太阳为中心的恒星位置之间的区别是明显的, 来自视差和重力偏转.
注意: swe_fixstar() 不计算恒星的速度. 如果你需要它们, 你必须自己计算它们, 第二次或第三次调用swe_fixstar().

4.3 swe_fixstar_mag()
long swe_fixstar_mag(char *star, double* mag, char* serr);

函数计算恒星的星等. 函数返回 OK 或 ERR. 星等值在参数 mag 中返回.
关于参数 star 的定义和使用参见函数swe_fixstar(). 通常参数 serr 是一个指向错误串的指针.

5. 开普勒根数, 拱点和交点, 轨道周期
5.1 swe_nod_aps_ut
函数 swe_nod_aps_ut() 和 swe_nod_aps() 计算行星的交点和拱点 ( 近日点, 远日点, 第二轨道椭圆的焦点). 两个函数功能完全相同除了它们期待不同的时间参数外(参见 swe_calc_ut() 和 swe_calc() ).

函数定义如下:

int32 swe_nod_aps_ut(double tjd_ut, int32 ipl, int32 iflag, int32 method, double *xnasc, double *xndsc, double *xperi, double *xaphe, char *serr);
其中
tjd_ut =世界时的儒略日
ipl  =行星编号
iflag =与swe_calc_ut() 和 swe_fixstar_ut() 相同
method =指定计算方法的另一个整型数, 见下面解释
xnasc =6元素双精度数组 包含 升交点 数据
xndsc =6元素双精度数组 包含 降交点 数据
xperi =6元素双精度数组 包含 近日点 数据
xaphe =6元素双精度数组 包含 远日点 数据
serr[256]  =发生错误时用于包含错误信息的字符串.
5.2 swe_nod_aps()
int32 swe_nod_aps(double tjd_et, int32 ipl, int32 iflag, int32 method, double *xnasc, double *xndsc, double *xperi, double *xaphe, char *serr);
相同, 但
tjd_et = 历书时的儒略日

参数 iflag 与函数 swe_calc_ut() 使用的该参数相同. 即, 它包含了星历标志, 以太阳为中心的, 地面点的, 速度, 章动标志等等.
参数 method 告诉函数需要什么种类的交点或拱点:

#define SE_NODBIT_MEAN  1
平交点和拱点计算拥有它们的星体, 即月亮和行星水星通过海王星, 密切的冥王星和小行星. 这是默认的方法, 也用于 method=0.

#define SE_NODBIT_OSCU  2
所有星体的吻切点拱点都计算.

#define SE_NODBIT_OSCU_BAR 4
所有星体的吻切点拱点都计算. 木星以外的行星, 交点和拱点从重心位置 和速度计算. 参见 swisseph.doc 中的说明.

如果该标志位组合了SE_NODBIT_MEAN, 平均值由行星水星 - 海王星给出.

#define SE_NODBIT_FOPOINT 256
轨道椭圆的第二个焦点被计算并在数组 xaphe 中返回. 该位可以与其它的任何位组合.


5.3 swe_get_orbital_elements()
此函数计算行星, 地月质心, 或小行星的吻切根数 (开普勒根数) 和轨道周期. 元素的计算相对于平黄道 J2000.
元素定义轨道椭圆的前提是它是一个双体系统也没有来自其它天体的摄动. 这些元素对月亮特别不利, 这是由太阳的强烈扰动. 不推荐用开普勒根数计算星历表.
 
int32 swe_get_orbital_elements(
  double tjd_et,
  int32 ipl, int32 iflag,
  double *dret,
  char *serr);

/* 函数计算行星或小行星或地月质心的吻切轨道参数 (开普勒根数)
 * 函数返回错误, 如果调用它来计算太阳, 月球交点,
 * 或拱点
 * 输入参数:
 * tjd_et       儒略日数, in TT (ET)
 * ipl          对象编号
 * iflag        可以包含
 *              - 星历标志: SEFLG_JPLEPH, SEFLG_SWIEPH, SEFLG_MOSEPH
 *              - 中心:
 *                太阳:            SEFLG_HELCTR (假定为默认) 或
 *                SS 质心:  SEFLG_BARYCTR  (相对于太阳第质心)
 *                                (仅木星外的行星可能)
 *                对于月亮的元素, 计算是以地球为中心的.
 *              - 求计算轨道内所有质量(天文年历的方法):
 *                                SEFLG_ORBEL_AA
 *              -参考黄道: SEFLG_J2000;
 *               如果错过了, 选择日期的平黄道(还没有实现)
 * 输出参数:
 * dret[]       返回值数组, 定义为dret[50]
 * dret[0]      半长轴(a)
 * dret[1]      偏心距(e)
 * dret[2]      倾斜(in)
 * dret[3]      升交点经度(大写 omega OM)
 * dret[4]      近拱点表达式(小写 omega om)
 * dret[5]      近拱点经度 (peri)
 * dret[6]      平近点角 at epoch (M0)
 * dret[7]      真近点角 at epoch (N0)
 * dret[8]      偏近点角 at epoch (E0)
 * dret[9]      平经度 at epoch (LM)
 * dret[10]     恒星轨道周期 in 回归年
 * dret[11]     平均日运动
 * dret[12]     回归周期年数
 * dret[13]     会合周期日数,
 *                  负值, 如果是内行星(金星, 水星, 阿登型小行星) 或月亮
 * dret[14]     近日点经过时间
 * dret[15]     近日点距离
 * dret[16]     远日点距离
*/


5.4 swe_orbit_max_min_true_distance()
此函数计算行星, 地月质心, 或小行星的最大可能距离, 最小可能距离, 和当前真距离. 计算可以是以太阳为中心的或以地球为中心的. 若是以太阳为中心的计算, 它是基于行星的瞬间开普勒椭圆. 地心的计算, 它是基于行星和地月质心的瞬间开普勒椭圆. 地心的计算是消耗相当大的..

int32 swe_orbit_max_min_true_distance(double tjd_et, int32 ipl, int32 iflag, double *dmax, double *dmin, double *dtrue, char *serr)
/* 输入:
 * tjd_et       epoch
 * ipl          行星编号
 * iflag        星历标志可选的日心标志 (SEFLG_HELCTR)
 *
 * 输出:
 * dmax         最大距离 (指向双精度的指针)
 * dmin         最小距离 (指向双精度的指针)
 * dtrue        真距离 (指向双精度的指针)
 * serr         错误串
 */

 6. 食, 升, 落, 中天, 行星现象

以下函数用于食和掩星计算.

日食:
? swe_sol_eclipse_when_loc( tjd...)查找给定地理位置的下一次月食.
? swe_sol_eclipse_when_glob( tjd...) 找到全球下一次月食.
? swe_sol_eclipse_where() 计算给定 tjd 的日食的地理位置.
? swe_sol_eclipse_how() 计算给定 tjd , 地理经度, 纬度和高度的日食的属性.

月掩星:
这些函数也可用于日食计算. 但他们的效率略低.
? swe_lun_occult_when_loc( tjd...) 找到一个星体给定地理位置的下一个掩星.
? swe_lun_occult_when_glob( tjd...) 找到给定星体的全球的下一个掩星.
? swe_lun_occult_where() 计算给定 tjd 的掩星的地理位置.

月食:
? swe_lun_eclipse_when_loc(tjd...) 为给定地理位置找到下一个月食.
? swe_lun_eclipse_when(tjd...) 找到下一个月食.
? swe_lun_eclipse_how() 计算一个给定 tjd 的月食的属性.

行星和恒星的升, 落, 和中天:
? swe_rise_trans()
? swe_rise_trans_true_hor( ) 返回一个本地水平高度不为零的升和落时间

行星现象:
? swe_pheno_ut() and swe_pheno() 计算太阳，月亮所有行星和小行星的日地距角, 相, 距, 视直径, 和视星等.
 

6.0. 典型的日食计算示例
找到下一次的日食, 计算最大食和四切的地理位置(对于所有的日食功能的详细解释，看下一章):

double tret[10], attr[20], geopos[10];
char serr[255];
int32 whicheph = 0; /* 默认星历 */
double tjd_start = 2451545; /* 2000年1月1日的儒略日数*/
int32 ifltype = SE_ECL_TOTAL | SE_ECL_CENTRAL | SE_ECL_NONCENTRAL;
/* 寻找地球上任何地方的下一次日食*/
eclflag = swe_sol_eclipse_when_glob(tjd_start, whicheph,  ifltype, tret, 0, serr);
if (eclflag == ERR)
  return ERR;
/* 最大食时间已经在tret[0]中返回;
 * 现在我们可以查找最大日食的地理位置*/
tjd_start = tret[0];
eclflag = swe_sol_eclipse_where(tjd_start, whicheph, geopos, attr, serr);
if (eclflag == ERR)
  return ERR;
/*最大日食的地理位置是在geopos[0] 和 geopos[1] 中;
 * 现在可以计算这个地方的四切. 选择时间
 * 最大食发生时的前一天: */
tjd_start = tret[0] - 1;
eclflag = swe_sol_eclipse_when_loc(tjd_start, whicheph, geopos, tret, attr, 0, serr);
if (eclflag == ERR)
  return ERR;
/* 现在tret[] 包含了以下值:
 * tret[0] = 最大日食时间 (儒略日数)
 * tret[1] = 初亏
 * tret[2] = 食既
 * tret[3] = 生光
 * tret[4] = 复圆 */

6.1. swe_sol_eclipse_when_loc()

要查找给定地理位置的下一个食, 使用 swe_sol_eclipse_when_loc().

int32 swe_sol_eclipse_when_loc(
double tjd_start,  /* 搜索的起始日期, 儒略日 UT */
int32 ifl,  /* 星历标志*/
double *geopos,  /* 3 元素双精度数组for 地理经度，纬度，高度.
                                 东经为正,
     西经为负,
                                 北纬为正,
     南纬为负 */
double *tret,  /* 返回数组, 10 元素双精度数组, 见下 */
double *attr,  /* 返回数组, 20 元素双精度数组, 见下 */
AS_BOOL backward,  /* TRUE, 如果向前搜索 */
char *serr); /* 返回错误串 */

函数返回:
/* retflag -1 (ERR) 发生错误 (例如 如果 swe_calc() 计算太阳或月亮失败)
    SE_ECL_TOTAL or SE_ECL_ANNULAR or SE_ECL_PARTIAL
   SE_ECL_VISIBLE,
   SE_ECL_MAX_VISIBLE,
   SE_ECL_1ST_VISIBLE, SE_ECL_2ND_VISIBLE
   SE_ECL_3ST_VISIBLE, SE_ECL_4ND_VISIBLE
 
  tret[0] 最大食时间
  tret[1] 初亏时间
  tret[2] 食既时间
  tret[3] 生光时间
  tret[4] 复圆时间
  tret[5] 第一切和第四切之间的日出时间
  tret[6] 第一切和第四切之间的日落时间 
 
 attr[0] 月球覆盖太阳直径的比例;
    对于 全/环食, 它的结果为magnitude acc. to IMCCE.
 attr[1] 月球直径与太阳之比
 attr[2] 月球覆盖太阳直径的比例 (掩星)
 attr[3] 核心阴影直径 in km
 attr[4] 太阳方位角 at tjd
 attr[5] 太阳地平线以上的真实高度 at tjd
 attr[6] 太阳在地平线以上的表观高度 at tjd
 attr[7] 月亮角距 单位为角度
 attr[8]         magnitude acc. to NASA;
                       = attr[0] for 偏食而 attr[1] for 环食和全食
 attr[9] 沙罗序列号 
 attr[10] 沙罗序列成员号
*/

6.2. swe_sol_eclipse_when_glob()

要找到下一个全球的食:
int32 swe_sol_eclipse_when_glob(
double tjd_start,  /* 搜索的起始日期, 儒略日 UT */
int32 ifl,   /* 星历标志*/
int32 ifltype,  /* 想要的日食类型: SE_ECL_TOTAL 等. 或 0, 为任何日食类型*/
double *tret,  /* 返回数组, 10 元素双精度数组, 见下 */
AS_BOOL backward,  /* TRUE, 如果向前搜索 */
char *serr);  /* 返回错误串 */

此函数要求时间参数tjd_start 是世界时 并且返回值(tret[]) 是UT(世界时).  要在 ET(历书时) 和 UT 间转换, 使用函数 swe_deltat().

注意: 一个该此函数的使用历书时作为参数的实现会有可能. 问题是什么时候下一个日食将在地球上任何地方发生是独立于地球的旋转位置并因此独立于Delta T. 但是, 函数经常与其它食函数组合使用 (参见下面的示例), 对于哪一个输入和输出是使用历书时(ET)是没有意义的, 因为他们关系到一个日食的当地情况, 因此是依赖于地球的旋转位置. 因为这个原因, 世界时(UT)被选为所有食函数时间参数.

ifltype 指定想要的食的类型. 它可以是以下位的组合(参见swephexp.h):

#define SE_ECL_CENTRAL  1
#define SE_ECL_NONCENTRAL  2
#define SE_ECL_TOTAL    4
#define SE_ECL_ANNULAR   8
#define SE_ECL_PARTIAL   16
#define SE_ECL_ANNULAR_TOTAL 32

ifltype 的推荐值:
/* 搜索任何食, 不论类型*/
ifltype = 0; 
/* 搜索一个全食; 注意: 非中心全食非常罕见 */
ifltype = SE_ECL_TOTAL | SE_ECL_CENTRAL | SE_ECL_NONCENTRAL;
/* 搜索一个环食 */
ifltype = SE_ECL_ANNULAR | SE_ECL_CENTRAL | SE_ECL_NONCENTRAL;
/* 搜索一个全环食(混合的) */
ifltype_ = SE_ECL_ANNULAR_TOTAL | SE_ECL_CENTRAL | SE_ECL_NONCENTRAL;
/* 搜索一个偏食 */
ifltype = SE_ECL_PARTIAL;

如果你的代码不能正确运行, 请学习 swetest.c 中的示例代码.

函数返回:

/* retflag -1 (ERR) 发生错误 (例如 如果 swe_calc() 计算太阳或月亮失败)
  SE_ECL_TOTAL or SE_ECL_ANNULAR or SE_ECL_PARTIAL or SE_ECL_ANNULAR_TOTAL
  SE_ECL_CENTRAL
  SE_ECL_NONCENTRAL

  tret[0] 最大食时间
  tret[1] 日食发生在当地视正午的时间
  tret[2] 日食开始时间
  tret[3] 日食结束时间
  tret[4] 全食开始时间
  tret[5] 全食结束时间
  tret[6] 中心线开始时间
  tret[7] 中心线结束时间
  tret[8] 环全食变成全食时间, 尚未实现
  tret[9] 环全食再变成环食时间, 尚未实现

 最小定义大小为tret[10] !
 */
6.3. swe_sol_eclipse_how ()

要计算给定地理位置和时间的日食的属性:

int32 swe_sol_eclipse_how(
double tjd_ut,  /* 时间, 儒略日 UT */
int32 ifl,  /* 星历标志*/
double *geopos /* 地理经度, 纬度, 海拔高度.
     * 东经为正,
    * 西经为负,
    * 北纬为正,
    * 南纬为负 */
double *attr,  /* 返回数组, 20 元素双精度数组, 见下 */
char *serr); /* 返回错误串 */

/* retflag  -1 (ERR) 发生错误 (例如 如果 swe_calc() 计算太阳或月亮失败)
   SE_ECL_TOTAL or SE_ECL_ANNULAR or SE_ECL_PARTIAL
   0,如果在地理位置没有日食可见.
 
 attr[0] 月球覆盖太阳直径的比例;
    对于全/环食, it results in magnitude acc. to IMCCE.
 attr[1] 月球直径与太阳之比
 attr[2] 月球覆盖太阳直径的比例 (obscuration)
 attr[3] 核心阴影直径 in km
 attr[4] 太阳方位角 at tjd
 attr[5] 太阳地平线以上的真实高度 at tjd
 attr[6] 太阳在地平线以上的表观高度 at tjd
 attr[7] 月亮角距 单位为角度
 attr[8]        星等 acc. to NASA;
                       = attr[0] 对于偏食而 attr[1] 对于环食和全食
 attr[9] 沙罗序列号 
 attr[10] 沙罗序列成员号

6.4. swe_sol_eclipse_where ()

此函数可用于找出日食的地理位置, 其中, 对于一个给定的时间,中心食是中心或非中心食是最大.
如果你想在地图上绘制全食或环食的日食路径,首先用 swe_sol_eclipse_when_glob() 计算全食或环食的开始和结束时间, 然后调用 swe_sol_eclipse_how() 数次来得到中心路径的地理位置. 北部和南部的本影和半影的范围还没有实现.

int32 swe_sol_eclipse_where (
double tjd_ut,  /* 时间, 儒略日 UT */
int32 ifl,   /* 星历标志*/
double *geopos, /* 返回数组, 2元素双精度数组, 地理经度和纬度
    * 东经为正,
    * 西经为负,
    * 北纬为正,
    * 南纬为负 */
double *attr,  /* 返回数组, 20 元素双精度数组, 见下 */
char *serr);  /* 返回错误串 */
函数返回:

/* -1 (ERR) 发生错误(例如 如果 swe_calc() 计算太阳或月亮失败)
  0  如果没有日食在 tjd
  SE_ECL_TOTAL
  SE_ECL_ANNULAR
  SE_ECL_TOTAL | SE_ECL_CENTRAL
  SE_ECL_TOTAL | SE_ECL_NONCENTRAL
  SE_ECL_ANNULAR | SE_ECL_CENTRAL
  SE_ECL_ANNULAR | SE_ECL_NONCENTRAL
  SE_ECL_PARTIAL
 
  geopos[0]: 中心线地理经度
  geopos[1]: 中心线地理纬度
 
  当前未实现:
  geopos[2]: 本影北界线地理经度
  geopos[3]: 本影北界线地理纬度
  geopos[4]: 本影南界线地理经度
  geopos[5]: 本影南界线地理纬度
  geopos[6]: 半影北界线地理经度
  geopos[7]: 半影北界线地理纬度
  geopos[8]: 半影南界线地理经度
  geopos[9]: 半影南界线地理纬度
 
  东经是正值,
  西经是负值,
  北纬是正值,
  南纬是负值
 
  attr[0] 月球覆盖的太阳直径之比
  attr[1] 月球直径与太阳直径之比
  attr[2] 月球覆盖的太阳面积之比(掩盖面积比)
  attr[3] 核心阴影直径单位为 km
  attr[4] 太阳方位单位为 tjd
  attr[5] 太阳地平线以上的真实高度单位为 tjd
  attr[6] 太阳在地平线以上的表观高度单位为 tjd
  attr[7] 太阳与月亮的角距离单位为度
  attr[8]   食分 (= attr[0] 或 attr[1] 取决于食的类型)
  attr[9]   沙罗序列号 
  attr[10]   沙罗序列成员号

  定义大小为 attr[20]!
 */

6.5. swe_lun_occult_when_loc()
要找到给定位置的行星或恒星的下一个月掩星, 使用 swe_lun_occult_when_loc().
相同的函数也可代替swe_sol_eclipse_when_loc()用于计算本地日食, 但效率稍低.

/* 与 swe_sol_eclipse_when_loc()相同的声明.
 * 另外:
 * int32 ipl           掩星星体的行星编号
 * char* starname      掩星恒星的名字. 如果是行星则必须是NULL 或 ""
 *                     掩星才能计算. 对于使用该字段,
 *                         参见 swe_fixstar().
 * int32 ifl         星历标志. 如果你想只有一个月亮与星体的合, 添加以下标志:
 *                     backward |= SE_ECL_ONE_TRY. 如果此标志未设置,
 *                     函数将搜索掩星直到它
 *                     找到为止. 对于黄道纬度 > 5 的星体,
 *                     函数可能不会成功直到它搜索到
 *                     星历文件尾部.
 */
int32 swe_lun_occult_when_loc(
double tjd_start,  /* 搜索的起始日期, 儒略日 UT */
int32 ipl,  /* 行星编号 */
char* starname,  /* 恒星名, 如果不是恒星则必须是NULL 或 ”” */
int32 ifl,  /* 星历标志*/
double *geopos,  /* 3 元素双精度for 地理经度, 纬度, 海拔高度.
     * 东经为正,
    * 西经为负,
    * 北纬为正,
    * 南纬为负 */
double *tret,  /* 返回数组, 10 元素双精度数组, 见下 */
double *attr,  /* 返回数组, 20 元素双精度数组, 见下 */
AS_BOOL backward,  /* TRUE, 如果向前搜索 */
char *serr); /* 返回错误串 */

一些星体的掩星可能非常罕见，或根本不会发生. 通常函数搜索一个事件直到它找一个或搜索到星历文件尾部. 为了避免无尽的循环, 函数可以使用标志 ifl |= SE_ECL_ONE_TRY 调用. 如果用此标志调用, 函数搜索下一个日期 当月亮与对象连接并找出它是否是一个掩星. 函数不检查任何在未来或过去的其它连接.

如果返回值 > 0, 有一个掩星且tret 和 attr 包含关于它的信息.
如果返回值 = 0, 没有掩星; tret[0] 包含最接近的连接的日期.
如果返回值 = -1, 发生错误.

为了查找一个具体的时间范围内的事件(tjd_start < tjd < tjd_stop), 一个可以写一个循环并调用函数(往往是日期 tjd < tjd_stop).  每次调用后, 增加 tjd = tret[0] + 2.

如果有一组星体或行星想在相同的时间范围内查找掩星, 每个这些对象都必须运行同一个循环. 如果事件必须按时间顺序列出, 必须在输出之前对它们进行排序.

函数返回:
/* retflag 
         -1 (ERR) 发生错误 (例如 如果 swe_calc() 计算太阳或月亮失败)
         0  (如果没有掩星/没有日食找到)
    SE_ECL_TOTAL or SE_ECL_ANNULAR or SE_ECL_PARTIAL
   SE_ECL_VISIBLE,
   SE_ECL_MAX_VISIBLE,
   SE_ECL_1ST_VISIBLE, SE_ECL_2ND_VISIBLE
   SE_ECL_3ST_VISIBLE, SE_ECL_4ND_VISIBLE
  这些返回值 (除了SE_ECL_ANNULAR) 同时出现在掩星.
 
  tret[0] 最大食时间
  tret[1] 初亏时间
  tret[2] 食既时间
  tret[3] 生光时间
  tret[4] 复圆时间
  tret[5] 第一切和第四切之间的日出时间 (尚未实现)
  tret[6] 第一切和第四切之间的日落时间  (尚未实现)
 
  attr[0] 月球覆盖太阳直径的比例 (magnitude)
  attr[1] 月球直径与太阳之比
  attr[2] 月球覆盖的太阳圆盘的部分(掩星)
  attr[3] 核心阴影直径 in km
  attr[4] 太阳方位角 at tjd
  attr[5] 太阳地平线以上的真实高度 at tjd
  attr[6] 太阳在地平线以上的表观高度 at tjd
  attr[7] 月亮角距 单位为角度 */

6.6. swe_lun_occult_when_glob()
要找到下一个全球的行星或恒星的月掩星(没有一个特定的地理位置), 使用 swe_lun_occult_when_glob().
相同的函数也查以用于查找全球的日食用于替代swe_sol_eclipse_when_glob(),但效率有点不高.

/* 与 swe_sol_eclipse_when_glob() 定义相同.
 * 另外:
 * int32 ipl           掩星星体的行星编号
 * char* starname      掩星恒星的名字. 如果是行星则必须是NULL 或 ""
 *                     掩星才能计算. 对于使用该字段,
 *                        参见 swe_fixstar().
* int32 ifl         星历标志. 如果你想只有一个月亮与星体的合, 添加以下标志:
 *                     backward |= SE_ECL_ONE_TRY. 如果此标志未设置,
 *                     函数将搜索掩星直到它找到为止. 对于黄道纬度 > 5 的星体,
 *                     函数可能不会成功直到它搜索到星历文件尾部.
 */
int32 swe_lun_occult_when_glob(
double tjd_start,  /* 搜索的起始日期, 儒略日 UT */
int32 ipl,  /* 行星编号 */
char* starname,  /* 恒星名, 如果不是恒星则必须为NULL 或 ”” */
int32 ifl,  /* 星历标志*/
int32 ifltype,  /* 想要的食类型 */
double *tret,  /* 返回数组, 10 元素双精度数组, 见下 */
AS_BOOL backward,  /* TRUE, 如果向前搜索 */
char *serr); /* 返回错误串 */

一个关于 ifl |= SE_ECL_ONE_TRY 的解释在前面段落关于函数 swe_lun_occult_when_loc() 中给出.

函数返回:

/* retflag 
         -1 (ERR) 发生错误 (例如 如果 swe_calc() 计算太阳或月亮失败)
         0  (如果无掩星 / 日食找到)
  SE_ECL_TOTAL or SE_ECL_ANNULAR or SE_ECL_PARTIAL or SE_ECL_ANNULAR_TOTAL
  SE_ECL_CENTRAL
  SE_ECL_NONCENTRAL
 
  tret[0] 最大食时间
  tret[1] 时间, 当日食发生在地方视正午
  tret[2] 日食开始时间
  tret[3] 日食结束时间
  tret[4] 全食开始时间
  tret[5] 全食结束时间
  tret[6] 中心线开始时间
  tret[7] 中心线结束时间
  tret[8] 环全食变为全食的时间 尚未实现
  tret[9] 环全食再变为环食的时间 尚未实现

 至少定义为tret[10]
 */

6.7. swe_lun_occult_where ()

类似于 swe_sol_eclipse_where(), 此函数可用于找出地理位置, 其中, 对于给定时间, 中心食是中心而非中心食是最大. 使用掩星, 它告诉我们, 在哪一地理位置的掩星在月球盘的中央或接近它的中间. 因为掩星总是在很大区域都是可见的, 这不是很有趣的信息. 但它可能会因本影（和半影）的限制即将实现而变得更加有趣.

int32 swe_lun_occult_where (
double tjd_ut,  /* 时间, 儒略日 UT */
int32 ipl,  /* 行星编号 */
char* starname,  /* 恒星的名字. 如果是不是恒星则必须是NULL 或 "" */
int32 ifl,   /* 星历标志*/
double *geopos, /* 返回数组, 2 元素双精度数组, 地理经度和纬度
    * 东经为正,
    * 西经为负,
    * 北纬为正,
    * 南纬为负 */
double *attr,  /* 返回数组, 20 元素双精度数组, 见下 */
char *serr);  /* 返回错误串 */
函数返回:

/* -1 (ERR) 发生错误 (例如 如果 swe_calc() 计算太阳或月亮失败)
  0  如果没有日食 (掩星) 在给定的 tjd
  SE_ECL_TOTAL
  SE_ECL_ANNULAR
  SE_ECL_TOTAL | SE_ECL_CENTRAL
  SE_ECL_TOTAL | SE_ECL_NONCENTRAL
  SE_ECL_ANNULAR | SE_ECL_CENTRAL
  SE_ECL_ANNULAR | SE_ECL_NONCENTRAL
  SE_ECL_PARTIAL
 
  geopos[0]: 中心线地理经度
  geopos[1]: 中心线地理纬度
 
  尚未实现:
  geopos[2]: 本影北界线地理经度
  geopos[3]: 本影北界线地理纬度
  geopos[4]: 本影南界线地理经度
  geopos[5]: 本影南界线地理纬度
  geopos[6]: 半影北界线地理经度
  geopos[7]: 半影北界线地理纬度
  geopos[8]: 半影南界线地理经度
  geopos[9]: 半影南界线地理纬度
 
东经为正,
  西经为负,
  北纬为正,
  南纬为负
 
  attr[0] 月球覆盖太阳直径的比例 (magnitude)
  attr[1] 月球直径与太阳之比
  attr[2] 月球覆盖太阳直径的比例 (obscuration)
  attr[3] 核心阴影直径 in km
  attr[4] 太阳方位角 at tjd
  attr[5] 太阳地平线以上的真实高度 at tjd
  attr[6] 太阳在地平线以上的表观高度 at tjd
  attr[7] 太阳与月亮的角距离 单位为角度

  定义为 attr[20]!
 */
6.8.a. swe_lun_eclipse_when_loc ()
要找到给定地理位置的下一个的月食:

int32 swe_lun_eclipse_when_loc(
double tjd_start,  /* 搜索的起始日期, 儒略日 UT */
int32 ifl,   /* 星历标志*/
double *geopos,  /* 3 元素双精度为地理经度, 纬度, 海拔高度.
     * 东经为正,
    * 西经为负,
    * 北纬为正,
    * 南纬为负 */
double *tret,  /* 返回数组, 10 元素双精度型, 见下 */
double *attr,  /* 返回数组, 20元素双精度型, 见下*/
AS_BOOL backward,  /* TRUE, 如果向前搜索*/
char *serr);  /* 返回错误串 */

如果你的代码不能正确运行, 请学习 swetest.c 中的示例代码.

函数返回:

/* retflag      SE_ECL_TOTAL or SE_ECL_PENUMBRAL or SE_ECL_PARTIAL
 *
 * tret[0]      最大食时间
 * tret[1]
 * tret[2]      偏食开始时间(指标符合日食)
 * tret[3]      偏食结束时间
 * tret[4]      全食开始时间
 * tret[5]      全食结束时间
 * tret[6]      半影食开始时间
 * tret[7]      半影食结束时间
 * tret[8]      月出时间, 如果它发生在月食期间
 * tret[9]      月落时间, 如果它发生在月食期间
 *
 * attr[0]      本影食分 at tjd
 * attr[1]      半影食分
 * attr[4]      月亮方位角 at tjd
 * attr[5]      水平线以上月亮真高度at tjd
 * attr[6]      水平线以上月亮视高度at tjd
 * attr[7]      月球反面的距离 单位为角度
 * attr[8]      本影食分 at tjd (= attr[0])
 * attr[9]      沙罗序列号
 * attr[10]     沙罗序列成员号 */

6.8.b. swe_lun_eclipse_when ()
要找到下一个月食:

int32 swe_lun_eclipse_when(
double tjd_start,  /* 搜索的起始日期, 儒略日 UT */
int32 ifl,   /* 星历标志*/
int32 ifltype,  /* 想要的食类型: SE_ECL_TOTAL 等.  或 0, 如果任何月食类型*/
double *tret,  /* 返回数组, 10 元素双精度数组, 见下 */
AS_BOOL backward,  /* TRUE, 如果向前搜索 */
char *serr);  /* 返回错误串 */

ifltype 的推荐值:
/* 搜索任意月食, 不再乎类型*/
ifltype = 0; 
/* 搜索月全食 */
ifltype = SE_ECL_TOTAL;
/* 搜索月偏食 */
ifltype = SE_ECL_PARTIAL;
/* 搜索半影月食 */
ifltype = SE_ECL_PENUMBRAL;

如果你的代码不能正确运行, 请学习 swetest.c 中的示例代码.

函数返回:

/* retflag  -1 (ERR) 发生错误 (例如为太阳或月亮调用 swe_calc() 失败)
    SE_ECL_TOTAL or SE_ECL_PENUMBRAL or SE_ECL_PARTIAL
  tret[0] 最大食时间
  tret[1] 
  tret[2] 偏食开始时间(指标符合日食)
  tret[3] 偏食结束时间
  tret[4] 全食开始时间
  tret[5] 全食结束时间
  tret[6] 半影食开始时间
  tret[7] 半影食结束时间
 */

6.9. swe_lun_eclipse_how ()

此函数计算给定时间的月食的属性:

int32 swe_lun_eclipse_how(
double tjd_ut,  /* 时间, 儒略日 UT */
int32 ifl,   /* 星历标志*/
double *geopos,  /* 输入数组, 经度, 纬度, 高度
   东经为正,
   西经为负,
   北纬为正,
   南纬为负 */
double *attr,  /* 返回数组, 20 元素双精度数组, 见下 */
char *serr);  /* 返回错误串 */

函数返回:

/* retflag  -1 (ERR) 发生错误 (例如 如果 swe_calc() 计算太阳或月亮失败)
    SE_ECL_TOTAL or SE_ECL_PENUMBRAL or SE_ECL_PARTIAL
   0  如果没有月食

attr[0] 本影食分 at tjd
attr[1] 半影食分
attr[4] 月亮方位角 at tjd. 尚未实现
attr[5] 月亮在地平线真高度 at tjd. 尚未实现
attr[6] 月亮在地平线视高度 at tjd. 尚未实现
attr[7] 月球的相对距离单位为角度
attr[8]   食分 (= attr[0])
attr[9]   沙罗序列号 
attr[10]   沙罗序列成员号

          至少定义为attr[20]
 */

6.10. swe_rise_trans() 和 swe_rise_trans_true_hor() (升, 降, 中天)

函数 swe_rise_trans() 计算所有行星, 小行星, 月亮, 和恒星的升, 降, 中天时间. 函数 swe_rise_trans_true_hor() 进行对本地水平线高度 != 0进行相同计算.

函数返回一个对象的上升时间,
- 如果在T0的对象是在地平线之下, 而且一个上升发生在对象的下一个顶点之前
- 如果在T0的对象是在地平线之上, 而且一个上升发生对象的接下来的上、下顶点之间.
而且它返回一个对象的下降时间,
-如果在T0的对象是在地平线之上,  而且一个下降发生在对象的下一个下顶点之前
-如果在T0的对象是在地平线之下,  而且一个下降发生在对象的下一个上、下顶点之间.

注意, “顶点” 并不意味着中天, 特别是对于太阳, 月亮和行星. 正在移动的星体的顶点的赤纬变化不是确切地发生在中天上,  而稍微在中天的前后. 在极地地区, 甚至发生月亮“升起”在顶点后不久的中天的西边. 即, 上缘, 如果它的园盘将在一个很短的时间可见. 函数 swe_rise_trans() 将捕捉这种情况.

函数定义如下:

int32 swe_rise_trans(
double tjd_ut,  /* 搜索该时间后 (UT) */
int32 ipl,   /* 行星编号, 如果行星或月亮 */
char *starname,  /* 恒星名, 如果恒星 */
int32 epheflag,  /* 星历标志*/
int32 rsmi,  /* 整型 指定想要的升, 落, 或上下中天. 参见下面的定义*/
double *geopos,  /* 3元素双精度数的数组
    *包含地理经度, 纬度, 观察者的高度 */
double atpress,  /* 大气压力 毫巴/hPa */
double attemp, /* 大气温度 摄氏度 */
double *tret,  /* 返回地址(双精度) 为升落等的时间. */
char *serr);  /* 返回错误信息地址 */

int32 swe_rise_trans_true_hor(
double tjd_ut,  /* 搜索该时间后 (UT) */
int32 ipl,   /* 行星编号, 如果行星或月亮 */
char *starname,  /* 恒星名, 如果恒星 */
int32 epheflag,  /* 星历标志*/
int32 rsmi,  /* 整型 指定想要的升, 落, 或上下中天. 参见下面的定义*/
double *geopos,  /* 3元素双精度数的数组
    * 包含地理经度, 纬度, 观察者的高度*/
double atpress,  /* 大气压力 毫巴/hPa */
double attemp, /* 大气温度 摄氏度 */
double horhgt, /* 星体升落点的本地水平线高度 in deg */
double *tret,  /* 返回地址(双精度) 为升落等的时间. */
char *serr);  /* 返回错误信息地址 */

第二个函数有一个额外的参数 horhgt 为星体升落点的本地水平线高度.

变量rsmi 可以具有以下值:

/* 对于 swe_rise_trans() 和 swe_rise_trans_true_hor() */
#define SE_CALC_RISE 1
#define SE_CALC_SET 2
#define SE_CALC_MTRANSIT 4 /* 上中天 (southern for northern geo. 纬度) */
#define SE_CALC_ITRANSIT 8 /* 下中天 (northern, 地平线以下) */
/* 以下位可以添加到 SE_CALC_RISE 或 SE_CALC_SET */
#define SE_BIT_DISC_CENTER         256     /* 圆盘中心的升落 */
#define SE_BIT_DISC_BOTTOM      8192     /* 圆盘下缘的升落*/
#define SE_BIT_NO_ REFRACTION    512      /* 如果不考虑折射*/
#define SE_BIT_CIVIL_TWILIGHT    1024    /* 为了计算民用曙暮光 */
#define SE_BIT_NAUTIC_TWILIGHT 2048    /* 为了计算航海曙暮光*/
#define SE_BIT_ASTRO_TWILIGHT   4096    /* 为了计算天文曙暮光*/
#define SE_BIT_FIXED_DISC_SIZE (16*1024) /* 忽略距离对圆盘大小的影响 */

rsmi = 0 将返回升.
升的时间取决于大气压力和温度. Atpress 大气压力单位为毫巴 (hectopascal); attemp 温度单位为摄氏度.
如果 atpress 给的值为0, 函数从 geopos[2] 和 attempt 给出的地理高度估计压力. 如果 geopos[2] 为0, atpress 将从海平面估计.

函数返回值是:
0 如果找到了升, 落或中天
-1 如果一个错误发生(通常是星历问题)
-2 如果升落事件因对象是在极地附近而未找到 


6.11. swe_pheno_ut() 和 swe_pheno(), 行星现象

这些函数计算太阳，月亮，所有行星和小行星的相, 日地距角, 距角, 视直径, 视星等. 两个函数除时间参数不同外其它完全相同.

int32 swe_pheno_ut(
double tjd_ut, /* 时间 儒略日 UT */
int32 ipl,   /* 行星编号 */
int32 iflag,   /* 星历标志*/
double *attr,  /* 返回数组, 20 元素双精度数组, 见下 */
char *serr);  /* 返回错误串 */

int32 swe_pheno(
double tjd_et, /* 时间 儒略日 ET */
int32 ipl,   /* 行星编号 */
int32 iflag,   /* 星历标志*/
double *attr,  /* 返回数组, 20 元素双精度数组, 见下 */
char *serr);  /* 返回错误串 */

函数返回:
/*
  attr[0] = 日地距角 (earth-planet-sun)
  attr[1] = 相 (圆盘被照亮的部分)
  attr[2] = 行星的距
  attr[3] = 圆盘的视直径
  attr[4] = 视星等

          declare as attr[20] at least !
 
  注意: 月球的星等是一件相当复杂的事情,
  但我们的算法很简单.
  月球的相位, 它与地球和太阳的距离被考虑，但没有其他因素.
 
  iflag 也允许 SEFLG_TRUEPOS, SEFLG_HELCTR
 */

6.12. swe_azalt(),水平座标, 方位角, 高度

swe_azalt() 从黄道或赤道坐标计算行星或恒星的水平座标 (方位角和高度).

void swe_azalt(
      double tjd_ut, // UT
      int32 calc_flag, // SE_ECL2HOR 或 SE_EQU2HOR
      double *geopos, // 3元素双精度数组: 地理经度, 纬度, 高度
      double atpress, // 大气压力 毫巴 (hPa)
      double attemp, // 大气温度 单位为摄氏度
      double *xin,  // 3元素双精度数组: 星体的黄道或赤道坐标位置,
   // 取决于 calc_flag
      double *xaz);  // 返回3元素双精度数组, 包含方位角, 真高度, 视高度

如果 calc_flag=SE_ECL2HOR, 设置 xin[0]= 黄道经度, xin[1]= 黄道纬度, (xin[2]=距离 (不要求));
否则
如果 calc_flag= SE_EQU2HOR, 设置 xin[0]=赤经, xin[1]=赤纬, (xin[2]= 距离 (不要求));

#define SE_ECL2HOR  0
#define SE_EQU2HOR  1

返回值是:
xaz[0] = 方位角, 即位置角度, 从南到西测量.
xaz[1] =地平线以上真高度 单位为角度.
xaz[2] =地平线以上视(折射)高度 单位为角度.

星体的视高度取决于大气压力和温度. 如果只要求真高度, 这些参数可以忽略.
如果 atpress 的值是0, 函数从geopos[2] 和 attempt 中给出的地理高度估计压力. 如果 geopos[2] 为 0, atpress 将从海平面估计.

6.13. swe_azalt_rev()
函数 swe_azalt_rev() 不是 swe_azalt() 相反的函数. 它从方位角和真高度计算黄道或赤道坐标. 如果只给出了视高度, 真高度必须首先用函数 swe_refrac() 算出(见下).
函数定义如下:

void swe_azalt_rev(
      double tjd_ut,
      int32 calc_flag, /* SE_HOR2ECL 或 SE_HOR2EQU */
      double *geopos, /* 3元素双精度数组 包含观测者的地理位置 */
      double *xin,   /* 2元素双精度数组 包含行星的方位角和真高度*/
      double *xout);  // 返回数组2元素双精度数组 包含黄道或赤道坐标, 取决于 calc_flag

关于方位角和真高度的定义, 参见4.9 的 swe_azalt().
#define SE_HOR2ECL  0
#define SE_HOR2EQU  1
6.14. swe_refrac(), swe_refract_extended(), 折射
折射函数 swe_refrac() 从视高度计算真高度或从视高度计算视高度. 它定义如下:

double swe_refrac(
double inalt,
double atpress,  /* 大气压力 毫巴 (hPa) */
double attemp,  /* 大气温度 单位为摄氏度*/
int32 calc_flag); /* SE_TRUE_TO_APP 或 SE_APP_TO_TRUE */
其中
#define SE_TRUE_TO_APP   0
#define SE_APP_TO_TRUE   1

折射取决于观测者位置的大气压力和温度.
如果 atpress 的值为0, 函数从geopos[2] 和 attempt 中给出的地理高度估计压力. 如果 geopos[2] 为 0, atpress 将从海平面估计.
还有一个更复杂的函数 swe_refrac_extended(),  它允许正确地计算海拔高度大于0时的折射, 理想地平和可视的行星可能有一个负的高度. (对于 swe_refrac(), 负高度不存在!)

double swe_refract_extended(
double inalt,  /* 对象几何地平线以上高度单位为角度,  几何地平线 =垂直重力平面*/
double geoalt,  /* 观测者海拔高度单位为米*/
double atpress,  /* 大气压力 毫巴 (hPa) */
double lapse_rate,  /* (dattemp/dgeoalt) = [°K/m] */
double attemp,  /* 大气温度摄氏度 */
int32 calc_flag); /* SE_TRUE_TO_APP 或 SE_APP_TO_TRUE */

函数返回:
情况1, 转换真高度到视高度:
- 视高度, 如果星体出现在理想地平线以上
- 真高度 (输入值), 否则
  "理想地平线"是地平线上所看到的一个理想的球体(从一架飞在海洋上清晰的天空上的飞机上看)
case 2, 转换从视高度到真高度:
- 真高度 结果从输入的视高度计算, 如果该值是一个貌似真实的视高度,
  即如果它是一个理想的地平线以上的位置
- 输入高度 否则

另外数组dret[] 返回以下值
- dret[0] 真高度, 如果可能; 否则为输入值
- dret[1] 视高度, 如果可能; 否则为输入值
- dret[2] 折射
- dret[3] 地平俯角

如果dret[0] != dret[1], 星体在地平线之上

6.15. 偕日升等: swe_heliacal_ut()
函数 swe_heliacal_ut() 查找给定的开始日期后面的下一个偕日升现象. 它处理范围是地理纬度 60s – 60n.

int32 swe_heliacal_ut(
double tjdstart,  /* 搜索偕日事件开始日期的儒略日数 */
double *dgeo                /* 地理位置 (细节见下) */
double *datm,  /* 大气条件 (细节见下) */
double *dobs,  /* 观察描述 (细节见下) */
char *objectname,        /* 恒星或行星的名字串 */
int32 event_type,  /* 事件类型 (细节见下) */
int32 helflag,  /* 计算标志, bitmap (细节见下) */
double *dret, /* 结果: 至少50元素的双精度数组, 目前只使用了其中的三个 */
char * serr /* 错误串 */
); 

函数返回 OK 或 ERR

dgeo[] (双精度数组)细节:
        dgeo[0]: 地理经度
        dgeo[1]: 地理纬度
        dgeo[2]: 地理高度 (眼睛高度) 单位为米

datm[] (双精度数组)细节:
        datm[0]: 大气压力 毫巴 (hPa)
        datm[1]: 大气温度 摄氏度
        datm[2]: 相对湿度 %
        datm[3]: 如果 datm[3]>=1, 则它是气象视距[km]
             if 1>datm[3]>0, 则它是大气总系数 (ktot)
                      datm[3]=0, 则其它的大气参数确定大气总系数 (ktot)
        默认值:
        如果这对你来说太多了, 设置所有值为0. 程序将设置以下默认值:
        压力1013.25, 温度15, 相对湿度 40. 这些值将会根据观测者的海拔高度修正.
        如果消光系数(气象视距) datm[3] 为 0, 程序将从datm[0..2]计算它的值.

dobs[] (双精度数组)细节:
        dobs[0]: 观测者年龄 (默认= 36)
        dobs[1]: 观察者的眼睛视力比(默认= 1 = normal)
如果标志 SE_HELFLAG_OPTICAL_PARAMS 设置, 下列参数相关:
        dobs[2]: 0 = monocular, 1 = binocular (actually a boolean)
        dobs[3]: telescope magnification: 0 = default to naked eye (binocular), 1 = naked eye
        dobs[4]: optical aperture (telescope diameter) in mm
        dobs[5]: optical transmission

event_type 细节:
        event_type = SE_HELIACAL_RISING (1): morning first (存在于所有可见的行星和恒星)
        event_type = SE_HELIACAL_SETTING (2): evening last (存在于所有可见的行星和恒星)
        event_type = SE_EVENING_FIRST (3): evening first (存在于水星, 金星, 和月亮)
        event_type = SE_MORNING_LAST (4): morning last (存在于水星, 金星, 和月亮)

helflag 细节:
        helflag 包含星历标志, 象 swe_calc() 中的 iflag 等. 另外它包含以下位:
        SE_HELFLAG_OPTICAL_PARAMS (512): 用于光学仪器的计算.
              除非该位设置,  dobs[2-5] 的值被忽略.
        SE_HELFLAG_NO_DETAILS (1024): 提供日期, 但不提供像可视开始、最佳、结束这样的细节.
              该让程序运行稍稍快一些.
        SE_HELFLAG_VISLIM_DARK (4096): 函数的行为就像太阳在天底.
        SE_HELFLAG_VISLIM_NOMOON (8192): 函数的行为就像月亮在天底, 即
              月亮被作为一个干扰观测的因素被排除在外. 这个标志是有用的, 如果你并非真正对那个特定年份的偕日日期感兴趣而是对那个时期的偕日感兴趣.
 
一些其它的、可在文件 swephexp.h 中找到 SE_HELFLAG_ 位, 仅仅用于测试的目的，可能会在未来的版本中改变. 请不要使用它们，不请求任何与它们相关的支持或信息.      


返回数组 dret[] (双精度数组) 细节:
        dret[0]: 开始能见度 (儒略日数)
        dret[1]: 最佳能见度(儒略日数), 0 如果 helflag >= SE_HELFLAG_AV
        dret[2]: 结束能见度(儒略日数), 0 如果 helflag >= SE_HELFLAG_AV

奇怪的现象:

- 金星的偕日升可以发生在它的偕日落前. 在这种情况下，行星可能会被视为一个早晨的恒星和一个晚上的恒星两天. 例如:
swetest -hev1 -p3 -b1.1.2008 -geopos8,47,900 -at1000,10,20,0.15 -obs21,1 -n1 -lmt
金星偕日升 : 2009/03/23   05:30:12.4 LMT (2454913.729310), visible for:  4.9 min
swetest -hev2 -p3 -b1.1.2008 -geopos8,47,900 -at1000,10,20,0.15 -obs21,1 -n1 -lmt
金星偕日落: 2009/03/25   18:37:41.6 LMT (2454916.276175), visible for: 15.1 min

- 具有良好的能见度和良好的视力(高视力比), 月亮的 “evening first” 实际上可能在早上开始, 因为月亮在日落之前是可见的. 注意以下示例中的 LMT 和可视持续时间:
swetest -hev3 -p1 -b1.4.2008 -geopos8,47,900 -at1000,10,40,0.15 -obs21,1.5 -n1 -lmt
Moon evening first   : 2008/04/06   10:33:44.3 LMT (2454562.940096), visible for: 530.6 min

- 在极地、但接近地平线的恒星, 可以有一个 evening last 和一个 morning first, 但 swe_heliacal_ut() 将找不到它. 它仅工作于恒星穿过地平线时.

- 在高地理纬度 > 55 (?),不寻常的事情可能会发生. 例如,  火星会有一个 morning last 出现. 在能见度持续时间不超过5天的情况下, 函数 swe_heliacal_ut() 可能会错过 morning first.

- 高地理纬度的水星和金星的偕出现变得稀少.

用户必须意识到，奇怪的现象发生，特别是高地理纬度和极地的对象和函数swe_heliacal_ut()可能并不总是能够正确处理好. 特殊情况下最好研究使用函数 swe_vi_limit_mag().

6.16. 能见度的星等限制: swe_vis_limit_mag()
函数 swe_vis_lim_mag() 确定在黑暗的天空中的极限视觉大小. 如果一个物体的视星等 mag 对于一个给定的日期是已知的, 例如从一个 swe_pheno_ut() 函数调用, 如果 mag 小于 swe_vis_limt_mag() 的返回值, 则它是可见的.

double swe_vis_limit_mag(
double tjdut,  /* 儒略日数 */
double *dgeo                /* 地理位置 (详情参见 swe_heliacal_ut() */
double *datm,  /* 大气条件 (详情参见swe_heliacal_ut()) */
double *dobs,  /* 观察描述 (详情参见swe_heliacal_ut()) */
char *objectname,        /* 恒星或行星的名字串*/
int32 helflag,  /* 计算标志, bitmap (详情参见swe_heliacal_ut()) */
double *dret, /* 结果: 对象可视的星等要求 */
char * serr /* 错误串 */
); 

函数返回
         -1 发生错误
         -2  对象是在地平线以下
         0 OK, 白昼视觉
         &1 OK, 夜视觉
         &2 OK, 近距极限 白昼视觉/夜视觉

数组 dgeo[], datm[], dobs[] 和其它参数的详细情况在“6.15. 偕日升等: swe_heliacal_ut()”中给出.

返回数组 dret[] (双精度数组)的细节:
        dret[0]: 极限星等 (如果 dret[0] > 对象星等, 则对象是可见的)
        dret[1]: 对象高度
        dret[2]: 对象方位角
        dret[3]: 太阳高度
        dret[4]: 太阳方位角
        dret[5]: 月亮高度
        dret[6]: 月亮方位角
        dret[7]: 对象星等


6.17. 偕日细节: swe_heliacal_pheno_ut()
函数 swe_heliacal_pheno_ut() 提供与偕日升和偕日落的计算相关的数据. 此函数不提供偕日升和偕日落的数据, 只是一些额外的数据主要用于测试目的. 要计算偕日升和偕日落, 请使用函数 swe_heliacal_ut().

double swe_heliacal_pheno_ut(
        double tjd_ut,  /* 儒略日数 */
        double *dgeo        /* 地理位置 (细节参见swe_heliacal_ut() */
 double *datm,  /* 大气条件 (细节参见 swe_heliacal_ut()) */
 double *dobs,  /* 观察描述 (细节参见 swe_heliacal_ut()) */
 char *objectname,/* 恒星或行星的名字串*/
   int32 event_type,  /* 事件类型 (细节参见 swe_heliacal_ut()) */
 int32 helflag,  /* 计算标志, bitmap (细节参见 swe_heliacal_ut()) */
 double *darr, /* 返回数组 */
 char * serr /* 错误串 */
);

返回数组具有以下数据:

'0=AltO [度]            对象的地面点高度(unrefracted)
'1=AppAltO [度]         对象的视高度(refracted)
'2=GeoAltO [度]         对象的地理高度
'3=AziO [度]            对象的方位角
'4=AltS [度]            太阳的地面点的高度
'5=AziS [度]            太阳方位角
'6=TAVact [度]          actual 地面点的arcus visionis
'7=ARCVact [度]         actual (geocentric) arcus visionis
'8=DAZact [度]          actual difference between object's and sun's 方位角
'9=ARCLact [度]         actual 经度 difference between object and sun
'10=kact [-]             extinction coefficient
'11=minTAV [度]         smallest 地面点的arcus visionis
'12=TfistVR [JDN]        first time object is visible, according to VR
'13=TbVR [JDN]           optimum time the object is visible, according to VR
'14=TlastVR [JDN]        last time object is visible, according to VR
'15=TbYallop[JDN]        best time the object is visible, according to Yallop
'16=WMoon [度]          cresent width of moon
'17=qYal [-]             q-test value of Yallop
'18=qCrit [-]            q-test criterion of Yallop
'19=ParO [度]           parallax of object
'20 Magn [-]             对象星等
'21=RiseO [JDN]          对象的升/落时间
'22=RiseS [JDN]          太阳的升/落时间
'23=Lag [JDN]            rise/set time of object minus rise/set time of sun
'24=TvisVR [JDN]         visibility duration
'25=LMoon [度]          cresent length of moon
'26=CVAact [度]
'27=Illum [%] 'new
'28=CVAact [度] 'new
'29=MSk [-] 

7. 日期和时间转换函数
7.1 计算日期和: swe_julday(), swe_date_conversion(), /swe_revjul()
这些函数在转换日历日期到天文时间度量为儒略日时需要.
double swe_julday(int year, int month, int day, double hour, int gregflag);

int swe_date_conversion (
 int y , int m , int d , /* 年, 月, 日 */
      double hour,    /* 小时 (十进制, 带分数) */
      char c,     /* 日历 ‘g’[公历]|’j’[儒略] */
 double *tjd);   /* 返回值为儒略日 */

void swe_revjul (
 double tjd,   /* 儒略日数 */
 int gregflag,  /* 公历: 1, 儒略历: 0 */
 int *year,  /* 年的目标地址, etc. */
 int *month, int *day, double *hour);

swe_julday() 和 swe_date_conversion() 根据年, 月, 日, 时计算儒略日数. swe_date_conversion() 另外检查日期是否合法. 它返回 OK 或 ERR.
swe_revjul() 是 swe_julday() 的反向功能. 它从一个儒略日数计算年, 月, 日和时.

变量 gregflag 告诉函数输入日期是儒略历 ( gregflag = SE_JUL_CAL) 或 公历 ( gregflag = SE_GREG_CAL).
通常, 你将设置 gregflag = SE_GREG_CAL.
儒略日数与介绍儒略历的儒略?凯撒无关, 而是由尤利亚努斯发明的. 儒略日数是给定一个日期, 自公元前4713年的一月一日中午到该日期已经过去的总天数. 例如 1.1.1900对应于儒略日数 2415020.5.
午夜的儒略日数总带有一个分数0.5, 因为习惯上天文日是从中午开始的. 这是实用的, 因为这样的话, 晚上在望远镜上工作时就没有日期变化. 来源于此的事实是, 中午的星历会在午夜的星历前印刷, 这早在二十世纪就被介绍了.

7.2. UTC 和儒略日: swe_utc_time_zone(), swe_utc_to_jd(), swe_jdet_to_utc(), swe_jdut1_to_utc()
以下函数, 是在 Swiss Ephemeris 版本1.76中引入, 与7.1中描述的函数做类似的工作. 区别是输入和输出时间是协调世界时 (UTC). 为了转换墙钟(或手表)时和儒略日数, 这些函数更加正确. 差异低于1秒.
 
使用这些函数来转换
- 本地时间至 UTC 及 UTC 至本地时间,
- UTC 到儒略日数, 及
- 儒略日数 到 UTC.

在 Swiss Ephemeris 中过去的闰秒是硬编码的. 将来的闰秒可以在文件seleapsec.txt 中指定, 参见 ch. 7.3.

注意, 在闰秒的情况下, 输入或输出时间必须是 60.9999 秒. 输入或输出格式必须允许这一点.

/* 转换本地时间至 UTC 或 UTC 至本地时间
 *
 * 输入:
 *   iyear ... dsec     日期和时间
 *   d_timezone         时区偏移
 * 输出:
 *   iyear_out ... dsec_out
 *
 * 对于格林威治东时区, d_timezone 为正.
 * 对于格林威治西时区, d_timezone 为负.
 *
 * 对于转换从本地时间至 UTC, 使用 +d_timezone.
 * 对于转换从UTC 至本地时间, 使用 -d_timezone.
 */
void swe_ utc_time_zone(
        int32 iyear, int32 imonth, int32 iday,
        int32 ihour, int32 imin, double dsec,
        double d_timezone,
        int32 *iyear_out, int32 *imonth_out, int32 *iday_out,
        int32 *ihour_out, int32 *imin_out, double *dsec_out
        )

/* 输入: 日期和时间(墙钟时间), 日历标志.
 * 输出: 一个双精度数组 with 儒略日数 在 ET (TT) 和 UT (UT1)中
 *             一个错误消息 (发生错误)
 * 函数返回 OK 或 ERR.
 */
int32 swe_utc_to_jd (
 int32 iyear, int32 imonth, int32 iday,
 int32 ihour, int32 imin, double dsec,   /* 注意 : 秒是十进制 */
 gregflag,  /* 公历: 1, 儒略历: 0 */
 dret /* 返回数组, 两个双精度:
    * dret[0] = 儒略日 在 ET (TT)中
    * dret[1] = 儒略日 在 UT (UT1)中 */
 serr /* 错误串 */
)

/* 输入: 儒略日数 在 ET (TT), 日历标志
 * 输出: 年, 月, 日, 时, 分, 秒 在 UTC 中*/
void swe_jdet_to_utc (
 double tjd_et, /* 儒略日数 在 ET (TT) 中*/
 gregflag,  /* 公历: 1, 儒略历: 0 */
 int32 *iyear, int32 *imonth, int32 *iday,
 int32 *ihour, int32 *imin, double *dsec,   /* 注意 : 秒是十进制 */
)

/* 输入: 儒略日数 in UT (UT1), 日历标志
 * 输出: 年, 月, 日, 时, 分, 秒 in UTC */
void swe_jdut1_to_utc (
 double tjd_ut, /* 儒略日数 in ET (TT) */
 gregflag,  /* 公历: 1, 儒略历: 0 */
 int32 *iyear, int32 *imonth, int32 *iday,
 int32 *ihour, int32 *imin, double *dsec,   /* 注意 : 秒是十进制*/
)

我如何从墙上时钟的日期和时间开始得到正确的行星位置, 恒星时, 和宫头?

int32 iday, imonth, iyear, ihour, imin, retval;
int32 gregflag = SE_GREG_CAL;
double d_timezone = 5.5 ; /* 时区 =印度标准时间; 注意: 东为正 */
double dsec, tjd_et, tjd_ut;
double dret[2];
char serr[256];
…
/* 如果日期和时间是在与 UTC 不同的时区, 时区必须减去偏移量
 * 首先为了得到 UTC: */
swe_utc_time_zone(iyear, imonth, iday, ihour, imin, dsec, d_timezone,
                &iyear_utc, &imonth_utc, &iday_utc, &ihour_utc, &imin_utc, &dsec_utc)
/* 从 UTC 计算 UT (UT1) 和 ET (TT)的儒略日数*/
retval = swe_utc_to_jd (iyear_utc, imonth_utc, iday_utc, ihour_utc, imin_utc, dsec_utc, gregflag, dret, serr);
if (retval == ERR) {
   fprintf(stderr, serr);  /* 错误处理*/
}
tjd_et = dret[0];  /* 这是 ET (TT) */
tjd_ut = dret[1];  /* 这是 UT (UT1) */
/* 用 tjd_et 计算行星*/
swe_calc(tjd_et, …);
/* 用 tjd_ut 计算宫 */
swe_houses(tjd_ut, …)

如何从一个儒略日数得到日期和墙钟时间? 取决于你是否有 tjd_et (儒略日 ET (TT)) 或 tjd_ut (儒略日 UT (UT1)), 使用 swe_jdet_to_utc() 或 swe_jdut1_to_utc() 两个函数中的一个.
…
/* 首先我们从 TT (ET) 计算 UTC */
swe_jdet_to_utc(tjd_et, gregflag, &iyear_utc, &imonth_utc, &iday_utc, &ihour_utc, &imin_utc, &dsec_utc);
         /* 现在, 转换 UTC 至本地时间 (注意 d_timezone 前面的负号): */
swe_utc_time_zone(iyear_utc, imonth_utc, iday_utc, ihour_utc, imin_utc, dsec_utc,
-d_timezone, &iyear, &imonth, &iday, &ihour, &imin, &dsec)

7.3. 处理闰秒和文件seleapsec.txt
闰秒的插入是不能提前知道的. 我们将在 IERS 宣布插入闰秒时更新 Swiss Ephemeris. 然而, 如果用户不想等待我们的更新或不想下载一个新版本的 Swiss Ephemeris, 他可以在星历所在目录中创建一个文件 seleapsec.txt. 文件内容看来如下(带 # 号的行是注释):
  # 该文件包含需要由Swiss Ephemeris考虑到的闰秒的日期
# 对于每个新的闰秒, 按格式 yyyymmdd 添加它的日期,
  # 例如2008年12月31日为: "20081231".
  # 闰秒插入到该日期的后面.
20081231

1972年以前, swe_utc_to_jd() 按 UT1 来处理它的输入时间.
注意: UTC 是在1961 开始使用的. 从 1961 - 1971, UTC 秒的长度是定期改变的, 所以，UTC 仍然非常接近 UT1.

从 1972 开始, 输入的时间按 UTC 处理.

如果 delta_t - nleap - 32.184 > 1, 输入时间按 UT1 处理.
注意: 这样我们避免错误大于1 秒 以防闰秒表 (或 Swiss Ephemeris 版本) 长时间没有更新.

7.4. 平太阳时 对 真太阳时: swe_time_equ(), swe_lmt_to_lat(), swe_lat_to_lmt()
世界时 (UT 或 UTC) 是基于平太阳时, 又叫当地平时, 它是时间的统一标准. 一天的长度总是相同的, 独立于一年中的时间.
在过去的几个世纪使用的机械时钟之前, 时间的计算主要是基于太阳表盘, 使用的是真太阳时, 又叫当地视时.
当地平时 和 当地视时 之间的差值叫时差. 这种差异可以大到20分钟.
如果历史数据中指出当地视时, 在用它来计算世界时 (对于宫)和历书时 (对于行星)之前，必须首先用时差转换成当地平时.
转换可以用函数 swe_lat_to_lmt() 来进行. 它的反转函数是 swe_lmt_to_lat(). 如果需要, 时差自己, 即 e = LAT – LMT, 可以使用函数 swe_time_equ() 计算

/* 时差
 *
 * 函数返回当地平时和当地平时的差值到 days 中.
 * E = LAT - LMT
 * 输入变量 tjd 是 UT.
 */
int swe_time_equ(double tjd, double* e, char* serr);

对于当地视时 和 当地平时 间的转换, 建议使用以下函数:

/* 转换 当地平时 (LMT) 到 当地视时 (LAT) */
/* tjd_lmt 和 tjd_lat 是儒略日数
 * geolon 是地理经度,东经为正,
 * 西经为负 */
int32 swe_lmt_to_lat(double tjd_lmt, double geolon, double *tjd_lat, char *serr);

/* 转换 当地视时 (LAT) 到 当地平时 (LMT) */
         int32 swe_lat_to_lmt(double tjd_lat, double geolon, double *tjd_lmt, char *serr);