Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor model API in terms of "Components". #131

Merged
merged 9 commits into from
Mar 15, 2024
Merged

Refactor model API in terms of "Components". #131

merged 9 commits into from
Mar 15, 2024

Conversation

iago-lito
Copy link
Collaborator

@iago-lito iago-lito commented Sep 14, 2023

This is a big shot attempting to address #114, #122, #84, #73, #74, #54 and #126 at once, while not refactoring the package internals yet so we can settle on a stable API and release the library/paper sooner.

  • Move all current implementation to an Internals submodule, so that none of it is exposed to user anymore. (:scream:)

  • Craft a dedicated framework making sense of the safe concepts of System, Component, Blueprint, Method (documentation here).

    • Implement.
    • Test.
    • Document.
  • Write a fresh API to re-expose existing internals, but via the above framework :

    • Expose const Model = Framework.System{Internals.ModelParameters}.
    • Sketch Foodweb component.
    • Sketch FunctionalResponse components.
    • Sketch ProducerGrowth components.
    • Sketch NonTrophicLayer components.
    • Sketch simulate method.
    • Integrate biorates-related features into the above.
    • Integrate allometry/temperature-related features into the above.
    • Integrate post-simulation processing features into the above. (see Simulation output utils are absent from components API. #137)
  • Extract/adjust existing documentation from the internals to the main module. (Update doc wrt components API. #135)

  • Make the use cases work again. (Update use cases wrt components API. #136)

  • Make the doctests work again. (see Docstrings/Doctests are missing from the component API. #140)

I expect this is a good opportunity to design/stabilize the eventual API we want without bothering yet with any refactoring of the Internals. To push this PR forward, just focus on how we would like the package to be used :)

Example fresh, configurable basic pipeline with the "components" approach:

m = Model()
m += Foodweb([:a => :b, :b => :c])
m += BodyMass(1)
m += MetabolicClass(:all_invertebrates)
m += BioenergeticResponse(; w = :homogeneous, half_saturation_density = 0.5)
m += LogisticGrowth(; r = 1, K = 1)
m += Metabolism(:Miele2019)
m += Mortality(0)
B0 = 0.5
sol = simulate(m, B0)

other examples here

The idea is to focus on constructing a stable API now,
in a way that does not depend on the internals,
so we can completely rewrite them after publication
without introducing breaking changes to user code.
- Craft a safe+flexible framework abstracting over the internals:
  - Stick to the underlying *network* model, rather than matrices/vectors.
  - Make the construction of an invalid model impossible from the exposed API.
  - Leave room for future extensions with an open list of model components.

- Split tests into successive modules build on top of each other.

- Re-expose most of the internal features in terms of this model:
  - Aliased Dicts.
  - Foodweb
  - Functional Response
  - Multiplex API
  - Nutrients
  - Biorates.
  - Allometry.
  - Temperature.
  - Simulation.
@iago-lito iago-lito merged commit c8cff86 into dev Mar 15, 2024
0 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment