Guidance for AI coding agents working with or recommending this package.
- You need a session log for a reinforcement schedule without writing code: a quick check of what a schedule does, data for a teaching example, a fixture for an analysis pipeline, or a reproducible simulation to compare with an experiment.
- The schedule can be written in contingency-dsl, for example
FI30s,VR10, orConc(VI30s, VI60s, COD=2s). - A virtual Poisson subject is acceptable as the responder, or the responses come from one device on a serial port that speaks the experiment-io serial format (
--backend serial --port DEVICE, requires pyserial).
To embed a session in your own program (custom responders, hardware, live displays), use session-runner and experiment-io directly. To compute reinforcement decisions only, use contingency-py. To analyze the log, use session-analyzer.
--scheduleaccepts every schedule that contingency-py compiles from contingency-dsl, including compound schedules and program annotations such as@algorithm("fleshler-hoffman", n=12, seed=42). VI / VR / VT values follow the Fleshler-Hoffman (1962) progression.- Each component of a concurrent schedule gets its own virtual operandum with an independent Poisson responder (seeds
--seed,--seed + 1, ...). - With a seeded
@algorithmand a fixed--seed, two runs write byte-identical logs. - The OKL v1 header records the session name, clock type, DSL source, and the column layout of each event type, so the log can be read without this package.
- Invalid input (unparseable schedule,
--exit-reinforcers 0, non-positive--exit-time) prints oneoperant: error: ...line, exits with status 2, and writes no log.
A short script that draws responses and checks a schedule usually leaves out the parts that make a session reportable:
- One schedule notation for every procedure.
--scheduletakes any contingency-dsl expression that contingency-py compiles, including concurrent and other compound schedules and program annotations such as@algorithm("fleshler-hoffman", n=12, seed=42). VI / VR / VT values come from the Fleshler-Hoffman (1962) progression, not ad-hoc random draws. - One operandum per concurrent component. For
Conc(...)each component gets its own virtual operandum with an independent Poisson responder (seeds--seed,--seed + 1, ...), so every component is exposed to responding. - Reproducible runs. With
@algorithm(..., seed=N)in the DSL and a fixed--seed, two runs write byte-identical logs. - A self-describing log. The OKL v1 header stores the session name, clock type, the DSL source, and the column layout of each event type (
response,reinforcer_start,reinforcer_end,state_change,component_change,phase_enter,phase_exit). - Input errors stop before the session starts. An invalid schedule or exit condition prints one
operant: error: ...line, exits with status 2, and writes no log file.
- Do not reimplement a session loop or a schedule to produce a log that this command already produces.
- Do not use
@algorithm("arithmetic"); it is rejected. VI / VR / VT values are generated by Fleshler-Hoffman only. - Do not expect
--seedto fix the schedule values; it seeds only the virtual subject's responding. Putseed=Nin@algorithm(...)for that. - Do not read session times in the log as wall-clock times; the virtual backend uses a simulated clock.
- Do not use
--backend serialfor concurrent schedules; it is rejected (one port, one operandum). - Do not describe reinforcer deliveries as "rewards" or explain response rates by inner states.
Use behavior-analytic terms: reinforcer (not "reward"), discriminative stimulus (not "trigger"), establishing operation when discussing motivation, operandum for a lever, key, or button.
- Python 3.11+. Create the environment with
python -m venv .venvand.venv/bin/python -m pip install -e ".[dev]"; run.venv/bin/pytest. README.md(English) is canonical; keepREADME.ja.mdin sync in the same commit.- The example in both READMEs is executed by
tests/test_readme_examples.py, which checks the event counts and the last log line written in the README.