with one click
perform
npx skills add https://github.com/dxbdxa/aoup_model --skill trae-active-transport-workflowCopy and paste this command into Claude Code to install the skill
perform
npx skills add https://github.com/dxbdxa/aoup_model --skill trae-active-transport-workflowCopy and paste this command into Claude Code to install the skill
| name | trae_active_transport_workflow |
| description | perform |
Version: v0.1
Project type: theory + simulation
Target: journal-grade large-scale parameter scan for delayed active transport in gated complex environments
Build a reproducible large-scale computation pipeline for a delayed active generalized Langevin model in gated geometries, with the scientific goal of testing the following central claim:
In complex gated environments, memory improves active transport only within a productive window where medium memory and control delay match the gate-crossing dynamics; the fastest transport regime is generally different from the most dissipation-efficient regime.
This document is the single control file for:
There exists an internal ridge in parameter space, rather than a boundary optimum, such that transport efficiency is maximized when
[ \Pi_m + \Pi_f \sim O(1), \qquad \Pi_p \gtrsim 1 ]
where (\Pi_m) is the memory-to-gate time ratio, (\Pi_f) is the feedback-delay-to-gate time ratio, and (\Pi_p) is the persistence-to-gate-length ratio.
The parameter set that minimizes mean first-passage time (MFPT) is generically different from the one that maximizes dissipation-normalized transport efficiency.
Outside the productive-memory window, transport degrades primarily because of prolonged wall trapping, revisit cycles, and stale steering, rather than a simple reduction in instantaneous speed.
A weak co-flow can enlarge the productive window, while strong flow can collapse it by over-biasing trajectories toward wall hugging or wrong-gate overshoot.
The same nondimensional control law should approximately organize results across several geometry families.
State variables per particle:
Dynamics:
Primary observables:
Use a reference geometry and baseline dynamics (no_memory, no_feedback, U=0) to define:
Recommended dimensionless groups:
[ \Pi_p = \frac{\ell_p}{\ell_g} = \frac{v_0 / D_r}{\ell_g} ]
[ \Pi_m = \frac{\tau_{\mathrm{mem}}}{\tau_g} ]
[ \Pi_f = \frac{\tau_f}{\tau_g} ]
[ \Pi_U = \frac{U}{v_0} ]
[ \Pi_W = \frac{w_{\mathrm{gate}}}{L} ]
[ \Pi_B = \frac{\delta_{\mathrm{wall}}}{L} ]
Optional secondary controls:
| Symbol | Meaning | Baseline choice | Notes |
|---|---|---|---|
L | system size | 1.0 | nondimensionalized geometry size |
v0 | self-propulsion speed | 1.0 | defines active advection scale |
Dr | rotational diffusion | 0.2–2.0 | set via target persistence ratio |
gamma0 | instantaneous drag | 1.0 | baseline drag scale |
gamma1 | memory drag strength | 0–10 | scan separately or encode into tau_mem |
tau_v | viscoelastic relaxation | 1e-2–1e2 | broad log scan |
tau_f | feedback delay | 1e-2–1e2 | broad log scan |
U | background flow speed | -1.5 to 1.5 | linear scan relative to v0 |
delta_wall | soft wall range | 0.005–0.05 | geometry dependent |
kf | alignment gain | 0–10 | used for ablation and sensitivity |
Tmax | max run time | 20–50 tau_g | adaptive by regime |
dt | time step | min(timescale)/100 initially | verify via convergence |
| Parameter | Symbol | Range | Grid style | Initial points | Refined points |
|---|---|---|---|---|---|
| Persistence ratio | Pi_p | 1e-1 to 1e2 | log | 16 | 30–40 local |
| Memory ratio | Pi_m | 1e-2 to 1e2 | log | 20 | 40–60 local |
| Feedback ratio | Pi_f | 1e-2 to 1e2 | log | 20 | 40–60 local |
| Flow ratio | Pi_U | -1.5 to 1.5 | linear | 13 | 25 local |
| Gate width ratio | Pi_W | 0.02 to 0.25 | linear/log hybrid | 6 | 10 |
| Wall range ratio | Pi_B | 0.005 to 0.05 | linear | 5 | 8 |
| Memory strength | chi_m | 0 to 1 | linear | 6 | 10 |
| Phase | Goal | Parameters varied | Samples per point | Method |
|---|---|---|---|---|
| A | numerical validation | dt, Tmax, seed count | 1e3–1e4 | deterministic convergence tests |
| B | baseline ablations | Pi_p, Pi_m, Pi_f, Pi_U on sparse set | 1e3 | compare full, no_memory, no_feedback, no_flow |
| C | coarse global scan | Pi_p, Pi_m, Pi_f, Pi_U | 5e2–2e3 | Sobol / Latin hypercube |
| D | adaptive refinement | around ridges, phase boundaries, ranking reversals | up to 1e4 | local densification + bootstrap stopping |
| E | rare-event supplement | low-success regions | effective 1e5–1e6 | weighted ensemble / splitting |
| F | geometry transfer | selected geometry families | 2e3–1e4 | ridge-following slices |
Compute (\ell_g) and (\tau_g) from the reference model:
Output:
reference_scales.jsonbaseline_transition_stats.parquetAcceptance:
Fit a reduced-state description:
Target outputs:
Acceptance:
Derive and verify low-order corrections to crossing rate and alignment phase lag.
Output:
Characterize stale-control regime through revisit rate, trap-time growth, and alignment decorrelation.
Output:
Recommended repository layout:
project_root/
├─ README.md
├─ pyproject.toml
├─ configs/
│ ├─ geometries/
│ │ ├─ maze_main.yaml
│ │ ├─ channel_single_bottleneck.yaml
│ │ ├─ pore_array.yaml
│ │ └─ random_labyrinth.yaml
│ ├─ scans/
│ │ ├─ phaseA_validation.yaml
│ │ ├─ phaseB_ablations.yaml
│ │ ├─ phaseC_global_sobol.yaml
│ │ ├─ phaseD_refinement.yaml
│ │ ├─ phaseE_rare_events.yaml
│ │ └─ phaseF_geometry_transfer.yaml
│ └─ figures/
│ ├─ fig1_productive_memory.yaml
│ ├─ fig2_speed_efficiency_separation.yaml
│ ├─ fig3_trapping_mechanism.yaml
│ └─ fig4_geometry_collapse.yaml
├─ docs/
│ ├─ theory_notes.md
│ ├─ derivations/
│ ├─ manuscript_notes/
│ └─ trae_active_transport_workflow.md
├─ src/
│ ├─ core/
│ │ ├─ geometry.py
│ │ ├─ navigation.py
│ │ ├─ dynamics.py
│ │ ├─ kernels.py
│ │ ├─ observables.py
│ │ └─ rng.py
│ ├─ scans/
│ │ ├─ generate_design.py
│ │ ├─ run_point.py
│ │ ├─ run_batch.py
│ │ ├─ adaptive_refine.py
│ │ └─ rare_event.py
│ ├─ analysis/
│ │ ├─ aggregate.py
│ │ ├─ bootstrap.py
│ │ ├─ ridge_detection.py
│ │ ├─ collapse.py
│ │ └─ diagnostics.py
│ ├─ figures/
│ │ ├─ fig1.py
│ │ ├─ fig2.py
│ │ ├─ fig3.py
│ │ └─ fig4.py
│ └─ cli/
│ ├─ scan_cli.py
│ ├─ analysis_cli.py
│ └─ figure_cli.py
├─ jobs/
│ ├─ local/
│ ├─ slurm/
│ └─ manifests/
├─ data/
│ ├─ raw/
│ ├─ interim/
│ ├─ processed/
│ └─ reference/
├─ outputs/
│ ├─ logs/
│ ├─ tables/
│ ├─ figures/
│ └─ reports/
└─ tests/
├─ test_geometry.py
├─ test_dynamics.py
├─ test_observables.py
├─ test_reproducibility.py
└─ test_figures.py
The atomic unit should be:
(geometry_id, model_variant, state_point_id, seed_chunk_id)
where:
geometry_id: one geometry filemodel_variant: full, no_memory, no_feedback, no_flow, optional no_delaystate_point_id: one nondimensional parameter tupleseed_chunk_id: one shard of trajectories, e.g. 200–1000 trajectoriesThis design allows:
| Layer | Unit | Typical size |
|---|---|---|
| Design | state point | 1 parameter tuple |
| Compute shard | seed chunk | 200–1000 trajectories |
| Batch | scheduler job | 20–200 shards |
| Merge | aggregation unit | all shards for one state point |
Use multiprocessing across state points and seed chunks. Best for:
Use array jobs over shards. Best for:
Suggested SLURM logic:
data/raw/{scan_id}/data/processed/{scan_id}/For each state point, continue submitting seed chunks until all selected stopping criteria are satisfied:
CI_width(Psucc) < 0.02relative_error(logMFPT) < 0.05relative_error(eta_sigma) < 0.10For points with
Psucc < 0.05, orswitch from brute-force to:
All outputs should be machine-readable and versioned. Prefer Parquet for tabular data and JSON for metadata.
File: data/raw/<scan_id>/trajlite/<state_point_id>/<seed_chunk_id>.parquet
Required fields:
scan_idgeometry_idmodel_variantstate_point_idseedtraj_idsuccess (bool)fpttermination_reasontrap_time_totaltrap_countwall_fractiondrag_dissipationpath_lengthrevisit_countmean_progress_along_navmean_speedmean_rel_speed_to_flowalignment_cos_meanalignment_cos_stdgate_cross_countlast_gate_indexOptional fields:
max_wall_depthlargest_stuck_episodeorbitality_scoreturning_numberFile: data/processed/<scan_id>/state_points.parquet
Required fields:
scan_idgeometry_idmodel_variantn_trajn_successPsucc_meanPsucc_ci_lowPsucc_ci_highMFPT_meanMFPT_medianFPT_q10FPT_q90trap_time_meantrap_count_meanwall_fraction_meanSigma_drag_meanJ_proxyeta_sigma_meaneta_sigma_ci_loweta_sigma_ci_highrevisit_meanalignment_meanalignment_lag_peakstatus_convergedstatus_rare_event_usedruntime_secondscode_versionFile: data/processed/<scan_id>/metadata.json
Include:
For a representative subset of points, verify all key observables are stable under
dtdt/2dt/4Acceptance:
For slow and trapping-prone points, verify sensitivity to Tmax.
Acceptance:
Repeat selected points with independent seed families.
Acceptance:
Validate signed-distance field, wall normals, and navigation gradients.
Acceptance:
full model must differ from at least one ablation on a preselected benchmark set.
Acceptance:
There exists an internal productive-memory ridge in the ((\Pi_m, \Pi_f)) plane.
full modelPi_p values (at least 3 slices)Pi_U valueseta_sigma_mean in ((Pi_m, Pi_f))Psucc_mean in ((Pi_m, Pi_f))Pi_p, Pi_Ueta_sigmaoutputs/figures/fig1_main.pdfoutputs/tables/fig1_ridge_points.parquetoutputs/reports/fig1_methods_note.mdThe MFPT optimum and efficiency optimum are generically separated.
full, no_memory, no_feedbackPi_U and/or Pi_m + Pi_f along ridge-crossing cutsMFPT_mean vs Pi_Ueta_sigma_mean vs Pi_UPi_U^fast and Pi_U^effoutputs/figures/fig2_main.pdfoutputs/tables/fig2_optima_summary.parquetoutputs/reports/fig2_reversal_test.mdFailure outside the productive window is driven by wall trapping and stale control rather than simple slowing.
outputs/figures/fig3_main.pdfoutputs/tables/fig3_episode_stats.parquetoutputs/reports/fig3_mechanism_note.mdThe productive-memory criterion is approximately geometry-robust when expressed in nondimensional form.
ell_g, tau_g, Pi_Well_g, tau_gPi_m + Pi_f, Pi_p, Pi_Uoutputs/figures/fig4_main.pdfoutputs/tables/fig4_collapse_metrics.parquetoutputs/reports/fig4_scaling_note.mdpython -m src.cli.scan_cli design --config configs/scans/phaseC_global_sobol.yaml
python -m src.cli.scan_cli run --manifest jobs/manifests/phaseC_subset.json --mode local
sbatch jobs/slurm/run_phaseC_array.slurm
python -m src.cli.analysis_cli aggregate --scan-id phaseC_global_sobol
python -m src.cli.analysis_cli convergence --scan-id phaseC_global_sobol
python -m src.cli.scan_cli refine --config configs/scans/phaseD_refinement.yaml
python -m src.cli.figure_cli build --figure fig1
python -m src.cli.figure_cli build --figure fig2
python -m src.cli.figure_cli build --figure fig3
python -m src.cli.figure_cli build --figure fig4
| Milestone | Description | Exit criteria |
|---|---|---|
| M0 | repository bootstrapped | tests run, config loader works, geometry cache works |
| M1 | reference scales established | ell_g, tau_g stable within 5% |
| M2 | baseline ablations complete | full vs ablations show robust differences |
| M3 | global scan complete | coarse map covers all primary controls |
| M4 | ridge and reversal identified | internal ridge and distinct optima verified |
| M5 | mechanism established | trap/revisit/alignment explanation validated |
| M6 | geometry transfer complete | at least partial nondimensional collapse achieved |
| M7 | figures frozen | Figures 1–4 reproducible from clean run |
Trae provides project-level Rules and reusable Skills in its IDE settings, which makes it suitable for using one Markdown file as a persistent execution controller for an AI-assisted coding workflow. citeturn862190search1turn862190search5turn862190search6turn862190search8
Use this file as the canonical planning document inside the project. Keep it under docs/trae_active_transport_workflow.md and update checkboxes and status notes in place.
Paste the following into project-level rules:
You are working on a theory + simulation project for delayed active transport in gated geometries.
Always preserve reproducibility, deterministic config handling, and explicit provenance.
Never hardcode scan parameters into figure scripts.
Any new observable must be added to both trajectory-level and state-point-level schemas.
Any new geometry must expose signed distance, wall normals, and navigation field caches.
Before modifying scan logic, update docs/trae_active_transport_workflow.md.
Before claiming a physics conclusion, check convergence, confidence intervals, and at least one ablation.
Prefer small pure functions, typed configs, and testable CLI entry points.
- [ ] M0 bootstrap repository and config system
- [ ] M1 compute reference scales (`ell_g`, `tau_g`)
- [ ] M2 implement observables and lightweight trajectory records
- [ ] M3 run validation suite (`dt`, `Tmax`, seeds)
- [ ] M4 run baseline ablations
- [ ] M5 generate coarse global design and launch phase C
- [ ] M6 aggregate and detect ridges / reversals
- [ ] M7 launch adaptive refinement and rare-event branch
- [ ] M8 build mechanism dataset with full trajectories
- [ ] M9 run geometry transfer scans
- [ ] M10 freeze Figures 1–4 and manuscript tables
Create the project structure described in docs/trae_active_transport_workflow.md.
Implement typed config loading, geometry caching, and a minimal CLI skeleton.
Do not implement physics yet; focus on file structure, IO contracts, and test scaffolding.
Implement the delayed active generalized Langevin stepping kernel with clear separation between geometry fields, stochastic dynamics, and observable accumulation.
Use testable pure functions where possible.
Expose a batch stepping interface suitable for future acceleration.
Implement manifest generation and shard-based execution for state-point scans.
Atomic work unit must be (geometry_id, model_variant, state_point_id, seed_chunk_id).
Outputs must conform exactly to the schema in docs/trae_active_transport_workflow.md.
Implement convergence checks and local refinement around ridges, steep gradients, and ranking reversals.
Generate a resubmission manifest for only under-converged or high-value regions.
Implement Figure X from docs/trae_active_transport_workflow.md.
Read only processed tables, never raw trajectories unless the figure explicitly requires them.
Make the script reproducible from config and save both the figure and intermediate tables.
1. Open `docs/trae_active_transport_workflow.md`.
2. Pick the current milestone and one concrete deliverable.
3. Ask Trae for the smallest implementation step that advances that deliverable.
4. Run tests or a local subset immediately after code generation.
5. Record any schema or logic changes back into this document.
6. Commit only after code, config, and docs are synchronized.
A task is done only if:
Implement repository skeleton, typed configs, geometry cache, and output schemas.
Run reference-scale extraction and produce reference_scales.json.
Implement state-point runner and lightweight per-trajectory logging.
Run the smallest benchmark set:
Pi_pPi_mPi_fPi_UThis first mini-scan should exist only to validate the pipeline, not to support claims.
Use this template in outputs/reports/<scan_id>_summary.md:
# Scan summary: <scan_id>
## Purpose
<what scientific question this scan addresses>
## Config
- geometry:
- model variants:
- parameter ranges:
- trajectory budget:
## Numerical status
- convergence passed / failed:
- known unstable regions:
- rare-event branch used:
## Main outcomes
- internal ridge found:
- ranking reversal found:
- strongest effect size:
- main caveat:
## Next action
<refinement, ablation, figure generation, or theory update>
This project should be developed as a control-law discovery pipeline, not as a generic parameter sweep. Every stage should push toward one of three outputs:
Any computation that does not sharpen at least one of these claims should be deprioritized.