Examples folder empty when cloned

[kbarnhart]

😢

I was going to post the BMI template I made for terrainbento before I put the terrainbento specific things in it... then I realized you guys have a great examples folder.

But something about the symlinks doesn't persist through cloning.

I can see examples online and cloning creates the folder structure but no files.

[mcflugen]

The folders in the examples folder are submodules. To include the submodules when you clone the repository you need to use the --recurse-submodules option,

$ git clone --recurse-submodules git@github.com:csdms/bmi

However, the plan is to remove all of the submodules in this repository and simply list examples in the README as links to projects that use BMI. That will be less confusing and more easily updated, I think.

If you would like terrainbento to be listed, perhaps you could add it to the README in a pull request???

[kbarnhart]

@mcflugen thanks for the info. --recurse-submodules worked as expected.

I think it would be helpful to have a links to examples (happy to link terrainbento when complete), but that providing a template that has all the functions, is not the abstract base class itself (which needs all the " -> np.ndarray" type stuff to be edited out), and is something that can be copied and have the ... within each function filled out is extremely helpful.

I have no opinions of where it should go.

[mcflugen]

I think the following should help you. First you need to install the bmipy package,

$ pip install bmipy

This contains the Bmi abstract base class from which your BMI components should inherit. Then, the following script should produce a template Bmi implementation.

import inspect
from bmipy import Bmi


def main():
    print("from bmipy import Bmi")
    print("import numpy")
    print("class MyBmi(Bmi):")

    func_template = """
    def {name}{signature}:
        raise NotImplementedError("{name}")"""

    for name, func in inspect.getmembers(Bmi, inspect.isfunction):
        print(func_template.format(name=name, signature=inspect.signature(func)))


if __name__ == "__main__":
    main()

I'll add this as a command line tool somewhere but I'm not sure where to put it yet.

[kbarnhart]

@mcflugen I tried this script, but it really isn't want I want.

What I want is almost exactly what is presently in the examples folder, in which you and @mdpiper have created a template with all of the necessary functions, the beginnings of docstrings (though it would be nice if the code blocks were python instead of C). This means that I don't have to edit all the abstract base class bits out of the bmi.py file, and I can just start adding my own implementations everywhere pass is written.

I have a follow up question about how to handle the ABC inheritance.

I modified the example so that the Bmi class (now called BmiModel) also inherits from the abstract base class.

from bmipy import Bmi
from .base import BmiBase
from .info import BmiInfo
from .time import BmiTime
from .vars import BmiVars
from .getter_setter import BmiGetter, BmiSetter
from .grid_rectilinear import BmiGridRectilinear
from .grid_uniform_rectilinear import BmiGridUniformRectilinear
from .grid_structured_quad import BmiGridStructuredQuad
from .grid_unstructured import BmiGridUnstructured


class BmiModel(Bmi, BmiBase, BmiInfo, BmiTime, BmiVars, BmiGetter, BmiSetter,
          BmiGridRectilinear, BmiGridUniformRectilinear, BmiGridStructuredQuad,
          BmiGridUnstructured):

All of the terrainbento models inherit from this BmiModel class.

But when I try and import a terrainbento model, I can't as it says that ALL of the BMI functions do not exist.

There is something related to inheritance that I must be doing wrong. Any recommendations?

[mcflugen]

@kbarnhart you need to implement all of the BMI methods. However, many of them may not apply to your model. In those cases, you should explicitly raise a NotImplementedError.

I'm not totally sure what you're wanting as a template. Have a look at the updated python example that uses the bmipy package. Maybe that's closer to what you're wanting?

[kbarnhart]

@mcflugen looking closer at the example, it turns out that there are some methods required by the ABC that are not implemented. This seems to be why I was having issues. The content in the example folder is almost what I'm looking for as a template.

As part of my work on terrainbento, I'll basically need to make the template I would want in the future. So I'll make a PR that makes these changes and we can then discuss where exactly it might want to live in the file and repo structures.

[kbarnhart]

A follow up.... The issue with the ABC was the order of inheritance. The ABC Bmi needed to be the last class listed in the parentheses.

from bmipy import Bmi
from .base import BmiBase
from .info import BmiInfo
from .time import BmiTime
from .vars import BmiVars
from .getter_setter import BmiGetter, BmiSetter
from .grid_rectilinear import BmiGridRectilinear
from .grid_uniform_rectilinear import BmiGridUniformRectilinear
from .grid_structured_quad import BmiGridStructuredQuad
from .grid_unstructured import BmiGridUnstructured


class BmiModel(BmiBase, BmiInfo, BmiTime, BmiVars, BmiGetter, BmiSetter,
          BmiGridRectilinear, BmiGridUniformRectilinear, BmiGridStructuredQuad,
          BmiGridUnstructured, Bmi):

Related to the other topic: where to put my eventual example, as @mcflugen and I discussed, we can determine a place to put my example that is sensible once it exists. So I'll leave this open until then.

[mdpiper]

In #56, all git submodules, including the examples, have been removed from the repository and replaced with links.