炁

炁，讀音同「氣」，是一種形而上的能量。作為道家的重要思想，與「氣」不同，「炁」是人體最初的先天能源，而「氣」則是指通過後天的呼吸以及飲食所產生的能量。

陰陽五行生剋，五運六氣、農曆節氣、天干地支計算，中醫基礎理論數據結構。具體使用方法可以參考單元測試QiTest.swift。

陰陽

萬物負陰而抱陽，沖氣以為和。

• 《道德經》

一個enum表示陰陽：

public enum YinYang: CaseIterable, Equatable {
    case yin
    case yang
}

五運六氣

五運六氣，簡稱運氣，又稱運氣學說，為古人研究氣候變化與疾病關係的一門學問。方法為運用陰陽五行生剋制化理論，以干支系統進行演繹，總結人在宇宙中的生理、病理變化。運氣學說為一綜合學科，其範圍涵蓋古代天文學、氣象學、物候學、地理學，屬於醫學氣象學和時間醫學的範疇。
內容包括五運與六氣，運與氣又有主、客之分，推算時需互相參照，並綜合當年物候才能準確推估疾病的發病規律。

五運包括木運、火運、土運、金運、水運，表木、火、土、金、水五行之氣在天地陰陽中的運行變化。五運代表不同節令的氣候特徵，因此五運是探索一年五個季節變化的運行規律。

古人曾用十月曆，至今仍可見於彝族人所用彝曆，十個月分為五個季節，五運與五季的配對關係為春溫屬木，夏熱屬火，長夏溼屬土，秋涼屬金，冬寒屬水。五運又可細分為歲運、主運、客運。

歲運

歲運統管全年五運之氣，可反映全年的氣候特徵及發病規律。因歲運居天地之中，氣交之分，隨天氣地氣的運動而先行升降，故又稱中運。因其通紀一年，又稱大運。歲運統管全年五運之氣，可反映全年的氣候特徵及發病規律，太過表主歲的運氣旺盛而有餘，不及表主歲的運氣衰少而不足， 因此歲運的表達方式是元素（Element）+太過/不及（excess/deficiency）。

計算給定天干對應的歲運：

public static func fortuneOfYear(of stem: HeavenlyStem) -> YearlyFortune

示例：

Qi.fortuneOfYear(of stem: .gui) // 天干癸
// 結果為“火運不及”： YearlyFortune(element: .fire, adequacy: .deficiency)

主運

主運指五運之氣分別主管一年五時的運。按照古十月歷，全年分作五步，每一步運各主一時，各主七十三天零五刻。始於木運，而火運，而土運，而金運，終於水運，按五行相生次序運行。年年如此，固定不變。

計算主運：

public static func hostFortunesOfYear() -> [Element]

返回：

[.tree, .fire, .earth, .metal, .water]

客運

客運與主運相對而言，因其十年之內年年不同，如客之往來，故名客運。客運也是主時之運，即每年五步的任一步，同時有一個主運和一個客運共同主持。推算方法為以當年歲運為初運，依五行太少相生順序，分作五步，行於主運之上，逐年變遷，十年一週期。另需注意，應以一個五行太少相生關係為基本單位。

計算客運：

public static func guestFortunesOfYearStem(_ stem: HeavenlyStem) -> [GuestFortune]

主氣

主氣主治一年六個季節的正常氣候變化，故稱為主時之氣。因其恆居不變，年年如此。又稱地氣。將一年二十四節氣分屬於六氣六步之中，主氣一年分六步，一步主四個節氣，即六十天八十七刻半。

public static func hostQiOfYear() -> [Qi]

客氣

客氣即是在天的三陰三陽之氣，因其運動不息，猶如客之往來，故稱客氣。又稱天氣。

计算客气：

public static func guestQiOfYear(of branch: EarthlyBranch) -> [Qi]

三陰三陽

三陰三陽為運氣學說中劃分陰陽的獨特方法，按陰陽氣的多少將陰和陽各分為三。因為三陰三陽的順序有不同的說法，此處命名只表示陰陽消長程度以避免歧義：

public enum ThreePhase: Equatable {
    case weak           // 少陽，厥陰
    case mild           // 太陽，少陰
    case dominant       // 陽明，太陰
}

曆法

LunarCalendar以及StemBranchCalendar分別提供農曆以及干支歷的計算。

農曆

LunarCalendar()

計算指定日期的農曆日期（包含農曆年月日，時辰以及節氣）：

public func lunarDate(from date: Date) -> LunarDate

（嚴格來講，農曆是陰陽合曆，命名為LunarDate不是很準確，具體見最後備註）

干支歷

天干地支是十乾與十二支的合稱、簡通稱為十天干十二地支，由兩者經一定的組合方式搭配成六十對，為一週期，循環往復，稱為一甲子或花甲之年。

干支紀年，週期第一年為「甲子」（如黃巾起事口號為「歲在甲子，天下大吉」），第二年為「乙醜」，依此類推，60年一週期；週期完了重復使用，周而復始，循環下去。

StemBranchCalendar(calculateMonthBasedOn: MonthCalculation = .solarTerm, timeZone: TimeZone = .current)

因為日干支是以儒略曆1970年的日期作為參照，因此可以設置需要的時區，默認使用當前時區。

干支歷可提供計算月支的方法，默認以二十四節氣分月計算。

/// 計算月支方法
public enum MonthCalculation {

    /// 以農曆月配干支，但不計閏月，閏月的干支取上一月的干支。
    /// 紀法是把月建配上天干，六十月(即五年)循環一週。
    /// 由於年天干的週期是十年，年干與月干有二對一的對應關係。
    /// 例如年干為甲或己時，正月的干支必然是丙寅，二月是丁卯，其餘可以類推。
    case lunarMonth

    /// 根據二十四節氣分月。子月定為由大雪至小寒前一日，丑月定為由小寒至立春前一日等等。
    case solarTerm
}

計算指定日期的干支（包含年月日對應的干支）：

public func stemBranchDate(of date: Date) -> StemBranchDate

計算指定日期的干支：

public func stemBranchOfDay(of date: Date) -> StemBranch

備註

農曆節氣

中國傳統夏曆（農曆）是一種「陰陽合曆」，同時根據日、月運行制定，「陰」是以朔望月為基準確定，「陽」是以地球自冬至繞太陽公轉一圈為基準確定歲實，每回歸年約365.2422日，二十四節氣據此而劃分，是中國古代用來指導農事之曆法曆注。然而由於地球繞太陽運行的軌道為橢圓形。離太陽較近時，地球公轉速度較快，較遠時則較慢，對當時制訂此曆法的中原地區而言，某些節氣無法反映出真實的氣候狀況。故自清代開始，另定以春分點為0度，太陽在黃道上每運行15度訂為一個節氣或中氣，24節氣因而為24個特定的時刻，而非特定的24天。此種節氣制訂法稱為「定氣法」。

節氣數據只限於1901-2100年，數據來源於香港天文台日期對照表，在此日期以外的年份，只採用粗略節氣日期。

黃帝紀年

黃帝紀年以黃帝登基之年為元年，因歷史說法不一，故黃帝元年何時開始有一定爭議。

Calendar(identifier: .chinese)

用iOS的中國日歷，按照"YYYY"的日期格式，在2023年5月8日，顯示的年份是4660，也就是說，蘋果使用公元前2637年作為黃帝元年。如果需要顯示黃帝紀年，則需根據需要稍作調整。