API Reference

RunPaths

Holds paths for a TEMPO run.

Fields

• work_dir::String : Absolute working directory for the run
• par_input::String : Input .par file name or relative path (resolved against work_dir; absolute paths are rejected)
• par_output::String : Output .par file name (filename only; no directories)
• tim_input::String : .tim file name or relative path (resolved against work_dir; absolute paths are rejected)

Notes

• A keyword constructor RunPaths(; work_dir, par_input, tim_input, par_output=default_par_output(par_input)) is available.

default_par_output(par_input::AbstractString) -> String

Generate a default output file name (no directories) by taking basename(par_input) and replacing its .par extension with *_out.par.

• Accepts either a bare filename or any path.
• Still enforces that the basename ends with .par (case‑insensitive).

EngineOptions

Defines low-level options for a TEMPO run.

Fields

• tempo_version::AbstractTempoVersion : Which TEMPO flavor to use
• flags::String : Additional command-line flags (normalized string)
• nits::Int : Number of internal iterations (must be ≥ 1)
• gain::Float64 : GAIN parameter controlling convergence damping (must be > 0)

Notes

• flags should be a single string; it is normalized (trimmed) and must not contain newlines.
• gain is validated to be strictly positive.

InputModifiers

Describes transformations applied to the inputs of a TEMPO run.

Fields

• override_params::Vector{TempoParameter} : parameters to upsert into the .par
• time_start::Union{Nothing,Float64} : optional lower MJD bound (inclusive)
• time_finish::Union{Nothing,Float64} : optional upper MJD bound (inclusive)
• couple_f1_to_ddot::Bool : if true, auto-adjust F1 when DDOT is overridden (applied during materialization)

Notes

• If both time_start and time_finish are provided, time_start ≤ time_finish is enforced.

CaptureOptions

Controls what is captured/emitted by the TEMPO engine itself (flags / process I/O).

Fields

• write_output::Bool : capture stdout/stderr from the engine
• write_residuals::Bool : for Tempo2 uses -write_residuals (per internal iteration); for Tempo uses -residuals (final only)

RetentionOptions

Controls what data we keep in the in-memory/result structures after a run.

Fields

• save_internal_iterations::Bool : retain all intermediate iteration results
• save_residuals::Bool : retain residuals arrays inside results (can be large)

WhiteNoiseOptions(; enabled=false, scope=:final)

Options for white-noise analysis:

• enabled — toggle analysis;
• scope — :final (last internal iteration) or :all (every internal iteration).

WorkspaceOptions

Workspace/runtime controls for a single TEMPO run. The options are grouped by intent:

Lifecycle & isolation

• work_mode::Symbol : :inplace | :jobdir
  • :inplace — run directly inside work_dir (job root = work_dir).
  • :jobdir — create/use a subdirectory of work_dir as an isolated job root.
• job_name::Union{Nothing,String} : subdirectory name when work_mode=:jobdir.
  • If nothing, an auto name like job-YYYYmmdd-HHMMSS-<rand> is generated.
• overwrite::Symbol : :error | :reuse | :unique | :clean
  • Behavior when the target job directory already exists (:unique appends -001, -002, ...).
  • :error — fail if exists; :reuse — use as-is; :clean — purge contents then use.
  • :overwrite is accepted for backward compatibility and treated as :clean (a warning is emitted).

Layout of files (inside the job root)

• layout::Symbol : :flat | :split
  • :flat — files live directly in the job root.
  • :split — create input/, output/, tmp/ under the job root.
• temp_dir::Union{Nothing,String}
  • If nothing, the execution cwd is the job root for :flat, or tmp/ for :split.
  • If non-nothing, use this subdirectory as the execution cwd (created if missing).

I/O mirroring

• io_mirror::Union{Symbol,Int,Tuple{Symbol,Int}} = :none
  • Controls how the temp_dir (or job root) directory structure is mirrored for I/O.
  • :none (flat), :full (mirror full temp_dir), Int (first N segments), (:depth_minus, k) (first depth-k segments).
  • Ignored when layout = :flat.

Inputs capture into job root

• link_tim::Bool : symlink the .tim file instead of copying (falls back to copy if symlink fails).
• snapshot_par::Bool : copy the input .par for reproducibility.

