simjecture 0.6.0__tar.gz → 0.6.1__tar.gz

simjecture-0.6.1/.gitattributes

@@ -0,0 +1,16 @@
+# Preserve autonomous run artifacts byte-for-byte, including model-authored
+# formatting. Generated figures likewise need not satisfy source whitespace
+# checks.
+demos/gray_scott_counterexample/record/** -text -whitespace
+demos/collisionless_gem_reconnection/record/** -text -whitespace
+demos/kepler_energy/record/** -text -whitespace
+demos/resistive_mhd_island_coalescence/minimal_record/** -text -whitespace
+demos/resistive_mhd_island_coalescence/sol_medium_record/** -text -whitespace
+demos/flash_warpx_kinetic_patch/record/** -text -whitespace
+docs/_static/demos/*.svg -whitespace
+
+*.npz binary
+*.png binary
+
+demos/resistive_mhd_island_coalescence/continuation_record/** -text -whitespace
+demos/flash_warpx_kinetic_patch/continuation_record/** -text -whitespace

simjecture-0.6.1/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,28 @@
+name: Bug report
+description: Something failed, behaved unexpectedly, or was difficult to use.
+body:
+  - type: markdown
+    attributes:
+      value: |
+        A small reproduction is very helpful. Remove API keys, credentials and private data from logs. For sensitive security reports, follow SECURITY.md instead.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What happened?
+      description: What did you expect, and what did you observe?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How can we reproduce it?
+      description: Commands, inputs or interface steps. Include a short log or screenshot if useful.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Version and environment
+      description: Package version or Git commit, OS, local/hosted workspace, agent and execution backend. Mention relevant solver or hardware details.
+    validations:
+      required: true

simjecture-0.6.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Contribution guide
+    url: https://github.com/tomzhu0225/simjecture/blob/main/CONTRIBUTING.md
+    about: Setup, checks, scientific records and attribution.

simjecture-0.6.1/.github/ISSUE_TEMPLATE/contribution.yml

@@ -0,0 +1,20 @@
+name: Tool, study or improvement
+description: Propose a scientific tool, diagnostic, study or project improvement.
+body:
+  - type: textarea
+    id: idea
+    attributes:
+      label: What would you like to contribute or improve?
+      description: Describe the question or user problem and the result you would like to see.
+    validations:
+      required: true
+  - type: textarea
+    id: starting_point
+    attributes:
+      label: Starting point
+      description: Existing code, a paper, a working example, a proposed hypothesis, or a specific documentation/UI change. For upstream software or data, include its license if known.
+  - type: textarea
+    id: validation
+    attributes:
+      label: How could we check it?
+      description: A numerical control, small reproducible case, or behavior to test. Mention hardware or access requirements and any help you need.

simjecture-0.6.1/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## What changed and why
+
+<!-- Describe the concrete problem and resulting behavior. Link a related issue if there is one. -->
+
+## Validation
+
+<!-- Commands/checks and their results. Separate passes from unavailable, skipped or still-running checks. For UI/docs styling, include a rendered screenshot. -->
+
+## Scientific scope or compatibility
+
+<!-- If applicable: changed assumptions, diagnostics, evidence eligibility, runtime requirements, upstream license/credit, or migration notes. Delete this section when it is not relevant. -->

{simjecture-0.6.0 → simjecture-0.6.1}/.github/workflows/ci.yml

@@ -23,6 +23,8 @@ jobs:
         run: uv sync --frozen --group docs
       - name: Build documentation without warnings
         run: uv run --group docs sphinx-build -W --keep-going -b html docs docs/_build/html
+      - name: Check generated documentation links
+        run: uv run python scripts/check_docs_links.py docs/_build/html
 
   deterministic-core:
     runs-on: ubuntu-latest
@@ -66,6 +68,8 @@ jobs:
         run: uv run ruff check .
       - name: Test
         run: uv run pytest --cov=conjecture_solver --cov-report=term-missing
+      - name: Build source distribution and wheel from it
+        run: uv build --out-dir /tmp/simjecture-python-distributions
       - name: Validate packaged workspace install
         run: |
           uv run python scripts/package_workspace.py --output dist
@@ -96,6 +100,13 @@ jobs:
         run: uv run simjecture schemas --output schemas --check
       - name: Verify recorded autonomous demos
         run: |
+          uv run python demos/kepler_energy/verify_record.py
+          uv run python demos/resistive_mhd_island_coalescence/verify_minimal_record.py
+          uv run python scripts/verify_research_audit.py demos/resistive_mhd_island_coalescence/sol_medium_record
+          uv run python scripts/verify_research_audit.py demos/flash_warpx_kinetic_patch/record
+          uv run python scripts/verify_research_audit.py demos/flash_warpx_kinetic_patch/continuation_record
+          uv run python scripts/verify_research_audit.py demos/resistive_mhd_island_coalescence/continuation_record
+          uv run python demos/resistive_mhd_island_coalescence/postrun_coordinate_check.py
           uv run python demos/gray_scott_counterexample/verify_record.py
           uv run python demos/collisionless_gem_reconnection/verify_record.py
           uv run python demos/agent_roles_validation/verify_record.py

simjecture-0.6.1/.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Publish documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - demos/**
+      - src/conjecture_solver/web/static/brand/**
+      - scripts/check_docs_links.py
+      - pyproject.toml
+      - uv.lock
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: documentation-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: actions/configure-pages@v6
+      - name: Install locked documentation environment
+        run: |
+          python -m pip install uv
+          uv sync --frozen --group docs
+      - name: Build and validate
+        run: |
+          uv run --group docs sphinx-build -W --keep-going -b html docs docs/_build/html
+          uv run python scripts/check_docs_links.py docs/_build/html
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/_build/html
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Publish validated documentation
+        id: deployment
+        uses: actions/deploy-pages@v5

{simjecture-0.6.0 → simjecture-0.6.1}/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 This project follows semantic versioning. Dates use ISO 8601.
 
+## Unreleased
+
+## 0.6.1 — 2026-10-08
+
+- Include cylinder-flow validation data in source distributions as well as
+  wheels. Check the sdist-to-wheel build in CI and leave bulky research archives
+  and demo figure bundles in the repository/docs distribution.
+
+- Preserve two neutral 30-minute plasma continuations and add field-led visual
+  walkthroughs with real evidence maps, FLASH evolution, kinetic patch geometry,
+  spatial pressure maps, hashed plotting bundles and PDF/SVG exports.
+- Fix report-finalization edge cases observed in those trials: preserve admitted
+  diagnostic jobs, resume the writer after asynchronous analysis, allocate unused
+  drafting time to review and allow one deadline-bound review transport retry.
+
+- Reserve finishing time in new minimal studies for a current scientific report,
+  independent report assessment and a bounded revision. Enforce numerical and
+  native-agent cutoffs, expose the phase in the GUI, and bind report assessment
+  to frozen bytes. An accepted unresolved report does not approve any claim.
+  Existing studies retain their original deadline policy.
+
+- Let the research director explicitly resume a waiting worker for independent
+  analysis or review preparation while simulations continue. Expose the waiting
+  state to the director and show wake-up requests in Evidence & review.
+
+- Isolate incomplete or invalid study records during automatic run discovery so
+  a compact audit cannot prevent the web interface from opening other campaigns.
+  Explicit study loads and resumes continue to enforce snapshot integrity.
+
+- Preserve a fresh one-hour minimal FLASH audit and an explicitly separate,
+  tested post-run correction for an agent-authored half-cell coordinate error.
+  Keep the classic record and all original scientific receipts unchanged.
+
+- Keep WSL's Linux-side NVIDIA utility path during CUDA installation so the
+  post-build readiness probe can find `nvidia-smi` after toolchain isolation.
+  Install CuPy inside the CUDA runtime, test an actual device kernel, and exclude
+  user-site Python packages from runtime launch/probing. Register the managed
+  dependency history as part of CUDA capability identity.
+
+- Add operator-tested FLASH-to-WarpX state-transfer helpers for a guided local
+  kinetic follow-up, with numerical tests for flux reconstruction, coordinate
+  rotation, pressure/current mapping, divergence and changed-input detection.
+- Make WarpX, EOS and opacity skill instructions distinguish minimal methods
+  review from classic instrument contracts. Document multi-tool evidence handoffs.
+
+- Rebuild the documentation around the autonomous research loop and evidence
+  system, with a responsive Furo theme, current-mode explanations, a repair-loop
+  tutorial and clearly labelled historical records.
+- Process ancestor claim reviews before repair reviews. Keep repair-support
+  requests pending while ancestor falsifications are missing, expose the blocking
+  claims and allow the worker to address them without repeated reviewer calls.
+
+- Add Cylinder flow / Warp-LBM, contributed by Zifei Meng under Apache-2.0,
+  with an installer, agent guide, recorded diagnostics, custom studies and a
+  separate inlet-distance research benchmark task. Preserve source and validation
+  provenance; expose contributor credit and launch/preparation actions in the GUI.
+- Bound resident RAM for namespace-confined GPU capability jobs while allowing
+  CUDA address reservations. Give GPU readiness checks a bounded 128 MiB
+  per-file allowance for first-run JIT compilation.
+
+- Render the account rail and compact chat input in the initial page, before
+  JavaScript or session requests finish. Hosted pages hide local Connections
+  and Machines controls from their first render. Keep the mobile model picker
+  and Send button on one row.
+
 ## 0.6.0 — 2026-10-06
 
 - Add optional `simjecture serve` for a hosted workspace with durable admission,

{simjecture-0.6.0 → simjecture-0.6.1}/CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: "If you use this software, please cite the exact software version and Git commit."
 title: "Simjecture"
 type: software
-version: 0.6.0
-date-released: 2026-10-06
+version: 0.6.1
+date-released: 2026-10-08
 abstract: >-
   An evidence-governed runtime for autonomous computational experimentation and
   falsification over hypothesis trees.

{simjecture-0.6.0 → simjecture-0.6.1}/CONTRIBUTING.md

@@ -13,6 +13,13 @@ existing test module. Keep it small enough to explain and review on its own.
 Discuss large changes or scientific-policy changes with the maintainer before
 investing in an implementation.
 
+For scientific tools, diagnostics and studies, the
+[contribution map](docs/development/contributing.md) links each kind of contribution
+to a concrete starting point. [Open a contribution proposal](https://github.com/tomzhu0225/simjecture/issues/new/choose)
+if you would like help choosing the scope. Domain review and clear documentation
+are as useful as code: a well-explained numerical limitation can improve the next
+research run.
+
 ## Report a problem
 
 Include the exact package version and Git commit, operating system, execution
@@ -44,6 +51,7 @@ additional dependencies only when they are needed for your contribution.
   then run `uv run simjecture schemas --output schemas --check` and relevant tests
 - **Documentation:** use `uv sync --frozen --group docs`, then
   `uv run --group docs sphinx-build -W --keep-going -b html docs docs/_build/html`.
+  Run `uv run python scripts/check_docs_links.py docs/_build/html` as well.
   Check changed examples and links; see [documentation development](docs/development/documentation.md)
 - **Browser UI:** add the `browser` dependency group with
   `uv sync --frozen --group browser`, install Chromium with

simjecture-0.6.1/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: simjecture
+Version: 0.6.1
+Summary: Evidence-governed autonomous experimentation and falsification for computational science
+Project-URL: Homepage, https://github.com/tomzhu0225/simjecture
+Project-URL: Documentation, https://drawingsword.com/simjecture/
+Project-URL: Repository, https://github.com/tomzhu0225/simjecture
+Project-URL: Issues, https://github.com/tomzhu0225/simjecture/issues
+Author: Bowen Zhu
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: autonomous science,computational physics,falsification,hypothesis testing,scientific agents,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: matplotlib<4,>=3.8
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: pandas<4,>=2.2
+Requires-Dist: pillow<13,>=10
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: scipy<2,>=1.12
+Provides-Extra: dsh
+Requires-Dist: mcp<3,>=2; extra == 'dsh'
+Provides-Extra: flash-demo
+Requires-Dist: h5py<4,>=3.10; extra == 'flash-demo'
+Provides-Extra: process
+Requires-Dist: psutil<8,>=6; extra == 'process'
+Provides-Extra: public
+Requires-Dist: fastapi<1,>=0.115; extra == 'public'
+Requires-Dist: h5py<4,>=3.10; extra == 'public'
+Requires-Dist: psutil<8,>=6; extra == 'public'
+Requires-Dist: smolagents[openai]<2,>=1.24; extra == 'public'
+Requires-Dist: uvicorn<1,>=0.30; extra == 'public'
+Provides-Extra: tui
+Requires-Dist: textual<9,>=2.0; extra == 'tui'
+Provides-Extra: workspace
+Requires-Dist: h5py<4,>=3.10; extra == 'workspace'
+Requires-Dist: psutil<8,>=6; extra == 'workspace'
+Requires-Dist: smolagents[openai]<2,>=1.24; extra == 'workspace'
+Description-Content-Type: text/markdown
+
+# Simjecture
+
+[![PyPI](https://img.shields.io/pypi/v/simjecture)](https://pypi.org/project/simjecture/)
+[![CI](https://github.com/tomzhu0225/simjecture/actions/workflows/ci.yml/badge.svg)](https://github.com/tomzhu0225/simjecture/actions/workflows/ci.yml)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21945748.svg)](https://doi.org/10.5281/zenodo.21945748)
+
+[Try online](https://simjecture.com) · [Documentation](https://drawingsword.com/simjecture/) ·
+[Research loop](https://drawingsword.com/simjecture/concepts/research-loop.html) · [Recorded studies](https://drawingsword.com/simjecture/demos/index.html) ·
+[Contributing](https://github.com/tomzhu0225/simjecture/blob/main/CONTRIBUTING.md)
+
+**Hypothesize. Simulate. Falsify.**
+
+Simjecture runs autonomous numerical investigations from a human-defined scientific
+question. An agent designs experiments, searches for counterexamples and tests
+revised hypotheses. The evidence system preserves what ran and a separate reviewer
+examines whether the results justify the conclusion.
+
+You set the question, physical scope and budget. The agent chooses how to work.
+You can inspect intermediate results, steer the investigation and continue it in a
+new phase. The result is a research record you can follow from hypothesis to code,
+measurements, counterexamples and review.
+
+## The research loop
+
+![Human direction, autonomous investigation, recorded experiments, independent review, and fresh tests of committed repairs](https://raw.githubusercontent.com/tomzhu0225/simjecture/main/docs/_static/architecture/research-loop.svg)
+
+A counterexample must survive the relevant numerical controls. Under the **repair**
+completion policy, the agent then proposes the smallest justified change to the
+hypothesis, commits its predictions before testing them, and collects fresh
+validation evidence. Missing evidence sends the work back through the loop.
+
+The **answer** policy can also finish with a reviewed falsification of the original
+claim. New browser studies default to answer; the CLI defaults to repair. Both use
+minimal mode by default: flexible agent strategy, recorded experiments and explicit
+scientific acceptance. A deadline can leave the question unresolved.
+
+Read [how the loop works](https://drawingsword.com/simjecture/concepts/research-loop.html) or
+[how evidence is checked](https://drawingsword.com/simjecture/concepts/evidence-and-claims.html).
+
+## Follow a real investigation
+
+[**Magnetic-island coalescence with FLASH**](https://drawingsword.com/simjecture/demos/island-coalescence.html)
+shows density, magnetic geometry and a current sheet evolving in a real MHD
+calculation. Follow five resistivity cases, two refinements and their evidence
+map to see what was measured and why the full-range question remains open.
+The classic campaign and subsequent diagnostic audits remain available.
+
+![Four fresh FLASH snapshots: density with magnetic field lines above, current density below](https://raw.githubusercontent.com/tomzhu0225/simjecture/main/docs/_static/demos/island-field-walkthrough.png)
+
+[**FLASH → WarpX kinetic follow-up**](https://drawingsword.com/simjecture/demos/flash-warpx-patch.html)
+follows an actual MHD current sheet into a kinetic particle simulation. The visual
+walkthrough locates the patch, opens its pressure-measurement region, and connects
+field maps and numerical controls to the unresolved scientific claim.
+
+![Actual FLASH source, pressure-measurement region and evolved WarpX field](https://raw.githubusercontent.com/tomzhu0225/simjecture/main/docs/_static/demos/coupled-field-handoff.png)
+
+Both plasma investigations include preserved continuation records, downloadable
+figures and explicit distinctions between a completed simulation, an approved
+method and an accepted scientific conclusion.
+
+The [orbital-accuracy walkthrough](https://drawingsword.com/simjecture/demos/kepler-energy.html) uses the current
+minimal workflow to investigate a concrete question: **does small energy error
+imply an accurate trajectory?** It connects the operator's brief, actual numerical
+experiments, hypothesis revisions and independent review. It found five counterexamples in the original case matrix, then supported a
+four-case repair using fresh simulations and independent review. The retained
+record can be verified without a model call.
+
+Earlier records remain available. In the
+[historical Gray–Scott study](https://drawingsword.com/simjecture/demos/gray-scott.html), the harness rejected an
+attempt to close a claim using evidence commissioned for a different claim. The
+agent registered the missing contract and ran fresh experiments before closing it.
+That record documents the classic workflow; it is not presented as a new-version run.
+
+## What the evidence system preserves
+
+| Question you should be able to ask | Recorded material |
+|---|---|
+| What was being tested? | Original hypothesis, operator requirements and committed repairs |
+| What actually ran? | Frozen source and inputs, command, runtime identity and execution receipt |
+| Where did this number come from? | Output files, hashes and the experiment cited by the claim |
+| What challenged the result? | Counterexamples, controls, failed attempts and review gaps |
+| Why did the investigation finish? | Independent review, completion policy and budget or stop reason |
+
+A repaired claim cannot reuse old exploratory results as fresh validation. Changed
+committed source, missing committed cases and altered recorded outputs are checked
+by the service. Numerical adequacy and scientific interpretation remain review
+judgments. See [the evidence guide](https://drawingsword.com/simjecture/concepts/evidence-and-claims.html).
+
+## Try it
+
+Open **[simjecture.com](https://simjecture.com)** for the hosted workspace with
+supplied inference and compute within usage limits. Signed-in visitors can upload
+files and retain projects. Guest conversations and artifacts are temporary.
+
+For your own Linux or WSL machine, install the latest stable release:
+
+```bash
+curl -fsSL https://github.com/tomzhu0225/simjecture/releases/latest/download/install.sh | bash
+```
+
+The installer verifies the release bundle and prepares Python and the browser
+workspace. Reopen it with `~/simjecture/start-workspace`. Research files live under
+`~/simjecture/artifacts/projects`. See [installation options](https://drawingsword.com/simjecture/getting-started/installation.html).
+
+1. Choose a compatible API model or an authenticated native agent in the workspace.
+2. Discuss your question and prepare a study brief with **Autonomous research**.
+3. Review its hypothesis, evidence requirements, completion policy and budget.
+4. Start the investigation and follow its experiments and **Evidence & review**.
+
+The [first-study tutorial](https://drawingsword.com/simjecture/getting-started/first-run.html) walks through the full
+counterexample-and-repair workflow. [Headless studies](https://drawingsword.com/simjecture/how-to/headless-studies.html)
+cover terminal launches and automation.
+
+## Bring your instruments and compute
+
+Ordinary Python studies work without an external solver. Optional capabilities
+include WarpX, operator-supplied FLASH, EOS/opacity tools, ITER diagnostics and
+[GPU cylinder flow](https://drawingsword.com/simjecture/how-to/cylinder-flow.html). The cylinder solver and its
+validation records were contributed by [Zifei Meng](https://github.com/ZifeiMengSPH).
+
+- [Commission a scientific instrument](https://drawingsword.com/simjecture/how-to/guided-commissioning.html) or
+  [add your own capability](https://drawingsword.com/simjecture/how-to/add-a-capability.html).
+- [Run experiments on local or SSH workers](https://drawingsword.com/simjecture/how-to/ssh-workers.html).
+- [Steer or continue an investigation](https://drawingsword.com/simjecture/how-to/continuation-steering.html).
+- [Compare agents on recorded diagnostic tasks](https://drawingsword.com/simjecture/how-to/llm-bench.html).
+- [Operate a hosted service](https://drawingsword.com/simjecture/how-to/public-trials.html).
+
+Native agents retain their existing tools and run with their host-account access.
+Numerical experiments use the selected execution backend, Bubblewrap by default.
+Read [security guidance](https://github.com/tomzhu0225/simjecture/blob/main/SECURITY.md) and
+[restricted-host setup](https://drawingsword.com/simjecture/how-to/restricted-containers.html) when deploying workers.
+
+## Contribute
+
+Help us test the research process on meaningful questions. Contributions can add
+scientific instruments, validated diagnostics, reproducible studies, numerical
+review, documentation or infrastructure. Start with [CONTRIBUTING.md](https://github.com/tomzhu0225/simjecture/blob/main/CONTRIBUTING.md)
+or [open an issue](https://github.com/tomzhu0225/simjecture/issues) to discuss a study
+or a substantial change.
+
+[Release notes](https://github.com/tomzhu0225/simjecture/blob/main/CHANGELOG.md) · [Release checks](https://drawingsword.com/simjecture/archive/index.html) ·
+[Research status](https://drawingsword.com/simjecture/research/status.html) · [Historical records](https://drawingsword.com/simjecture/archive/index.html)
+
+## Citation and license
+
+Use [CITATION.cff](https://github.com/tomzhu0225/simjecture/blob/main/CITATION.cff) and identify the exact version and Git commit used
+for a result. The [concept DOI](https://doi.org/10.5281/zenodo.21945748) identifies
+the release series.
+
+Copyright 2026 Bowen Zhu and contributors. Licensed under [Apache 2.0](https://github.com/tomzhu0225/simjecture/blob/main/LICENSE).
+See [third-party notices](https://github.com/tomzhu0225/simjecture/blob/main/THIRD_PARTY_NOTICES.md) for upstream attribution and
+redistribution requirements.

simjecture-0.6.1/README.md

@@ -0,0 +1,152 @@
+# Simjecture
+
+[![PyPI](https://img.shields.io/pypi/v/simjecture)](https://pypi.org/project/simjecture/)
+[![CI](https://github.com/tomzhu0225/simjecture/actions/workflows/ci.yml/badge.svg)](https://github.com/tomzhu0225/simjecture/actions/workflows/ci.yml)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21945748.svg)](https://doi.org/10.5281/zenodo.21945748)
+
+[Try online](https://simjecture.com) · [Documentation](https://drawingsword.com/simjecture/) ·
+[Research loop](https://drawingsword.com/simjecture/concepts/research-loop.html) · [Recorded studies](https://drawingsword.com/simjecture/demos/index.html) ·
+[Contributing](https://github.com/tomzhu0225/simjecture/blob/main/CONTRIBUTING.md)
+
+**Hypothesize. Simulate. Falsify.**
+
+Simjecture runs autonomous numerical investigations from a human-defined scientific
+question. An agent designs experiments, searches for counterexamples and tests
+revised hypotheses. The evidence system preserves what ran and a separate reviewer
+examines whether the results justify the conclusion.
+
+You set the question, physical scope and budget. The agent chooses how to work.
+You can inspect intermediate results, steer the investigation and continue it in a
+new phase. The result is a research record you can follow from hypothesis to code,
+measurements, counterexamples and review.
+
+## The research loop
+
+![Human direction, autonomous investigation, recorded experiments, independent review, and fresh tests of committed repairs](https://raw.githubusercontent.com/tomzhu0225/simjecture/main/docs/_static/architecture/research-loop.svg)
+
+A counterexample must survive the relevant numerical controls. Under the **repair**
+completion policy, the agent then proposes the smallest justified change to the
+hypothesis, commits its predictions before testing them, and collects fresh
+validation evidence. Missing evidence sends the work back through the loop.
+
+The **answer** policy can also finish with a reviewed falsification of the original
+claim. New browser studies default to answer; the CLI defaults to repair. Both use
+minimal mode by default: flexible agent strategy, recorded experiments and explicit
+scientific acceptance. A deadline can leave the question unresolved.
+
+Read [how the loop works](https://drawingsword.com/simjecture/concepts/research-loop.html) or
+[how evidence is checked](https://drawingsword.com/simjecture/concepts/evidence-and-claims.html).
+
+## Follow a real investigation
+
+[**Magnetic-island coalescence with FLASH**](https://drawingsword.com/simjecture/demos/island-coalescence.html)
+shows density, magnetic geometry and a current sheet evolving in a real MHD
+calculation. Follow five resistivity cases, two refinements and their evidence
+map to see what was measured and why the full-range question remains open.
+The classic campaign and subsequent diagnostic audits remain available.
+
+![Four fresh FLASH snapshots: density with magnetic field lines above, current density below](https://raw.githubusercontent.com/tomzhu0225/simjecture/main/docs/_static/demos/island-field-walkthrough.png)
+
+[**FLASH → WarpX kinetic follow-up**](https://drawingsword.com/simjecture/demos/flash-warpx-patch.html)
+follows an actual MHD current sheet into a kinetic particle simulation. The visual
+walkthrough locates the patch, opens its pressure-measurement region, and connects
+field maps and numerical controls to the unresolved scientific claim.
+
+![Actual FLASH source, pressure-measurement region and evolved WarpX field](https://raw.githubusercontent.com/tomzhu0225/simjecture/main/docs/_static/demos/coupled-field-handoff.png)
+
+Both plasma investigations include preserved continuation records, downloadable
+figures and explicit distinctions between a completed simulation, an approved
+method and an accepted scientific conclusion.
+
+The [orbital-accuracy walkthrough](https://drawingsword.com/simjecture/demos/kepler-energy.html) uses the current
+minimal workflow to investigate a concrete question: **does small energy error
+imply an accurate trajectory?** It connects the operator's brief, actual numerical
+experiments, hypothesis revisions and independent review. It found five counterexamples in the original case matrix, then supported a
+four-case repair using fresh simulations and independent review. The retained
+record can be verified without a model call.
+
+Earlier records remain available. In the
+[historical Gray–Scott study](https://drawingsword.com/simjecture/demos/gray-scott.html), the harness rejected an
+attempt to close a claim using evidence commissioned for a different claim. The
+agent registered the missing contract and ran fresh experiments before closing it.
+That record documents the classic workflow; it is not presented as a new-version run.
+
+## What the evidence system preserves
+
+| Question you should be able to ask | Recorded material |
+|---|---|
+| What was being tested? | Original hypothesis, operator requirements and committed repairs |
+| What actually ran? | Frozen source and inputs, command, runtime identity and execution receipt |
+| Where did this number come from? | Output files, hashes and the experiment cited by the claim |
+| What challenged the result? | Counterexamples, controls, failed attempts and review gaps |
+| Why did the investigation finish? | Independent review, completion policy and budget or stop reason |
+
+A repaired claim cannot reuse old exploratory results as fresh validation. Changed
+committed source, missing committed cases and altered recorded outputs are checked
+by the service. Numerical adequacy and scientific interpretation remain review
+judgments. See [the evidence guide](https://drawingsword.com/simjecture/concepts/evidence-and-claims.html).
+
+## Try it
+
+Open **[simjecture.com](https://simjecture.com)** for the hosted workspace with
+supplied inference and compute within usage limits. Signed-in visitors can upload
+files and retain projects. Guest conversations and artifacts are temporary.
+
+For your own Linux or WSL machine, install the latest stable release:
+
+```bash
+curl -fsSL https://github.com/tomzhu0225/simjecture/releases/latest/download/install.sh | bash
+```
+
+The installer verifies the release bundle and prepares Python and the browser
+workspace. Reopen it with `~/simjecture/start-workspace`. Research files live under
+`~/simjecture/artifacts/projects`. See [installation options](https://drawingsword.com/simjecture/getting-started/installation.html).
+
+1. Choose a compatible API model or an authenticated native agent in the workspace.
+2. Discuss your question and prepare a study brief with **Autonomous research**.
+3. Review its hypothesis, evidence requirements, completion policy and budget.
+4. Start the investigation and follow its experiments and **Evidence & review**.
+
+The [first-study tutorial](https://drawingsword.com/simjecture/getting-started/first-run.html) walks through the full
+counterexample-and-repair workflow. [Headless studies](https://drawingsword.com/simjecture/how-to/headless-studies.html)
+cover terminal launches and automation.
+
+## Bring your instruments and compute
+
+Ordinary Python studies work without an external solver. Optional capabilities
+include WarpX, operator-supplied FLASH, EOS/opacity tools, ITER diagnostics and
+[GPU cylinder flow](https://drawingsword.com/simjecture/how-to/cylinder-flow.html). The cylinder solver and its
+validation records were contributed by [Zifei Meng](https://github.com/ZifeiMengSPH).
+
+- [Commission a scientific instrument](https://drawingsword.com/simjecture/how-to/guided-commissioning.html) or
+  [add your own capability](https://drawingsword.com/simjecture/how-to/add-a-capability.html).
+- [Run experiments on local or SSH workers](https://drawingsword.com/simjecture/how-to/ssh-workers.html).
+- [Steer or continue an investigation](https://drawingsword.com/simjecture/how-to/continuation-steering.html).
+- [Compare agents on recorded diagnostic tasks](https://drawingsword.com/simjecture/how-to/llm-bench.html).
+- [Operate a hosted service](https://drawingsword.com/simjecture/how-to/public-trials.html).
+
+Native agents retain their existing tools and run with their host-account access.
+Numerical experiments use the selected execution backend, Bubblewrap by default.
+Read [security guidance](https://github.com/tomzhu0225/simjecture/blob/main/SECURITY.md) and
+[restricted-host setup](https://drawingsword.com/simjecture/how-to/restricted-containers.html) when deploying workers.
+
+## Contribute
+
+Help us test the research process on meaningful questions. Contributions can add
+scientific instruments, validated diagnostics, reproducible studies, numerical
+review, documentation or infrastructure. Start with [CONTRIBUTING.md](https://github.com/tomzhu0225/simjecture/blob/main/CONTRIBUTING.md)
+or [open an issue](https://github.com/tomzhu0225/simjecture/issues) to discuss a study
+or a substantial change.
+
+[Release notes](https://github.com/tomzhu0225/simjecture/blob/main/CHANGELOG.md) · [Release checks](https://drawingsword.com/simjecture/archive/index.html) ·
+[Research status](https://drawingsword.com/simjecture/research/status.html) · [Historical records](https://drawingsword.com/simjecture/archive/index.html)
+
+## Citation and license
+
+Use [CITATION.cff](https://github.com/tomzhu0225/simjecture/blob/main/CITATION.cff) and identify the exact version and Git commit used
+for a result. The [concept DOI](https://doi.org/10.5281/zenodo.21945748) identifies
+the release series.
+
+Copyright 2026 Bowen Zhu and contributors. Licensed under [Apache 2.0](https://github.com/tomzhu0225/simjecture/blob/main/LICENSE).
+See [third-party notices](https://github.com/tomzhu0225/simjecture/blob/main/THIRD_PARTY_NOTICES.md) for upstream attribution and
+redistribution requirements.