Python API¶

The CTCF table (site, captures_from, strength), with lefsim.n_sites in the schema metadata.

As plain Python data (dicts, lists, numbers and strings), in the same shape as the JSON.

Load from plain Python data shaped as to_dict returns it, with the same checks as construction.

As a JSON string; indent pretty-prints.

Load from a JSON string as to_json writes it, with the same checks as construction.

The LEF table: lef_id, left_pos, right_pos, left_mobility, right_mobility.

The effective distance between sites a and b: the shortest path when a path walks the lattice (step_length per step) and may cross LEFs (hop_length per crossing; across a chain of LEFs side by side, a rosette, a hop per LEF and the junctions between them free). Both lengths are integers, so distances are exact; divide by step_length for lattice steps.

Effective distances (see effective_distance). Without targets, every pair of sites, condensed as scipy.spatial.distance.pdist (squareform makes it a matrix). With targets, each of sites to each of targets, row-major. Returns an array.array("q"); numpy.asarray wraps it without copying.

As plain Python data (dicts, lists, numbers and strings), in the same shape as the JSON.

Load from plain Python data shaped as to_dict returns it, with the same checks as construction.

As a JSON string; indent pretty-prints.

Load from a JSON string as to_json writes it, with the same checks as construction.

As plain Python data (dicts, lists, numbers and strings), in the same shape as the JSON.

Load from plain Python data shaped as to_dict returns it, with the same checks as construction.

As a JSON string; indent pretty-prints.

Load from a JSON string as to_json writes it, with the same checks as construction.

As plain Python data (dicts, lists, numbers and strings), in the same shape as the JSON.

Load from plain Python data shaped as to_dict returns it, with the same checks as construction.

As the versioned JSON model document (lefsim.model, version 2); indent pretty-prints.

Load a JSON model document as to_json writes it, with the same checks as construction.

The current state as a Model: the world now, with this run's rates and spawn rule. Sim(sim.model(), seed=..., start_time=sim.time) continues from here with fresh randomness.

The model this run started from. With seed and start_time, it says where a recording came from: Sim(sim.initial_model(), seed=sim.seed, start_time=sim.start_time) replays the run from its start, event for event.

The current state as a World.

The current state as a one-snapshot Batch, without advancing.

Fire one event. Returns (time, action, id) — id is a leg_id for "Step" and "Evict", a lef_id for "Respawn" — or None if no events remain.

Fire every event at or before t_end, then set the clock to t_end. Releases the GIL while running; Ctrl-C interrupts.

Fire up to n events.

Run until t_end, recording grid snapshots (with dt, on the grid t0 + k * dt, inclusive of t_end) and/or event deltas (with events=True; add keyframes=True to open the event table with one Keyframe row per leg holding the full state). Consecutive calls on the same grid continue it seamlessly. Releases the GIL while running; Ctrl-C interrupts.

Fire up to n events, recording as in record_until; snapshots cover grid points up to the current time.

Run toward t_end, taking at most max_snapshots grid snapshots. stopped is "recorder_full" when the chunk filled first: call again for the next one. Consecutive chunks tile the grid exactly.

Run toward t_end, logging event deltas into a chunk of about max_rows rows. With keyframes (the default) the chunk opens with the full state, so it can be replayed on its own, and may exceed max_rows by the rows of a zero-delay chain in progress (chunks only end at settled times). stopped is "recorder_full" when the chunk filled first: call again for the next one. time is the time through which the chunk describes the run.

Hand this simulation to a lazy Arrow stream that runs it to t_end, one bounded chunk per batch, as the record_*_chunk methods would.

Pass exactly one of dt (grid snapshots, at most max_snapshots per batch) or events=True (deltas, about max_rows rows per batch). With events=True, keyframes=True, every batch opens with one Keyframe row per leg, so each batch can be replayed on its own; a batch may then exceed max_rows by the rows of a zero-delay chain in progress (typically two), since batches only end at settled times. The stream can be iterated for Batches, or passed to any Arrow PyCapsule consumer (e.g. pyarrow.RecordBatchReader.from_stream, polars.DataFrame, duckdb). It runs without the GIL, so it can be consumed from any thread.

The stream's schema metadata says where it came from, once for the whole stream: lefsim.model (the model the run started from, as JSON) and lefsim.run (JSON: seed as a string, start_time, record_start, the requested record_end or null, lefsim_version).

The Sim is moved into the stream and can't be used afterwards; copy it first (copy.copy(sim)) to keep going from here.

As a pyarrow.Table (requires pyarrow).

As a polars.DataFrame (requires polars).

As a pandas.DataFrame (requires pyarrow and pandas).

Write this stream to a Parquet file as it runs, one row group per batch, so the file indexes itself for random access (Replayer.from_parquet). Only for keyframed event streams (events=True, keyframes=True). The footer carries lefsim.model and lefsim.run, with record_end set to where the data actually ends (if writing stops early, e.g. on Ctrl-C, the file is still valid up to there), and lefsim.row_groups = "keyframed". compression is any codec pyarrow writes; the default, zstd, and snappy are also readable by the TS package's lefsim/parquet. Requires pyarrow. Consumes the stream.

Load a whole keyframed event log: any Arrow table, batch or stream (pyarrow, polars, a Stream, pq.ParquetFile(...).iter_batches()) or an iterable of them. Batch boundaries don't matter: the log is re-split at its keyframes. n_lefs defaults to the size of the first keyframe. end is the time through which the log describes the run (e.g. the t_end it was recorded to); it defaults to the last row, since event rows alone can't say how long the state after the last event lasted.

Open a Parquet file written by Stream.to_parquet for random access: only the footer is read up front, and each seek, advance_to or snapshots reads just the row groups it needs (one per keyframed chunk, found from the footer's time statistics). The lattice and the end come from the file's lefsim.model and lefsim.run; pass lattice for a file without them. A file not written that way (e.g. by duckdb COPY) is read whole, as from_arrow would. Requires pyarrow.

Append a chunk of event rows (whole keyframes only). end is the time through which the chunk describes the run (a Recording's time); it defaults to the chunk's last row.

Move forward to t (or back, by seeking), clamped to the data: it never fails. Returns the time reached.

Jump to t in either direction (clamped to end).

The state at time as a one-snapshot Batch, like Sim.state().

The state at time as a World.

Seek to t and return the state there as a World.

Snapshots on the grid t0 + k * dt from t_start through t_end (default: the end of the log): the same table Sim.record_until(dt=...) records. Without t_start, starts from the current time (or the first keyframe), so consecutive calls on the same grid continue it.

Drop data no longer needed to seek to t or later.

For each point of the grid snapshots(dt, ...) would take, the effective distance of every pair of sites (condensed, as World.effective_distances). Returns (times, distances): array.array("d") of grid times, and array.array("q") of distances, row-major, one row of k(k-1)/2 per time. A replayer opened with from_parquet reads row groups as it walks the grid.