# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later
"""The service loop: Python's side of an execution session (SEP 47 section 5).
A session (:mod:`solprop.backends.session`) owns the run's numerical state and its
schedule. This loop advances it and services what it reports -- saved planes and their
output transactions, plane observers and progress, snapshot persistence, warnings and
the terminal record -- then acknowledges each batch. It holds no numerical state of its
own: it never rediscovers the next plane, rebuilds a statistic or replays the attempts
to reconstruct a controller.
Ordering follows SEP 47 section 5.3: a plane is committed with its method history and
its execution record in one transaction (``solprop._interrupts.committing``); a
snapshot is serviced after that commit; the plane observer and the reporter follow.
A service failure leaves the batch unacknowledged, so the field it names can still be
exported for the terminal checkpoint, and the primary failure is preserved.
"""
from __future__ import annotations
import dataclasses
import logging
import time
from collections.abc import Mapping
from dataclasses import dataclass
import numpy as np
from solprop._host import RunClock, usage
from solprop._interrupts import committing, poll
from solprop.backends.driver_session import DriverSession
from solprop.backends.events import (
EventBatch,
ExportTicket,
ObservationKind,
ObservationReady,
Outcome,
Progress,
ServiceKind,
ServiceRequired,
join_attempts,
)
from solprop.backends.export import ExportRecipe
from solprop.backends.protocol import BackendHistory
from solprop.backends.protocol import StepStats as BackendRows
from solprop.driver.plane_view import PlaneWatch
from solprop.driver.run import (
_announce,
_earlier_execution,
_FailedObservation,
_history_of,
_MarchKeeper,
_method_history,
_open_run,
_record_abandoned_step,
_record_execution,
_refuse_unread_collar,
_resume_position,
_retain,
_Status,
retention_at,
)
from solprop.driver.summary import resources
from solprop.exceptions import ResponseBudgetError, RunTerminated, StopRequested
from solprop.log import (
InterruptibleReporter,
ProgressReporter,
StopFlag,
SummarisingReporter,
)
from solprop.output.hdf5 import HDF5Output
from solprop.output.schema import (
CheckpointOutput,
FieldRetention,
Output,
PlaneStore,
RecipeRecord,
RunMetadata,
SavedPlane,
StepHistory,
StepStats,
TerminalCheckpoint,
_adopted,
)
from solprop.output.snapshots import SnapshotController
from solprop.output.tdse_archive import TDSEArchiveWriter
from solprop.stepper.multistep import Multistep
from solprop.translate.problem import PropagationProblem
from solprop.translate.run_request import RunRequest
from solprop.translate.tdse import TDSEBinding
__all__ = ["MONITOR_RECONSTRUCTED", "ServiceContext", "serve"]
logger = logging.getLogger("solprop.driver.run")
_CONSUMER = ExportRecipe(power=True, optics=False)
"""The field a saved plane, a plane observer and a checkpoint record all hold: output
amplitudes in the internal FFT convention (SEP 47 section 5.4). The plane store makes
the optics conversion on its way to disk."""
[docs]
@dataclass(frozen=True)
class ServiceContext:
"""What the service loop needs besides the session and the output.
Attributes
----------
problem : solprop.translate.problem.PropagationProblem
The translated problem.
request : solprop.translate.run_request.RunRequest
The run's policies.
metadata : solprop.output.schema.RunMetadata
The run's record.
reporter : solprop.log.ProgressReporter
Where progress goes.
retention : solprop.output.schema.FieldRetention
Which planes keep their field.
resume_history : bool or None
The public method-history retention choice.
snapshots : solprop.output.snapshots.SnapshotController or None
Snapshot requests, when enabled.
tdse_binding : solprop.translate.tdse.TDSEBinding or None
A live atomic runtime.
tdse_archive : solprop.output.tdse_archive.TDSEArchiveWriter or None
A live archive to suspend beside the optical writer.
recipe : solprop.output.schema.RecipeRecord or None
The recipe the run was built from.
start_plane : int
The first save plane beyond the starting state.
stop : solprop.log.StopFlag or None
The run's stop flag, polled between batches as well as inside the session.
restoration : collections.abc.Mapping or None, optional
What a resumed execution restored of the method history
(``Simulation._continue_march``), for its
execution record; ``None`` for a fresh run or a caller that says nothing.
"""
problem: PropagationProblem
request: RunRequest
metadata: RunMetadata
reporter: ProgressReporter
retention: FieldRetention
resume_history: bool | None
snapshots: SnapshotController | None
tdse_binding: TDSEBinding | None
tdse_archive: TDSEArchiveWriter | None
recipe: RecipeRecord | None
start_plane: int
stop: StopFlag | None = None
restoration: Mapping[str, object] | None = None
def _rows(rows: BackendRows) -> StepStats:
"""Return a session's periodic rows in the form an output handler stores.
Parameters
----------
rows : solprop.backends.protocol.StepStats
The rows, with a leading row axis and no batch axis.
Returns
-------
solprop.output.schema.StepStats
The same rows.
"""
return StepStats(z=rows.z, step=rows.step, values=dict(rows.values))
MONITOR_RECONSTRUCTED = {
"state": "reconstructed",
"reason": "persisted_records",
"restored": ["cumulative_totals", "quiet_state", "transverse_record"],
"restarted": ["check_cadence", "transverse_cap"],
}
"""How a resumed execution's boundary monitor was restored (SEP 47 section 5.5).
Today's reconstruction from the persisted records: the cumulative totals, the quiet
state and the transverse record are restored, and the check cadence and the transverse
cap restart from that restored state; persisting them is not claimed."""
def _restart(base: Mapping[str, object], keeper: _MarchKeeper) -> dict[str, object]:
"""Return an execution's restart record with the latest retention decision.
Parameters
----------
base : collections.abc.Mapping
What the execution restored, fixed when it started.
keeper : solprop.driver.run._MarchKeeper
The method-history keeper, holding the latest retention decision.
Returns
-------
dict
The record (:data:`solprop.driver.run.RESTART_RECORD`).
"""
retention = keeper.record()
return dict(base) if retention is None else {"retention": retention, **base}
class _Exports:
"""One detached export per pending ticket, shared by every consumer.
The output, a plane observer and a terminal checkpoint asking for the same field
share one array (SEP 47 section 5.4); a field-free plane fetches nothing unless a
consumer asks.
Parameters
----------
session : solprop.backends.driver_session.DriverSession
The session whose tickets are exported.
"""
def __init__(self, session: DriverSession) -> None:
"""Start with nothing exported."""
self._session = session
self._ticket: ExportTicket | None = None
self._field: np.ndarray | None = None
self._phase: np.ndarray | None = None
def field(self, ticket: ExportTicket) -> np.ndarray:
"""Return the consumer field for a ticket, exporting it once.
Parameters
----------
ticket : solprop.backends.events.ExportTicket
A pending ticket.
Returns
-------
numpy.ndarray
Read-only output amplitudes in the internal convention.
"""
if self._ticket != ticket or self._field is None:
field = self._session.export(ticket, _CONSUMER)
field.setflags(write=False)
phase = self._session.noise_phase(ticket)
if phase is not None:
phase.setflags(write=False)
self._ticket, self._field, self._phase = ticket, field, phase
return self._field
def release(self) -> None:
"""Drop the exported field once its batch is acknowledged."""
self._ticket = self._field = self._phase = None
def phase(self, ticket: ExportTicket) -> np.ndarray | None:
"""Return the noise phase for a ticket, exported with its field.
Parameters
----------
ticket : solprop.backends.events.ExportTicket
A pending ticket.
Returns
-------
numpy.ndarray or None
The phase, or ``None`` without a noise model.
"""
self.field(ticket)
return self._phase
_Chunk = tuple[BackendHistory | None, BackendRows | None]
"""One event's attempts and periodic rows, as it delivered them."""
class _Chunks:
"""The attempts and rows delivered since the last saved plane, in order.
A session delivers each attempt once, with the event after it
(:mod:`solprop.backends.events`); this is where they are assembled. An observation
takes them all as its plane's history and starts afresh; a running checkpoint
includes them without consuming them; a terminal checkpoint includes them.
"""
def __init__(self) -> None:
"""Start with nothing held."""
self._chunks: list[_Chunk] = []
def add(self, history: BackendHistory | None, rows: BackendRows | None) -> None:
"""Hold one event's chunk.
Parameters
----------
history : solprop.backends.protocol.BackendHistory or None
Its attempts.
rows : solprop.backends.protocol.StepStats or None
Its periodic rows, without a batch axis.
"""
self._chunks.append((history, rows))
def joined(self) -> tuple[BackendHistory, BackendRows]:
"""Return every chunk held, assembled, without consuming them.
Returns
-------
tuple
The attempts and rows since the last saved plane.
"""
return join_attempts(self._chunks)
def take(self) -> tuple[BackendHistory, BackendRows]:
"""Return every chunk held, assembled, and start afresh.
Returns
-------
tuple
The attempts and rows since the last saved plane.
"""
joined = self.joined()
self._chunks = []
return joined
def _plane(
event: ObservationReady,
exports: _Exports,
attempts: tuple[BackendHistory, BackendRows],
*,
keep: bool,
) -> SavedPlane:
"""Build the plane an output stores from an observation.
Parameters
----------
event : solprop.backends.events.ObservationReady
The observation.
exports : _Exports
Its field, when kept.
attempts : tuple
Its history and rows, assembled from the chunks since the previous plane.
keep : bool
Whether the plane keeps its field.
Returns
-------
solprop.output.schema.SavedPlane
The plane.
"""
field = exports.field(event.ticket) if keep else None
phase = exports.phase(event.ticket) if keep else None
return SavedPlane(
z=event.z,
field=None if field is None else _adopted(field),
stats=dict(event.stats),
step_history=_history_of(attempts[0]),
step_stats=_rows(attempts[1]),
noise_phase=None if phase is None else _adopted(phase),
)
[docs]
def serve( # noqa: PLR0912, PLR0915 - the commit sequence of SEP 47 section 5.3
session: DriverSession,
output: Output,
context: ServiceContext,
) -> None:
"""Advance a session to its end, servicing every event it reports.
Parameters
----------
session : solprop.backends.driver_session.DriverSession
The started session.
output : solprop.output.schema.Output
Where the planes go; closed when the loop ends, whether or not it succeeded.
context : ServiceContext
Everything else the service needs.
Raises
------
BaseException
The run's primary failure, a stop request or a signal, after its terminal
record and any checkpoint are written.
"""
problem, reporter = context.problem, context.reporter
backend = session.driver
planes = context.request.observation.save_planes
started = time.perf_counter()
clock = RunClock.start()
checkpoint_output = _open_run(
output, context.metadata, backend, context.tdse_binding
)
if context.recipe is not None and isinstance(output, PlaneStore):
with committing():
output.record_recipe(context.recipe)
reserve = getattr(output, "reserve", None)
if reserve is not None:
reserve(planes.size + 1)
_retain(output, context.retention, problem.shape)
reached, missing_current_save = _resume_position(output, checkpoint_output, problem)
_refuse_unread_collar(problem, backend)
monitor = session.monitor
# Read before this execution's first record replaces the earlier one's.
earlier = None if checkpoint_output is None else checkpoint_output.outcome
resumed, monitored, unwatched = _earlier_execution(output, checkpoint_output)
base: dict[str, object] = {}
if context.restoration is not None:
base["restoration"] = dict(context.restoration)
if resumed and monitor is not None:
# The record continues across the resume (SEP 21, ADR-057).
session.continue_monitor(
{
"record": monitored,
"plane": missing_current_save
or output.n_saved == 0
or float(output["z"][-1]) == reached,
"unwatched": unwatched,
}
)
base["monitor"] = dict(MONITOR_RECONSTRUCTED)
_announce(
problem,
context.metadata,
backend,
output,
reporter,
(context.start_plane, reached),
boundary_check=None if monitor is None else monitor.check,
)
keeper = _MarchKeeper(
output,
backend,
context.resume_history,
method=_method_history(problem),
retention=None if earlier is None else retention_at(earlier.execution, reached),
)
exports = _Exports(session)
current: list[ObservationReady | None] = [None]
def fetch() -> np.ndarray:
"""Return the pending observation's field, for the plane observer.
Returns
-------
numpy.ndarray
The field of the observation the observer is shown.
"""
event = current[0]
assert event is not None # the observer is shown a pending plane only
return exports.field(event.ticket)
watch = PlaneWatch(reporter, context.metadata, fetch, clock.observer)
pending: SavedPlane | None = None
pending_save_count = output.n_saved
pending_ticket: ExportTicket | None = None
snapshots = context.snapshots
snapshots_started = False
terminal_rows: tuple[object, object] = (None, None)
chunks = _Chunks()
failure: BaseException | None = None
adams = isinstance(context.request.integration.method, Multistep)
try:
if snapshots is not None:
snapshots._start()
snapshots_started = True
_record_execution(
checkpoint_output,
backend,
context.tdse_binding,
_Status("running", reached),
clock=clock,
restart=_restart(base, keeper),
)
batch: EventBatch | None = None
while True:
if batch is not None:
# Between batches, before the next propagation: a stop set during the
# service is honoured here, while the batch's field can still be
# exported for the checkpoint (SEP 41, S17).
poll(context.stop)
session.acknowledge(batch.receipt)
exports.release()
current[0] = None
batch = None
if session.finished:
break
if snapshots is not None and snapshots._due():
session.request_snapshot()
pending = None
pending_save_count = output.n_saved
pending_ticket = None
terminal_rows = (None, None)
batch = session.advance()
for event in batch.events:
if isinstance(event, Progress):
chunks.add(event.history, event.step_stats)
elif isinstance(event, ObservationReady):
chunks.add(event.history, event.step_stats)
attempts = chunks.take()
if event.kind is ObservationKind.LAUNCH and not (
output.n_saved == 0 or missing_current_save
):
# A resumed file already holds the plane at its position.
continue
current[0] = event
pending_ticket = event.ticket
# Its attempts, should the plane fail before it holds them.
terminal_rows = attempts
if event.kind is not ObservationKind.LAUNCH:
_warn_coarse(event, planes)
keep = context.retention.keeps(output.n_saved)
pending = _plane(event, exports, attempts, keep=keep)
pending_save_count = output.n_saved
with committing():
output.save(pending)
if event.kind is not ObservationKind.LAUNCH:
keeper.keep(pending.z)
reached = event.z
_record_execution(
checkpoint_output,
backend,
context.tdse_binding,
_Status("running", reached),
clock=clock,
restart=_restart(base, keeper),
)
watch.show(pending, output.n_saved - 1)
if event.kind is not ObservationKind.LAUNCH:
reporter.plane(event.z, event.summary)
elif isinstance(event, ServiceRequired):
chunks.add(event.history, event.step_stats)
# The one service a session asks for is the snapshot this loop
# requested, only with snapshots on.
assert event.kind is ServiceKind.SNAPSHOT and snapshots is not None
assert isinstance(output, HDF5Output)
_service_snapshot(
event,
output,
checkpoint_output,
backend,
keeper,
exports,
context,
chunks.joined(),
clock=clock,
adams=adams,
base=base,
)
else:
chunks.add(event.history, event.step_stats)
if event.outcome is Outcome.COMPLETED:
with committing():
_record_execution(
checkpoint_output,
backend,
context.tdse_binding,
_Status("complete", reached),
clock=clock,
restart=_restart(base, keeper),
)
else:
assert event.error is not None
pending_ticket = event.ticket
terminal_rows = chunks.joined()
raise event.error
reporter.finished(time.perf_counter() - started)
if isinstance(reporter, SummarisingReporter):
reporter.summary(resources(usage(clock)))
except BaseException as error:
failure = error
failed_z = _persist_failure(
session,
checkpoint_output,
context,
keeper,
exports,
pending_ticket,
terminal_rows,
chunks,
base,
_FailedObservation(
pending,
output.n_saved > pending_save_count,
error,
reached,
clock,
output.n_saved > 0 and context.retention.keeps(output.n_saved - 1),
),
)
if failed_z is not None:
reached = failed_z
if isinstance(error, RunTerminated | StopRequested):
logger.log(
logging.INFO if isinstance(error, StopRequested) else logging.WARNING,
"%s at z = %.6e m; %s",
error,
reached,
"the run's state there is written, and resume=True continues it"
if failed_z is not None
else "no state was written there",
)
if isinstance(reporter, InterruptibleReporter):
reporter.interrupted(reached, error)
raise
finally:
try:
output.close()
except BaseException as error:
if failure is None:
raise
failure.add_note(f"the optical output could not be closed: {error}")
finally:
if snapshots is not None and snapshots_started:
snapshots._finish()
def _warn_coarse(event: ObservationReady, planes: np.ndarray) -> None:
"""Log a plane whose propagation did not meet its tolerance.
Parameters
----------
event : solprop.backends.events.ObservationReady
The observation.
planes : numpy.ndarray
The requested save planes, m.
"""
summary = event.summary
if summary.met_tolerance:
return
index = min(event.plane_index, planes.size - 1)
logger.warning(
"a step was too coarse for the tolerance it is scaled by on the way to the "
"save plane at z = %.6e m (plane %d of %d): the largest scaled error norm was "
"%.3e against the requested 1.0",
float(planes[index]),
index + 1,
planes.size,
summary.max_norm,
)
def _service_snapshot( # noqa: PLR0913, PLR0917 - the snapshot transaction's context
event: ServiceRequired,
output: HDF5Output,
checkpoint_output: CheckpointOutput | None,
backend: object,
keeper: _MarchKeeper,
exports: _Exports,
context: ServiceContext,
attempts: tuple[BackendHistory, BackendRows],
*,
clock: RunClock,
adams: bool,
base: Mapping[str, object],
) -> None:
"""Persist a running checkpoint at an accepted endpoint and copy the snapshot.
At a saved plane the plane is the checkpoint, as before; elsewhere the endpoint's
field and the attempts and rows since the last plane are written as a running
checkpoint without being consumed (SEP 47 section 5.5).
Parameters
----------
event : solprop.backends.events.ServiceRequired
The snapshot request.
output : solprop.output.hdf5.HDF5Output
The live writer.
checkpoint_output : solprop.output.schema.CheckpointOutput or None
The writer as a checkpoint store.
backend : object
The driver, for the execution record.
keeper : _MarchKeeper
Keeps the method history beside the checkpoint.
exports : _Exports
The endpoint's field.
context : ServiceContext
The run's context.
attempts : tuple
The attempts and rows since the last plane, the snapshot's own chunk included:
the running checkpoint's, which does not consume them.
clock : solprop._host.RunClock
When the run started.
adams : bool
Whether the run's method keeps an Adams history, which a snapshot requires.
base : collections.abc.Mapping
What the execution restored, for its restart record.
"""
snapshots = context.snapshots
assert snapshots is not None
z = event.z
at_plane = output.n_saved > 0 and float(output["z"][-1]) == z
checkpoint = None
def persist() -> None:
"""Keep the method history and record the execution beside the snapshot."""
keeper.keep(z, required=adams)
_record_execution(
checkpoint_output,
backend, # pyright: ignore[reportArgumentType]
context.tdse_binding,
_Status("running", z),
clock=clock,
checkpoint=checkpoint,
restart=_restart(base, keeper),
)
# A snapshot at the plane just saved needs no running checkpoint beside it.
if not at_plane:
assert event.ticket is not None
history, rows = attempts
phase = exports.phase(event.ticket)
checkpoint = TerminalCheckpoint(
plane=SavedPlane(
z=z,
field=_adopted(exports.field(event.ticket)),
stats={},
step_history=_history_of(history),
step_stats=_rows(rows),
noise_phase=None if phase is None else _adopted(phase),
),
next_save_index=int(
np.searchsorted(context.request.observation.save_planes, z, "right")
),
landed=True,
)
snapshots._service(
output,
context.tdse_archive,
next_save_index=int(
np.searchsorted(context.request.observation.save_planes, z, "right")
),
require_history=adams,
persist=persist,
provenance=context.metadata,
z=z,
)
def _persist_failure( # noqa: PLR0913, PLR0917 - the failure's whole context
session: DriverSession,
output: CheckpointOutput | None,
context: ServiceContext,
keeper: _MarchKeeper,
exports: _Exports,
ticket: ExportTicket | None,
rows: tuple[object, object],
chunks: _Chunks,
base: Mapping[str, object],
failure: _FailedObservation,
) -> float | None:
"""Checkpoint the accepted state without replacing the original exception.
Parameters
----------
session : solprop.backends.driver_session.DriverSession
The session, its last batch still pending.
output : solprop.output.schema.CheckpointOutput or None
Handler supporting terminal checkpoints, when available.
context : ServiceContext
The run's context.
keeper : _MarchKeeper
Keeps the method history beside the checkpoint.
exports : _Exports
Shares a field already exported for the pending plane.
ticket : solprop.backends.events.ExportTicket or None
The committed field to checkpoint, or ``None`` when the state is poisoned or
the failure arose outside the session.
rows : tuple
The attempts and periodic rows since the last saved plane, assembled for the
terminal event or the failed plane, or ``None`` for each.
chunks : _Chunks
The chunks delivered since the last saved plane, for a failure outside the
session, whose own undelivered attempts are joined to them.
base : collections.abc.Mapping
What the execution restored, for its restart record.
failure : solprop.driver.run._FailedObservation
The primary failure and the plane in hand.
Returns
-------
float or None
The checkpointed position, m, when one was written.
"""
if output is None:
return None
backend = session.driver
in_flight = backend.in_flight
if failure.pending is None and in_flight is not None:
# The latest running checkpoint, when one follows the last plane, is the
# state to resume from (SEP 47 section 5.5).
return _record_abandoned_step(
backend,
output,
context.tdse_binding,
failure,
in_flight,
restart=_restart(base, keeper),
)
if ticket is None:
# The loop's own session is open, and a state left in flight is recorded
# above: the committed state always has a ticket.
ticket = _fallback_ticket(session)
assert ticket is not None
problem = context.problem
reached = None
try:
pending = failure.pending
field = _adopted(exports.field(ticket))
phase = exports.phase(ticket)
if pending is None or pending.z != ticket.z:
history, step_rows = rows
if history is None and step_rows is None:
# A failure outside the session: the chunks since the last plane, a
# running checkpoint's included, and what no event delivered.
chunks.add(*session.undelivered(ticket))
history, step_rows = chunks.joined()
pending = SavedPlane(
z=ticket.z,
field=field,
stats={},
step_history=StepHistory.empty()
if history is None
else _history_of(history), # pyright: ignore[reportArgumentType]
step_stats=StepStats.empty() if step_rows is None else _rows(step_rows), # pyright: ignore[reportArgumentType]
noise_phase=None if phase is None else _adopted(phase),
)
elif pending.field is None:
pending = dataclasses.replace(
pending,
field=field,
noise_phase=None if phase is None else _adopted(phase),
)
history = pending.step_history
ends = (history.z + history.h)[history.accepted]
landed = (
not context.request.observation.dense
or pending.z == problem.initial.z
or bool(np.any(np.isclose(ends, pending.z, rtol=1e-12, atol=0.0)))
)
if failure.already_saved:
pending = dataclasses.replace(
pending, step_history=StepHistory.empty(), step_stats=StepStats.empty()
)
reached = pending.z
checkpoint = TerminalCheckpoint(
plane=pending,
next_save_index=int(
np.searchsorted(
context.request.observation.save_planes, pending.z, side="right"
)
),
landed=landed,
)
with committing(deliver=False):
# The history first, so that the record states what was kept beside the
# checkpoint; a failure to keep it still leaves the checkpoint recorded.
try:
keeper.keep(reached)
except Exception as unkept:
failure.error.add_note(
f"the method history could not be kept beside the terminal "
f"checkpoint: {unkept}"
)
logger.exception("could not keep the method history")
_record_execution(
output,
backend,
context.tdse_binding,
_Status(
"budget_exhausted"
if isinstance(failure.error, ResponseBudgetError)
else "failed",
reached,
f"{type(failure.error).__name__}: {failure.error}",
),
clock=failure.clock,
checkpoint=checkpoint,
restart=_restart(base, keeper),
)
except Exception as checkpoint_error:
failure.error.add_note(
f"terminal checkpoint could not be persisted: {checkpoint_error}"
)
logger.exception("could not persist the terminal checkpoint")
return reached
def _fallback_ticket(session: DriverSession) -> ExportTicket | None:
"""Return a ticket for the committed state after a failure outside the session.
A service failure -- an output error, a signal during a commit -- leaves the
session's batch pending, so its state is still where the batch left it. When
nothing is pending, the session issues a failed terminal batch whose ticket exports
the committed state (``DriverSession.pending_ticket``).
Parameters
----------
session : solprop.backends.driver_session.DriverSession
The session.
Returns
-------
solprop.backends.events.ExportTicket or None
A ticket for the committed state, or ``None`` when the session is closed or
its state was left in flight.
"""
return session.pending_ticket()