Appendix

Use this appendix for final integration checks and one compact worked example. For terminology and abbreviations, see the Preface.

Integration Checklist

Functional Bring-Up Checklist

• Pack bytes validate before runtime create.
• tdse_model_create(..., &create_diag, ...) succeeds on the target host.
• tdse_model_info(...) matches expected np, nq, nh, and dt.
• The prime-step pattern (t0 - dt) is implemented intentionally.
• op, hr, ir, and commit wiring are step-aligned.
• tdse_step_dr(...) is only used after commit and outside an active trial step.

Lifecycle Checklist

• Ordinary host shutdown uses tdse_model_destroy(...), not tdse_model_release(...).
• Destroy wait policy is explicit and documented.
• The host handles TDSE_ERR_TIMEOUT intentionally.
• The host treats TDSE_ERR_INVALID_STATE during close or destroy as ownership handoff, not as local retryable success.
• RAII or destructor paths use tdse_model_release(...) only as terminal cleanup.

Diagnostics Checklist

• tdse_model_create_diagnostics_t is logged or archived on non-OK create paths.
• Runtime failure capture includes both tdse_model_state_info(...) and tdse_model_last_error_info(...).
• One known-failure path such as TDSE_ERR_IR_STEP_OUT_OF_RANGE is exercised and logged.
• Failure logs include API name, status, t, dt, and step index.

Concurrency Checklist

• One live runtime handle is owned by exactly one execution thread at a time.
• Same-handle concurrent step entry is prevented by host design.
• Threading stress remains green on the target build.
• The integration wrapper does not silently share a runtime handle across worker threads.

Worked Example (np=3, nh=4)

Use this example when you want one concrete end-to-end flow after reading the main manual.

What This Example Demonstrates

The example shows:

1. configure Builder for np = nq = 3, nh = 4
2. apply explicit time-domain H
3. apply optional IR
4. write a pack
5. create a runtime model with request-scoped diagnostics
6. run begin -> hr -> ir -> commit
7. query committed-step dr

Compact C Example

Builder half:

#include <tdse/tdse.h>
#include <tdse_builder.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>

int main(void) {
    const size_t np = 3, nh = 4;
    const double dt = 1e-3;

    /* ---- Builder: create pack ---- */
    double h[4 * 3 * 3] = {
        1,0,0, 0,1,0, 0,0,1,
        0.2,0,0, 0,0.2,0, 0,0,0.2,
        0.1,0,0, 0,0.1,0, 0,0,0.1,
        0.05,0,0, 0,0.05,0, 0,0,0.05
    };

    tdse_builder_t* b = NULL;
    tdse_builder_create(&b);

    tdse_builder_options_t opt = tdse_builder_options_init();
    opt.dt = dt; opt.nh = nh; opt.np = np; opt.nq = np;
    tdse_builder_configure_ex(b, &opt);

    tdse_h_desc_t hd = {0};
    hd.struct_size = sizeof(hd);
    hd.np = (int32_t)np; hd.nq = (int32_t)np; hd.nh = nh;
    hd.data = h;
    tdse_builder_apply_h(b, &hd);
    tdse_builder_write_pack(b, "appendix_example.pack");
    tdse_builder_destroy(b);

Runtime half:

    /* ---- Runtime: load and step ---- */
    FILE* f = fopen("appendix_example.pack", "rb");
    fseek(f, 0, SEEK_END); long sz = ftell(f); fseek(f, 0, SEEK_SET);
    unsigned char* pack = (unsigned char*)malloc((size_t)sz);
    fread(pack, 1, (size_t)sz, f); fclose(f);

    tdse_model_t* m = NULL;
    tdse_model_create_diagnostics_t diag = tdse_model_create_diagnostics_init();
    tdse_status_t st = tdse_model_create(pack, (size_t)sz, &diag, &m);
    free(pack);
    if (st != TDSE_OK) { printf("create failed\n"); return 1; }

    /* Prime step at n = -1 */
    double primary0[3] = {0,0,0};
    tdse_step_begin(m, -dt, dt);
    tdse_step_commit(m, primary0);

    /* Ordinary steps */
    double hr[3], ir[3], dr[3];
    for (size_t n = 0; n < 5; ++n) {
        double primary[3] = {sin(0.1*n), cos(0.1*n), 0.5};
        tdse_step_begin(m, n * dt, dt);
        tdse_step_hr(m, hr);
        tdse_step_ir(m, ir);
        tdse_step_commit(m, primary);
        tdse_step_dr(m, dr);
        printf("step=%zu hr=[%+.4f %+.4f %+.4f] dr=[%+.4f %+.4f %+.4f]\n",
               n, hr[0], hr[1], hr[2], dr[0], dr[1], dr[2]);
    }

    /* Bounded shutdown */
    tdse_model_destroy_options_t dopt = tdse_model_destroy_options_init();
    tdse_model_destroy_result_t dres = tdse_model_destroy_result_init();
    dopt.wait_timeout_ms = 250.0;
    tdse_model_destroy(m, &dopt, &dres);
    return 0;
}

What To Notice

Three details are worth carrying into production code:

• create uses request-scoped diagnostics
• the runtime loop keeps commit as the only state-advancing call
• shutdown uses bounded destroy rather than release