Cleanup & retention

• cleanup_before_run::Bool : remove engine artifacts in the run directory before launch.
• keep_tmp_on_success::Bool : keep tmp/ after a successful run (useful for debugging).
• keep_tmp_on_error::Bool : keep tmp/ if the run failed.

Runtime & manifest

• timeout_s::Union{Nothing,Int} : kill the run after this many seconds (nothing = unlimited).
• write_manifest::Bool : write a small manifest file in the job root.
• manifest_style::Symbol : :json | :toml.

LoggingOptions

Lightweight logging verbosity controls for the runner.

• verbosity — one of :silent | :warn | :info | :debug (also accepts 0..3 in the constructor)
• with_timestamps — include timestamps in log lines

TempoRunSettings

Top-level settings for a single TEMPO run. Composed from smaller structures:

• paths::RunPaths
• engine::EngineOptions
• modifiers::InputModifiers
• capture::CaptureOptions
• retention::RetentionOptions
• analysis::WhiteNoiseOptions
• workspace::WorkspaceOptions
• logging::LoggingOptions

copy_with(s::TempoRunSettings; kwargs...) -> TempoRunSettings

Create a modified copy of s with keyword overrides. You can override either whole sub-structs (analysis, workspace, logging) or individual convenience keys (e.g. white_noise_enabled, timeout_s, verbosity, ...).

Additional override-params controls:

• override_params_clear::Bool=false: start from an empty override list.
• override_params_delete: names (Symbol/String or a collection of them) to remove from overrides.
• override_params_upsert::Vector{TempoParameter}=TP[]: add/replace overrides by name.

If override_params is provided, delete/upsert are applied on top of it.

copy_with(e::PriorExecutionOptions; kwargs...) -> PriorExecutionOptions

Return a copy of e with any provided keyword overrides applied. Valid keys:

• mode, chain_direction, chain_snapshot_par
• scheduler, max_workers
• workdir_layout, node_dir_prefix, keep_node_dirs
• on_error
• dir_name_mode, index_pad, value_sig

copy_with(s::PriorMarginalizationSettings; kwargs...) -> PriorMarginalizationSettings

Create a modified copy of s, overriding any subset of fields via keyword arguments. All validations are performed by the regular constructor.

Keyword arguments mirror the settings fields:

• parameter, pin_mode, prior, nodes
• likelihood_source, ref_strategy, ref_value
• representative, save_node_results
• exec_options, metrics_hook, seed_spec

validate(v::AbstractTempoVersion) -> Bool

Check that data directory exists and the executable is available (or at least named). Returns true if OK, otherwise throws.

validate(s::TempoRunSettings) -> Bool

Alias for [validate_inputs_exist] — quick pre-materialization check that input .par/.tim exist relative to work_dir and that par_output is a bare file name. Does not create directories.

run_tempo_parsed(settings::TempoRunSettings) :: TempoRunOutput

Materialize the workspace, run TEMPO/TEMPO2 with relative paths, parse stdout into iteration records, and assemble RunArtifacts. No post-run deletion is performed here; call cleanup_run! from task-level code after reading the artifacts.

BasicTempoTask(settings::TempoRunSettings)

Single TEMPO/TEMPO2 task with parsed iterations, optional residual statistics, and optional white-noise analysis controlled by settings.analysis.

run_task(task::SingleTempoTask) -> GeneralTempoResult

Execute the task and return a unified result. Every concrete SingleTempoTask must provide a method.

run_task(task::MultiPointTask)

Entry point for multi-point workflows. Define as needed for your project.

run_task(task::BasicTempoTask) -> GeneralTempoResult

Run TEMPO/TEMPO2 using task.settings, parse iteration-wise outputs, attach residual/TIM-derived statistics, optionally perform white-noise fitting, and return an aggregated GeneralTempoResult.

run_task(task::PriorMarginalizedTempoTask) -> GeneralTempoResult

Execute the prior-marginalized task: build θ grid, run/supply node results, and assemble the aggregated GeneralTempoResult.

If settings.exec_options.on_error == :stop, the execution stops at the first failing node (detected by _check_nodes_for_error) and returns that node's GeneralTempoResult annotated by _bad_prior_result with :prior_mode => :stopped_on_error.

