Setup examples/tutorials for the C API

[Luthaf]

This re-opens #305 which was merged without review.

This PR uses sphinx-gallery ability to parse non-Python examples to make tutorial for the C API. The corresponding code is tested separately, since sphinx does not know how to run it.

Contributor (creator of pull-request) checklist

• Tests updated (for new features and bugfixes)?
• Documentation updated (for new features)?
• Issue referenced (for PRs that solve an issue)?

Reviewer checklist

• CHANGELOG updated with public API or any other important changes?

[EricBoittier]

Looks good to me

[EricBoittier]

Review of code up to and including "1-create-system.c"

Follow-up PR for other examples (e.g. models, plugins, engines, etc) to come

[EricBoittier]

if (status != MTA_SUCCESS) {
    fprintf(stderr, "failed to get system size\n");
    mta_system_free(system);
    return EXIT_FAILURE;
}
printf("created system with %lu atoms\n", (unsigned long)size);

mta_string_t length_unit = NULL;
status = mta_system_get_length_unit(system, &length_unit);
if (status != MTA_SUCCESS) {
    fprintf(stderr, "failed to get length unit\n");
    mta_system_free(system);
    return EXIT_FAILURE;
}
printf("length unit: %s\n", mta_string_view(length_unit));
mta_string_free(length_unit);

// %%
//
// Query types, positions, cell, and PBC
// -------------------------------------
//
// :c:func:`mta_system_get_data` returns a **borrowed** DLPack view of the
// requested data. You must call the tensor's ``deleter`` when you are done;
// do not modify the underlying buffer.

DLManagedTensorVersioned* data = NULL;

status = mta_system_get_data(system, MTA_SYSTEM_DATA_TYPES, &data);
if (status != MTA_SUCCESS) {
    fprintf(stderr, "failed to get types\n");
    mta_system_free(system);
    return EXIT_FAILURE;
}
int32_t* types_view = (int32_t*)((char*)data->dl_tensor.data + data->dl_tensor.byte_offset);
printf("types:");
for (uintptr_t i = 0; i < size; i++) {
    printf(" %d", types_view[i]);
}
printf("\n");
data->deleter(data);```

//Consider adding examples for other queries

[Luthaf]

I'd leave this for a separate "working with systems" tutorial, intended for C model developers (all three of them), where this tutorial can also be useful to C engine developers (hopefully a couple more people)

[EricBoittier]

good, good, I see your point. That seems like a natural way to split the content. So anything else missing for C engine developers in this file? Maybe stresses?

[EricBoittier]

something like an "expected output" block could be nice to have, eg:

double* positions_view = (double*)((char*)data->dl_tensor.data + data->dl_tensor.byte_offset);
printf("positions:\n");
for (uintptr_t i = 0; i < size; i++) {
    printf("  %.3f %.3f %.3f\n",
           positions_view[3 * i + 0],
           positions_view[3 * i + 1],
           positions_view[3 * i + 2]);
}
data->deleter(data);

status = mta_system_get_data(system, MTA_SYSTEM_DATA_CELL, &data);
if (status != MTA_SUCCESS) {
    fprintf(stderr, "failed to get cell\n");
    mta_system_free(system);
    return EXIT_FAILURE;
}
double* cell_view = (double*)((char*)data->dl_tensor.data + data->dl_tensor.byte_offset);
printf("cell:\n");
for (int i = 0; i < 3; i++) {
    printf("  %.3f %.3f %.3f\n",
           cell_view[3 * i + 0],
           cell_view[3 * i + 1],
           cell_view[3 * i + 2]);
}
data->deleter(data);

status = mta_system_get_data(system, MTA_SYSTEM_DATA_PBC, &data);
if (status != MTA_SUCCESS) {
    fprintf(stderr, "failed to get pbc\n");
    mta_system_free(system);
    return EXIT_FAILURE;
}
uint8_t* pbc_view = (uint8_t*)((char*)data->dl_tensor.data + data->dl_tensor.byte_offset);
printf("pbc: %s %s %s\n",
       pbc_view[0] ? "true" : "false",
       pbc_view[1] ? "true" : "false",
       pbc_view[2] ? "true" : "false");
data->deleter(data);

// %%
//
// Running this program prints::
//
//     created system with 4 atoms
//     length unit: Angstrom
//     types: 1 1 6 6
//     positions:
//       0.000 0.000 0.000
//       0.500 0.500 0.000
//       0.500 0.000 0.500
//       0.000 0.500 0.500
//     cell:
//       1.000 0.000 0.000
//       0.000 1.000 0.000
//       0.000 0.000 1.000
//     pbc: true true true

[EricBoittier]

+// Free the system once it is no longer needed. The DLPack tensors have already
+// been consumed by mta_system_create and must not be freed again.
+
+mta_system_free(system);
+
+// %%
+
+return EXIT_SUCCESS; }
@Luthaf you would add an assert(cell == ...) which would fail loudly if the code changes?