### Install Latest Development Release from PyPI

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/installation.md

Install the latest development release (if available) by using the `--pre` flag with pip.

```default
pip install -U --pre pyswisseph
```

--------------------------------

### Install Pyswisseph from PyPI

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/installation.md

Use this command to install the latest stable version of Pyswisseph from the Python Package Index.

```default
pip install -U pyswisseph
```

--------------------------------

### Install Pyswisseph from Source

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/installation.md

Clone the Git repository and install Pyswisseph using pip. This method is for obtaining the latest unstable development version.

```default
git clone --recurse-submodules https://github.com/astrorigin/pyswisseph
cd pyswisseph
pip install .
```

--------------------------------

### Example: Jupiter Moon Io Body Number

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/planetary_positions/bodies/planetary_moons_and_body_centers.md

Example demonstrating the construction of the body number for Jupiter's moon Io.

```python
pl = swe.PLMOON_OFFSET + swe.JUPITER * 100 + 1 # 9000 + 5 * 100 + 1 = 9501
```

--------------------------------

### Basic Pyswisseph Setup and Calculation (UT)

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/steps_to_get_a_planets_position.md

Initializes the library, sets the ephemeris path, and demonstrates calculating positions for planets and fixed stars using Universal Time.

```python
# import the library
import swisseph as swe
# set the directory path of the ephemeris files
swe.set_ephe_path("/usr/local/share/sweph/ephe")
# from the birth date, compute the julian day number
jul_day_ut = swe.julday(year, month, day, hour, gregflag)
# compute a planet or other bodies
xx, retflags = swe.calc_ut(jul_day_ut, planet_no, flags)
# or a fixed star
xx, retnam, retflags = swe.fixstar_ut(star_nam, jul_day_ut, flags)
```

--------------------------------

### Venus Heliacal Setting Example

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/planetary_phenomena/heliacal_risings_and_settings.md

Demonstrates Venus' heliacal setting using the swetest command-line tool. Note the specific event type (-hev2) and date.

```console
swetest -hev2 -p3 -b1.1.2008 -geopos8,47,900 -at1000,10,20,0.15 -obs21,1 -n1 -lmt

Venus heliacal setting: 2009/03/25 18:37:41.6 LMT (2454916.276175), visible for: 15.1 min
```

--------------------------------

### Venus Heliacal Rising Example

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/planetary_phenomena/heliacal_risings_and_settings.md

Demonstrates Venus' heliacal rising using the swetest command-line tool. Note the specific event type (-hev1) and date.

```console
swetest -hev1 -p3 -b1.1.2008 -geopos8,47,900 -at1000,10,20,0.15 -obs21,1 -n1 -lmt

Venus heliacal rising : 2009/03/23 05:30:12.4 LMT (2454913.729310), visible for: 4.9 min
```

--------------------------------

### Run Pyswisseph Tests with Ephemeris Path

Source: https://github.com/astrorigin/pyswisseph/blob/master/README.rst

Executes the Pyswisseph test suite. Requires ephemeris files to be installed and the SE_EPHE_PATH environment variable to be set.

```bash
env SE_EPHE_PATH="/usr/share/sweph/ephe" python3 setup.py test
```

--------------------------------

### Complete Mini Chart Calculation

Source: https://context7.com/astrorigin/pyswisseph/llms.txt

A complete example computing all standard chart factors — Julian Day, planetary positions, house cusps, and Ascendant — for a birth data entry.

```APIDOC
## Complete mini chart calculation

### Description
A complete example computing all standard chart factors — Julian Day, planetary positions, house cusps, and Ascendant — for a birth data entry.

### Method
`swe.julday()`
`swe.calc_ut()`
`swe.houses()`
`swe.close()`

### Parameters
- `year`, `month`, `day` (int) - Birth date.
- `hour` (float) - Birth time in UT.
- `geolat` (float) - Geographical latitude.
- `geolon` (float) - Geographical longitude.
- `gregflag` (int) - Calendar flag (e.g., `swe.GREG_CAL`).
- `flags` (int) - Calculation flags (e.g., `swe.FLG_SWIEPH | swe.FLG_SPEED`).

### Response
- `jd_ut` (float) - Julian Day in UT.
- `xx` (list) - Planetary position data.
- `retflags` (int) - Return flags from `calc_ut`.
- `cusps` (list) - House cusp longitudes.
- `ascmc` (list) - Ascendant and MC data.

### Example
```python
#!/usr/bin/env python3
import swisseph as swe

swe.set_ephe_path(None)

# Birth data
year, month, day = 1980, 7, 4
hour = 8.5          # 08:30 UT
geolat = 40.7128    # New York City
geolon = -74.0060
gregflag = swe.GREG_CAL
flags = swe.FLG_SWIEPH | swe.FLG_SPEED