task_stage_inputs!(task::SingleTempoTask, dest_dir::AbstractString) -> Nothing

Stage/copy any task-specific input artifacts into dest_dir so that the task can run there using name-only paths. Default implementation does nothing.

Wrappers like prior-marginalization should call this before cloning a task with a new work_dir.

GridAxis(name; min, max, N, rule)
GridAxis(name, values::AbstractVector)

A typed grid axis with a chosen discretization rule. Call axisvalues to obtain physical coordinates and linspace to obtain the rule's linear parameterization.

Arguments

• name::Symbol : semantic axis name (e.g. :PBDOT, :beta0).
• min, max : axis bounds (ignored for ExplicitRule).
• N::Integer : number of grid points (must be ≥ 1).
• rule : one of LinRule(), LogRule([sign]), or ExplicitRule.
• values : alternative constructor; makes an ExplicitRule from a supplied vector of nodes.

Examples

ax1 = GridAxis(:x; min=-1.0, max=1.0, N=21, rule=LinRule())
ax2 = GridAxis(:m; min=-1e-4, max=-1e-2, N=16, rule=LogRule())  # auto-sign (−)
ax3 = GridAxis(:θ, [-1.0, -0.5, 0.0, 0.5, 1.0])                 # explicit nodes

GridAxis(name; min, max, N, rule)
GridAxis(name, values::AbstractVector)

A typed grid axis with a chosen discretization rule. Call axisvalues to obtain physical coordinates and linspace to obtain the rule's linear parameterization.

Arguments

• name::Symbol : semantic axis name (e.g. :PBDOT, :beta0).
• min, max : axis bounds (ignored for ExplicitRule).
• N::Integer : number of grid points (must be ≥ 1).
• rule : one of LinRule(), LogRule([sign]), or ExplicitRule.
• values : alternative constructor; makes an ExplicitRule from a supplied vector of nodes.

Examples

ax1 = GridAxis(:x; min=-1.0, max=1.0, N=21, rule=LinRule())
ax2 = GridAxis(:m; min=-1e-4, max=-1e-2, N=16, rule=LogRule())  # auto-sign (−)
ax3 = GridAxis(:θ, [-1.0, -0.5, 0.0, 0.5, 1.0])                 # explicit nodes

GridAxis(name; min, max, N, rule)
GridAxis(name, values::AbstractVector)

A typed grid axis with a chosen discretization rule. Call axisvalues to obtain physical coordinates and linspace to obtain the rule's linear parameterization.

Arguments

• name::Symbol : semantic axis name (e.g. :PBDOT, :beta0).
• min, max : axis bounds (ignored for ExplicitRule).
• N::Integer : number of grid points (must be ≥ 1).
• rule : one of LinRule(), LogRule([sign]), or ExplicitRule.
• values : alternative constructor; makes an ExplicitRule from a supplied vector of nodes.

Examples

ax1 = GridAxis(:x; min=-1.0, max=1.0, N=21, rule=LinRule())
ax2 = GridAxis(:m; min=-1e-4, max=-1e-2, N=16, rule=LogRule())  # auto-sign (−)
ax3 = GridAxis(:θ, [-1.0, -0.5, 0.0, 0.5, 1.0])                 # explicit nodes

GridAxis(name; min, max, N, rule)
GridAxis(name, values::AbstractVector)

A typed grid axis with a chosen discretization rule. Call axisvalues to obtain physical coordinates and linspace to obtain the rule's linear parameterization.

Arguments

• name::Symbol : semantic axis name (e.g. :PBDOT, :beta0).
• min, max : axis bounds (ignored for ExplicitRule).
• N::Integer : number of grid points (must be ≥ 1).
• rule : one of LinRule(), LogRule([sign]), or ExplicitRule.
• values : alternative constructor; makes an ExplicitRule from a supplied vector of nodes.

Examples

ax1 = GridAxis(:x; min=-1.0, max=1.0, N=21, rule=LinRule())
ax2 = GridAxis(:m; min=-1e-4, max=-1e-2, N=16, rule=LogRule())  # auto-sign (−)
ax3 = GridAxis(:θ, [-1.0, -0.5, 0.0, 0.5, 1.0])                 # explicit nodes

linspace(ax)

Return the linear parameterization for an axis:

