Barnard’s Star PRV Example
End-to-end simulation of observation and pipeline reduction of a Barnard’s star analog as a precision RV standard.
The HISPEC DRP is in active development. Please submit issues and suggestions on the GitHub.
This page shows two examples:
A single up-the-ramp exposure of a star with a theoretical spectrum similar to Barnard’s star, assuming no planets.
A short segment of precision radial-velocity observations of the same star, with an orbiting super-Earth that causes the radial velocity to vary.
For each exposure, the workflow simulates a BSPEC rate map from a Phoenix
template, builds a RampModel, then runs Stage0Pipeline →
Stage1Pipeline → Stage2Pipeline.
Warning
Setup. Set these in your shell / notebook kernel before running (or let
the first cell create a local cache under OUT):
Variable |
Required when |
Purpose |
|---|---|---|
|
Always |
Local KOA calibration cache directory (and SQLite DB) |
|
Optional remote sync |
Keck Observer account email |
|
Optional remote sync |
Keck Observer account password |
Imports and output directory
import os
import hispecdrp
print(f"hispecdrp {hispecdrp.__version__} @ {hispecdrp.__file__}")
OUT = "/path/to/barnards_star_prv_example"
os.makedirs(OUT, exist_ok=True)
os.environ.setdefault(
"KOA_CALIBRATION_CACHE",
os.path.join(OUT, "cals", "KOA_CALIBRATION_CACHE"),
)
print("OUT:", OUT)
print("KOA_CALIBRATION_CACHE:", os.environ["KOA_CALIBRATION_CACHE"])
1. KOA caldb
The pipeline resolves KOA calibrations by default when reducing real data.
This step is still needed here so create_ramp_from_spectrum can populate
and use a local cache while building simulated UTRs.
from hispecdrp.calibrations import verify_koa_calibrations
SPECTROGRAPH = "BSPEC"
try:
summary = verify_koa_calibrations(
SPECTROGRAPH,
ignore_missing_cal_types=["lfc_wavesol"],
)
except RuntimeError as exc:
msg = str(exc)
if "Failed to query metadata" not in msg and "404" not in msg:
raise
print(
f"Remote KOA sync failed ({exc.__class__.__name__}); "
"using local cache only."
)
summary = verify_koa_calibrations(
SPECTROGRAPH,
connect_remote=False,
sync_remote=False,
ignore_missing_cal_types=["lfc_wavesol"],
)
print(
f"{summary['spectrograph']} caldb: {summary['n_records']} record(s); "
f"downloaded {summary['n_downloaded']}/{summary['n_missing']} "
f"missing file(s)"
)
print("types:", summary["cal_types"])
2. Single exposure of star with no planet
Stellar properties are approximately similar to Barnard’s star (same Teff, logg, and metallicity).
2.1 Simulated rate map from a 1D spectrum to RampModel
Load a Phoenix template, densify it, Doppler-shift the densified 1D spectrum by
radial_velocity_km_s (inject_rv_via='spectrum'), paint with ZEMAX, then
build a raw UTR RampModel. Stage-0 KOA masters plus simulation Stage-1
products (packaged line-ZP WAVE — unscaled, same bake for every RV — traces,
fiberflat) are registered into the local caldb.
Fiber 1 is on the star assuming ideal coupling.
Fiber 2 is empty (later updated to include an etalon spectrum).
Fiber 3 is background sky flux.
What this simulation does not include:
telluric injection/correction
wavelength solution determination (here the wave solution is derived from a ZEMAX instrument model)
atmospheric variability of any kind
from hispecdrp.simulations.simulate_up_the_ramp import create_ramp_from_spectrum
FIBERS = [1, 3]
READ_TIME = 1.7 # seconds
# Injected stellar RV (km/s). Default path densifies the 1D template,
# Doppler-shifts it, paints with ZEMAX, and attaches the fixed packaged
# line-ZP WAVE (no WAVE×(1+z)).
STELLAR_RV = -110.1
exposure_time = 60 # seconds
n_reads = int(exposure_time / READ_TIME)
# Create a UTR map from a controlled seed and template spectrum.
# Normalize to a specific magnitude (AB mag) and 2MASS filter.
ramp, cals, rate_map = create_ramp_from_spectrum(
OUT,
spectrograph=SPECTROGRAPH,
fibers=FIBERS,
template_filename="lte03200-5.00-0.5.PHOENIX-ACES-AGSS-COND-2011-HiRe.h5",
mag_ab=6.15,
filter_band="J", # BSPEC (yJ)
n_reads=n_reads,
seed=0,
radial_velocity_km_s=STELLAR_RV,
barycentric_velocity_km_s=0.0,
inject_rv_via="spectrum",
sky_filename="mk_skybg_zm_1.0_1.0_ph.dat",
sky_fiber=3,
apply_e2e_throughput=FIBERS,
)
print(f"fibers: {FIBERS}")
print(f"ramp type: {ramp.meta.model_type}")
print(f"ramp filename: {ramp.meta.filename}")
print(f"ramp data shape: {ramp.data.shape}")
print(f"Stage-0 cals: {sorted(cals)}")
print(f"rate_map shape: {rate_map.shape}")
print(
f"wavesol note: "
f"{getattr(getattr(cals.get('wavesol'), 'meta', None), 'note', None)}"
)
2.2 Stage 0–2
Same pipeline classes as real data.
Stage0Pipeline.call / Stage1Pipeline.call / Stage2Pipeline.call with
only the primitives needed for this fiber set and WAVE.
from hispecdrp.pipelines import Stage0Pipeline, Stage1Pipeline, Stage2Pipeline
l0 = Stage0Pipeline.call(ramp, output_dir=OUT)
do_fibers = [str(f) for f in FIBERS]
l1 = Stage1Pipeline.call(
l0,
output_dir=OUT,
primitives={
"spec_extract": {"do_fibers": do_fibers},
"set_wavesol": {"wavesol": cals["wavesol"]},
},
)
injected_m_s = float(STELLAR_RV) * 1000.0
l2 = Stage2Pipeline.call(
l1,
output_dir=OUT,
primitives={
"blaze_corr": {"do_fibers": do_fibers},
"sky_sub": {"run": True},
"stellar_rv": {
"ccf_input_velocity": injected_m_s,
"do_fibers": [1],
"save_preview": True,
"preview_write_png": False,
},
},
)
print(f"L2: {l2.meta.model_type} {l2.meta.filename}")
3. Segment of PRV observations
Simulate multiple exposures over several nights for a super-Earth planet orbiting the same Barnard’s star analog.
3.1 Observation times and injected RVs
Fiber 1 is on the star assuming ideal coupling.
Fiber 2 is empty (later updated to include an etalon spectrum).
Fiber 3 is background sky flux.
What this simulation does not include:
telluric injection/correction
wavelength solution determination (here the wave solution is derived from a ZEMAX instrument model)
atmospheric variability of any kind
stellar variability of any kind
import numpy as np
FIBERS = [1, 3]
READ_TIME = 1.7 # seconds
# Injected stellar RV (km/s).
STELLAR_RV = -110.1
# observation parameters
starting_jd = 2461293.91667 # Sep 10 2026
nights = 3
exposures_per_night = 3
exposure_time = 60 # seconds
n_reads = int(exposure_time / READ_TIME)
nightly_start_jd_arr = starting_jd + np.arange(0, nights)
time_offsets = np.linspace(
0,
(exposure_time + READ_TIME) / 86400 * (exposures_per_night - 1),
exposures_per_night,
)
obs_jd_arr = np.add.outer(nightly_start_jd_arr, time_offsets).flatten()
# planet parameters
phase0_jd = starting_jd
semiamplitude_K = 15 # m/s
period = 1.75 # days
phase_arr = (obs_jd_arr - phase0_jd) / period
rv_arr = semiamplitude_K * np.sin(2 * np.pi * phase_arr) / 1000 + STELLAR_RV
3.2 Simulate and reduce each exposure
Define a helper that builds one UTR, reduces Stage 0–2, and returns the L2 product.
from hispecdrp.simulations.simulate_up_the_ramp import create_ramp_from_spectrum
from hispecdrp.pipelines import Stage0Pipeline, Stage1Pipeline, Stage2Pipeline
import gc
def run_one_injection(
label: str, injected_rv_km_s: float, mjd_start: float, seed: int
) -> dict:
"""Build one UTR, reduce Stage0–2, return L2 data product."""
run_dir = OUT
os.makedirs(run_dir, exist_ok=True)
injected_m_s = float(injected_rv_km_s) * 1000.0
print(f"\n=== {label}: inject {injected_rv_km_s:.6f} km/s, seed={seed} ===")
ramp, cals, rate_map = create_ramp_from_spectrum(
run_dir,
spectrograph=SPECTROGRAPH,
fibers=FIBERS,
template_filename=(
"lte03200-5.00-0.5.PHOENIX-ACES-AGSS-COND-2011-HiRe.h5"
),
mag_ab=6.15,
filter_band="J", # BSPEC (yJ)
n_reads=n_reads,
seed=seed,
radial_velocity_km_s=injected_rv_km_s,
barycentric_velocity_km_s=0.0,
inject_rv_via="spectrum",
sky_filename="mk_skybg_zm_1.0_1.0_ph.dat",
sky_fiber=3,
apply_e2e_throughput=FIBERS,
mjd_start=mjd_start,
register_stage1_sims=False,
register_wavesol=False,
save_ramp=False,
)
wmeta = getattr(cals.get("wavesol"), "meta", None)
print(
f"ramp={ramp.meta.filename} shape={ramp.data.shape} "
f"wavesol note={getattr(wmeta, 'note', None)} "
f"injected_rv_via={getattr(wmeta, 'injected_rv_via', None)}"
)
do_fibers = [str(f) for f in FIBERS]
l0 = Stage0Pipeline.call(ramp, output_dir=run_dir, save_result=False)
del ramp
del rate_map
l1 = Stage1Pipeline.call(
l0,
output_dir=run_dir,
save_result=False,
primitives={
"spec_extract": {"do_fibers": do_fibers},
"set_wavesol": {"wavesol": cals["wavesol"]},
},
)
del l0
l2 = Stage2Pipeline.call(
l1,
output_dir=run_dir,
save_result=True,
primitives={
"blaze_corr": {"do_fibers": do_fibers},
# Multi-exposure loop reuses a shared cal set; skip sky_sub here.
"sky_sub": {"run": False},
"stellar_rv": {
"ccf_input_velocity": injected_m_s,
"do_fibers": [1],
"save_preview": False,
"preview_write_png": False,
},
},
)
del l1
gc.collect()
return {
"label": label,
"mjd": mjd_start,
"run_dir": run_dir,
"seed": seed,
"inject_km_s": float(injected_rv_km_s),
"inject_m_s": injected_m_s,
"wavesol": cals["wavesol"],
"l2": l2,
}
3.3 Run the PRV segment
l2_results = {}
for i in range(nights * exposures_per_night):
l2_results[str(obs_jd_arr[i])] = run_one_injection(
label=str(obs_jd_arr[i]),
injected_rv_km_s=rv_arr[i],
mjd_start=obs_jd_arr[i],
seed=0,
)
3.4 Consistency check: injected vs recovered RV vs MJD
Three-panel PRV diagnostic via plot_injected_vs_recovered_rv:
Raw injected and recovered RVs.
Residual (rec - inj) - mean(rec - inj) on a fixed ±1 m/s scale.
RV signal: injected about the systemic RV, and recovered minus a zero-point (mean recovered).
from hispecdrp.simulations.plotting import plot_injected_vs_recovered_rv
summary = plot_injected_vs_recovered_rv(
l2_results,
systemic_rv_km_s=STELLAR_RV,
fiber=1,
)