# Step 1: Julian Day
jd_ut = swe.julday(year, month, day, hour, gregflag)
print(f"Julian Day: {jd_ut:.4f}")

# Step 2: Planetary positions
planet_names = {
    swe.SUN: "Sun", swe.MOON: "Moon", swe.MERCURY: "Mercury",
    swe.VENUS: "Venus", swe.MARS: "Mars", swe.JUPITER: "Jupiter",
    swe.SATURN: "Saturn", swe.URANUS: "Uranus", swe.NEPTUNE: "Neptune",
    swe.PLUTO: "Pluto", swe.TRUE_NODE: "True Node", swe.CHIRON: "Chiron",
}

print("\nPlanetary Positions:")
for pid, pname in planet_names.items():
    try:
        xx, retflags = swe.calc_ut(jd_ut, pid, flags)
        sign = int(xx[0] / 30)
        deg_in_sign = xx[0] % 30
        sign_names = ["Ari","Tau","Gem","Can","Leo","Vir",
                      "Lib","Sco","Sag","Cap","Aqu","Pis"]
        retrograde = " R" if xx[3] < 0 else "  "
        print(f"  {pname:<12} {deg_in_sign:5.2f}° {sign_names[sign]}{retrograde}  (lon={xx[0]:.4f}°)")
    except swe.Error as e:
        print(f"  {pname:<12} Error: {e}")

# Step 3: House cusps (Placidus)
cusps, ascmc = swe.houses(jd_ut, geolat, geolon, b'P')
print(f"\nAscendant: {ascmc[swe.ASC]:.4f}°")
print(f"MC:        {ascmc[swe.MC]:.4f}°")
print("\nHouse Cusps:")
for i in range(1, 13):
    print(f"  House {i:2d}: {cusps[i]:>9.4f}°")

# Step 4: Clean up
swe.close()
```
```

--------------------------------

### Get correct planetary positions from date and time

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/date_and_time/utc_and_julian_day.md

Demonstrates how to convert a local date and time to UTC, then to Julian Day numbers (UT and ET), which can then be used for astronomical calculations.

```APIDOC
## Get correct planetary positions from date and time

This snippet shows how to convert a local date and time to UTC, and then to Julian Day numbers for use in astronomical calculations.

### Usage

1. **Convert local time to UTC**: Use `swe.utc_time_zone()` by providing year, month, day, hour, minute, second, and the timezone offset.
2. **Convert UTC to Julian Day numbers**: Use `swe.utc_to_jd()` with the UTC time obtained in the previous step to get Julian Day numbers for both UT (Universal Time) and ET (Ephemeris Time).
3. **Calculate astronomical positions**: Use the obtained Julian Day numbers (e.g., `jdut` for UT) with functions like `swe.calc()` or `swe.houses()`.

### Example

```python
import swisseph as swe

year = 2021
month = 8
day = 19
hour = 15
mins = 25
secs = 0
tzoffset = 5.5 # Indian Standard Time

# Convert local time to UTC
utc = swe.utc_time_zone(year, month, day, hour, mins, secs, tzoffset)

# Get Julian day number in UT and ET
jdet, jdut = swe.utc_to_jd(*utc)

# Now you can use jdut for calculations, e.g.:
# swe.calc(jdut, ...)
# swe.houses(...)
```

### Note on Timezones

If the provided date and time are not in UTC, the timezone offset must be subtracted first to obtain UTC.
```

--------------------------------

### Orbital Elements for 2015 RR245

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/planetary_positions/bodies/fictitious_planets.md

Example of orbital elements for the minor planet 2015 RR245, using J2000 equinox.

```text
2457600.5,J2000,322.50413,81.2891975,0.5852663,261.41753,211.67680,7.57643,2015 RR245 # 23
```

--------------------------------

### Moon Evening First Example

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/planetary_phenomena/heliacal_risings_and_settings.md

Demonstrates the Moon's 'evening first' phenomenon using the swetest command-line tool. Note the specific event type (-hev3) and date, and the extended visibility duration.

```console
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
```

--------------------------------

### Python House Cusp Calculation

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/house_cusp_calculation.md

This snippet demonstrates the start of a Python procedure for house cusp calculation. Further implementation details are expected.

```python
def calculate_house_cusps(birth_data):
    """Calculates house cusps based on birth data.

    Args:
        birth_data: A dictionary containing birth information (e.g., date, time, location).

    Returns:
        A dictionary of house cusp degrees.
    """
    # The procedure will be more complicated:
    pass

```

--------------------------------

### Mercury Orbital Elements with T terms

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/planetary_positions/bodies/fictitious_planets.md

Example of orbital elements for Mercury including T terms for various orbital parameters, using JDATE for equinox.