• For LinAxis, this equals the physical coordinates.
• For LogAxis, this is uniform in log10(|x|).
• For ExplicitAxis, returns a copy of the stored values.

The result is a copy (safe to mutate by the caller).

axisvalues(ax)

Return the physical coordinates for an axis. For LogAxis, uses the rule sign (+1/−1) or infers it from ax.min when the rule is constructed with LogRule().

The result is a copy (safe to mutate by the caller).

RefinementSettings(units...; desired_refinement_level, parallel=false, params_to_save=())

Container for adaptive‑grid refinement configuration.

Arguments

• units... : one or more refinement units (order matters).
• desired_refinement_level : how many refinement rounds to perform (≥ 0).
• parallel : whether the grid engine may run points in parallel.
• params_to_save : tuple of metric names to extract at each point.

LocalMinimaUnit(name; min=-Inf, max=Inf, from_min=true)

Refine until a local minimum is detected along variable name within the interval [min, max].

Arguments

• name::Symbol : the variable/axis identifier.
• min, max : bounds of the search interval.
• from_min : if true, sweep from the lower bound (otherwise from upper).

FullUnit(name; min=-Inf, max=Inf)

Always refine over the whole range [min, max] of variable name.

DiffUnit(name; min=-Inf, max=Inf, diff, from_min=true)

Refine where the absolute change Δ(metric) exceeds diff within [min, max]. If from_min is true, scanning proceeds from the lower bound.

RelDiffUnit(name; min=-Inf, max=Inf, rel_diff, from_min=true)

Refine where the relative change exceeds rel_diff within [min, max].

ContourUnit(name; min=-Inf, max=Inf, contours, from_min=true)

Refine near specified contour levels (contours) of the target metric within [min, max]. contours can be a number, a tuple, or a vector of levels.

DiffContourUnit(name; min=-Inf, max=Inf, diffs, contours, from_min=true)

Refine near combinations of absolute difference thresholds (diffs) and contour levels (contours) within [min, max]. diffs/contours accept a number, tuple, or vector.

AdaptiveRefinement2DGrid

Structure representing a 2D adaptive refinement grid with variables, parameters, axes, refinement settings, and refinement status.

GridWorkspaceOptions

Workspace and tagging options for Adaptive2DGridTask.

Fields

• grid_root::String : Root folder for all grid artifacts. If relative, it's resolved against the base task work_dir.
• point_job_prefix::String : Subdirectory under grid_root to hold per-point job folders (used as part of job_name).
• results_dirname::String : Subdirectory under grid_root where per-point results (e.g., JLD2 files) are saved.
• input_dirname::String : Optional subdirectory name used when staging base inputs for the grid.

Tagging

• tag_mode::Symbol : :with_value to embed axis values into the tag, :hash to use a stable hash instead.
• tag_value_sig::Int : Significant digits when formatting values for :with_value tags.
• tag_sep::String : Separator between X and Y parts for :with_value tags.
• sanitize::Bool : Make tag filesystem-safe.
• hash_len::Int : Number of hex characters to keep when tag_mode == :hash.

Persistence & staging

• save_results_jld2::Bool : Save full GeneralTempoResult for each point into results_dirname.
• stage_inputs::Bool : Stage base task inputs into the grid root once before running.
• stage_inputs_mode::Symbol : Where to stage inputs: :root (into grid_root) or :subdir (into grid_root/input_dirname).

Adaptive2DGridTask(; base_task, x, y, ref_settings, opts=GridWorkspaceOptions())

Run a SingleTempoTask over an adaptively refined 2D grid defined by axes x and y.

Arguments

• base_task::SingleTempoTask : The task to clone and execute at each grid point.
• x::GridAxis, y::GridAxis : Grid axes (linear/log/explicit rules supported).
• ref_settings::RefinementSettings : Refinement engine configuration (units and parameters to save).
• opts::GridWorkspaceOptions : Workspace layout, tagging, and persistence options.

Behavior

• Each grid point is run in its own job directory (under opts.grid_root) with a unique job_name and par_output stem.
• The task is cloned via task_copy_with and parameter overrides TP(string(x.name), xv), TP(string(y.name), yv).
• Selected result scalars are returned to the grid engine as a NamedTuple keyed by ref_settings.params_to_save.