Create a model integration

Role: Model author, model owner or co-admin. Start here if you have a Python calculation or an existing solver and want other people to run it through Enumeray. The downloaded projects need Python 3.9+ and tar for extraction; they run locally without an account, API checkout, Rust toolchain or model installation. Install the CLI when you want to generate a new project or continue to publication.

The scalar example doubles a number. It demonstrates the integration boundary; replace its science and numerical assertions before publishing a real model. Commands below run in a terminal. The generated-project walkthrough uses model ID example; bundled projects have the explicit IDs listed below. Choose your own ID before scaffolding. IDs start with a lowercase ASCII letter and contain up to 64 lowercase letters, digits, underscores or hyphens.

Run the downloaded examples offline

Download the model examples archive and its SHA-256 file into one new directory, keeping those filenames. Check and extract them there:

python3 - <<'PY'
from hashlib import sha256
from pathlib import Path
archive = Path("model-examples.tar.gz")
expected = Path("model-examples.tar.gz.sha256").read_text().split()[0]
if sha256(archive.read_bytes()).hexdigest() != expected:
    raise SystemExit("Archive checksum mismatch")
PY
tar -xzf model-examples.tar.gz
cd enumeray-examples-*
python3 verify-examples.py --root .

The extracted directory name contains its package version and public source revision. examples-manifest.json records that identity and the included file hashes. The verifier checks those bytes, then tests fresh copies of the scalar and collection examples and all four Python/executable, JSON/file starters. Successful tests establish the demonstrated calculation and protocol behavior; they do not contact a service or establish scientific suitability for your research.

For one editable Python scalar project, start from the extracted root:

cd starter-kit/python-json
python3 -B -m unittest discover -s . -p 'test_*.py'

This bundled project’s model ID is starter-python-json, its example name is starter-example, and input 2 produces 4. The walkthrough below generates the same kind of project under model ID example. Keep the chosen project’s publication.json, request fixtures and model ID together. The model example family map also identifies the file, native executable, standalone scalar and collection variants. Individual JSON downloads are declarations or envelopes; download the full archive to obtain their code, fixtures and tests together.

Create and execute a local project

Run from the directory where you want the new project:

enumeray model init example --directory example
cd example
python3 -B -m unittest discover -s . -p 'test_*.py'

model init creates a new directory and editable files; its parent must already exist. It refuses an existing destination. Tests create disposable workspaces, execute the wrapper, compare scientific results, and check malformed requests, failures and preservation of existing results. A passing starter is the starting point for your own scientific tests.

File	What you change or use it for
model.py	Scientific Python functions; no Enumeray dependency
implementation.py	Maps declared inputs into your calculation and maps results back
wrapper.py, protocol.py	Command entrypoint, request validation, result identities and durable JSON publication
publication.json	One editable declaration: metadata, science, schemas/examples and execution settings
fixtures/request.json, fixtures/expected-result.json	Complete wrapper envelopes for local execution and assertions
test_starter.py, test_protocol.py	Scientific assertions and shared protocol-boundary checks; run both, and update scientific assertions when changing the calculation
AUTHOR_GUIDE.md, ANALYSIS_GUIDE.md	Complete author and analysis guides shipped with the standalone project

For a manual scalar run, keep the project unchanged during execution and put result files in a fresh workspace:

PROJECT_DIR="$(pwd)"
WORK_DIR="$(mktemp -d)"
cd "$WORK_DIR"
python3 "$PROJECT_DIR/wrapper.py" execute \
  --request "$PROJECT_DIR/fixtures/request.json" \
  --result "$WORK_DIR/result.json"
python3 -m json.tool "$WORK_DIR/result.json"
cd "$PROJECT_DIR"

The command prints Wrapper: succeeded to stderr, exits 0, and saves a result whose outputs are {"doubled":4}. The full result echoes four request UUIDs. Running it again with the same result path fails while preserving that file. Use a fresh workspace for another local execution; do not delete evidence to retry an uncertain production run.

Choose a starter for your implementation

These commands create separate projects; run them from a common parent, outside example:

# Python implementation with an uploaded CSV input and downloadable CSV output
enumeray model init csv-example --directory csv-example --io files

# Existing executable, scalar JSON input/output
enumeray model init solver-example --directory solver-example --kind executable

# Existing executable with files, prepared for a Slurm site
enumeray model init cluster-example --directory cluster-example \
  --kind executable --io files --driver slurm

Defaults are --kind python --io json --driver process. All four Python/executable and JSON/file combinations can be tested locally. --driver slurm adds a model-owned model.sbatch and its path in publication.json; the unit tests still invoke the wrapper directly and do not require a scheduler. Executable projects add demo_solver.py; replace the fixed solver command and native-format mapping in implementation.py.

Read scientific contracts for complete declarations and wrappers for full request/result JSON, file staging and native solver examples.

The scaffold leaves execution.context_id and execution.release_path unset. Your local tests work immediately. model validate requires those deployment values; fill them after agreeing on an immutable installation. Validation creates no candidate ID. Use model create example --file publication.json once to import catalogue metadata without repeating it. The heliosphere-only EUHFORIA layout is an illustrative integration design requiring real scientific mapping, rather than another runnable starter.

Move from local tests to a usable offering

Step	Owner and prerequisite	Action and evidence
Define and test	Author, scientific implementation	Edit the contract, mapping and fixtures; run the local tests
Install	Author with OS access, or connector owner	Copy a complete release under an approved root; verify execution-account access and dependencies
Select compute	Connector owner has granted your account compute access	enumeray connector grant available shows a suitable context
Complete declaration	Author, agreed context and immutable installed release	Edit publication.json directly; model validate --file publication.json checks it offline
Save and register	Model owner/co-admin with an active compute grant	model release init example --file publication.json --directory release-r1 freezes one candidate; model release resume release-r1 registers and waits
Trial the exact candidate	Author or named delegated reviewer with current candidate authority	analysis init MODEL --candidate CANDIDATE_ID --inputs inputs.json --directory trial-r1, review disclosure, then submit/wait/collect that folder and complete scientific assertions
Review and activate	Model owner/co-admin, candidate is ready and scientifically checked	Release status/review includes trial evidence automatically; model release review release-r1, then explicit model release activate release-r1
Share and exercise	Model owner/co-admin and authorized model users	Choose visibility/run access, then initialize, review, submit and collect an ordinary analysis folder

Follow installation and publication for complete process/Slurm declarations, copy commands, registration, readiness and a smoke run. Then follow sharing and updates for access decisions, co-admins, updates and rollback. The complete author guide also works as a single sequential walkthrough.

Connector owners control hosts, credentials, execution identities, launchers and permitted roots. Authors control their science, wrapper, runtime setup and installed release contents. A compute grant does not install your software or grant OS access. For Slurm, the author’s batch file supplies resource requests and runtime setup; the site’s scheduler controls allocation.

Interpret each successful check correctly

Local tests execute your wrapper and can establish the scientific behavior you assert. Manifest validation checks the supported declaration and installation settings. API registration checks administration, compute authorization and context policy. Connector readiness observes entrypoint/batch-file digests, execution identity and backend access; it does not run every scientific example or verify every dependency or dataset. An actual submitted run exercises the installed execution path.

Keep immutable releases and their original connectors available while accepted work references them. Updating the current publication does not rewrite previously accepted runs. Use separate model integrations for stable parallel offerings that users should discover and choose independently.