```text
J2000, JDATE, 174.794787 + 149472.5157715 * T, 0.38709831, 0.20563175 + 0.000020406 * T, 29.125226 + 0.3702885 * T, 48.330893 + 1.186189 * T, 7.004986 + 0.0018215 * T, Mercury elem. for equ. of date # 18
```

--------------------------------

### Build Pyswisseph Extension with CMake on Linux

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/installation.md

Build the Pyswisseph extension using CMake on Linux. This involves cloning the repository, creating a build directory, configuring with ccmake or cmake, and then building with make. The resulting 'swisseph.so' file should be placed in your sys.path.

```bash
git clone --recurse-submodules https://github.com/astrorigin/pyswisseph
cd pyswisseph
mkdir build
cd build
ccmake ..
# 'configure' and select your options, 'configure' again
# until you can 'generate' and exit
# with the regular cmake, it looks like this:
#cmake -D CMAKE_BUILD_TYPE=Release -D PYSWE_USE_SWEPHELP=0 ..
make
# put the resulting file 'swisseph.so' in your sys.path
```

--------------------------------

### Orbital Elements for Comet Halley

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/planetary_positions/bodies/fictitious_planets.md

Example of orbital elements for Comet Halley near 12 BCE, specifying B1950 equinox and other orbital parameters.

```text
1717323.34852, B1950, 0.0, 17.99261849, 0.9673664, 92.54399, 35.19064, 163.58392, Comet Halley 12 BCE # 22
```

--------------------------------

### Get Swiss Ephemeris Library Version

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/ephemeris_related_functions.md

Retrieves the version number of the Swiss Ephemeris library. The version is split into major, minor, and patch components.

```python
se_version_major, se_version_minor, se_version_patch = swe.version.split('.')
```

--------------------------------

### Create seleapsec.txt for Leap Seconds

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/date_and_time/handling_of_leap_seconds.md

Create a `seleapsec.txt` file in the ephemeris directory to manually specify leap second insertion dates. Each line should contain the date in `yyyymmdd` format.

```text
# This file contains the dates of leap seconds to be taken into account
# by the Swiss Ephemeris. 
# For each new leap second add the date of its insertion in the format
# yyyymmdd, e.g. "20081231" for 31 december 2008.
# The leap second is inserted at the end of the day.
20081231
```

--------------------------------

### Build Pyswisseph Extension with CMake on Windows

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/installation.md

Build the Pyswisseph extension using CMake on Windows with Visual Studio. After configuring and generating the solution, build it in Release mode. The resulting 'swisseph.pyd' file should be placed in your sys.path.

```bash
# Use CMake to create a “solution”:
# 1. Browse to the source code directory
# 2. Browse to an empty directory where you want to build
# 3. Click *Configure*, select your version of Visual Studio in the menu
# 4. Lines in red are newly found options, leave untouched in doubt
# 5. Click *Configure* again, lines become white, click *Generate*
# 6. With Visual Studio, open the “solution” located in your build directory
# 7. Select *Release* build type instead of *Debug*, click *Build Solution*
```

--------------------------------

### Set Ephemeris Path with Pyswisseph

Source: https://context7.com/astrorigin/pyswisseph/llms.txt

Initializes the Swiss Ephemeris by specifying the directory containing ephemeris data files. Use `None` to default to the Moshier ephemeris. This should be the first call in your application.

```python
import swisseph as swe

# Point to a local directory containing Swiss Ephemeris data files
swe.set_ephe_path("/usr/local/share/sweph/ephe")

# Alternatively, use the built-in Moshier ephemeris (no data files needed)
swe.set_ephe_path(None)

# Override any SE_EPHE_PATH environment variable
import os
os.putenv("SE_EPHE_PATH", "")
swe.set_ephe_path("/opt/sweph/ephe")
```

--------------------------------

### Simplified Precession Polynomial for J2000 Epoch

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/ephemerides/sidereal/on_which_ecliptic_is_the_ayanamsha_measured.md

A simplified version of the precession polynomial when the start date (Js) is J2000 (1 Jan. 2000, 12:00 TT).

```mathematics
P_N = 5029.0966 * t + 1.11161 *  t2 - 0.000113*t3
```

--------------------------------

### Pyswisseph Calculation with Ephemeris Time (ET)

Source: https://github.com/astrorigin/pyswisseph/blob/master/docs/programmers_manual/steps_to_get_a_planets_position.md

Shows how to convert Universal Time to Ephemeris Time and then compute celestial body positions. Includes closing the library resources.

```python
# if necessary, convert universal time (ut) to ephemeris time (et)
jul_day_et = jul_day_ut + swe.deltat(jul_day_ut)
# then compute a planet or other bodies
xx, retflags = swe.calc(jul_day_et, planet_no, flags)
# or a fixed star
xx, retnam, retflags = swe.fixstar(star_nam, jul_day_et, flags)
# at the end of your computations close all files and free memory
swe.close()
```