A new home for the BMI documentation

BMI
,
1

Last week, @mcflugen overhauled the BMI documentation, improving navigation and modifying internals to make it easier to maintain over time.

We also gave the BMI docs a new home: bmi.csdms.io. Please visit and check out the changes!

2 Likes
2

Note that the old URL, bmi.readthedocs.io, still works—it automatically redirects to bmi.csdms.io.

3

Also note that we still have to do Fortran and Java mappings for the docs. I can do this, but if anyone else is interested, help would be welcomed (and you’d be acknowledged as a contributor in the docs).

4

Great work! I was already reading the old docs so will switch to reading this!

1 Like
5

Do you mean the language-specific tabs on this page? If so, I can probably tackle this! But not for a couple of weeks, so I don’t mind if someone wants to jump in first.

1 Like
6

Yup, that’s it! @mcflugen has a repository for the mappings that we can PR into.

2 Likes
7

Nice, that’s very clever :slightly_smiling_face:

8

I just started digging into the Fortran mappings and immediatedly came across the issue of how to define types. All of the other languages can be done as a nice tidy one-liner in the function definition, e.g.

def initialize(self, config_file: str) -> None:

But Fortran requires multiple lines:

function initialize(self, config_file) result(bmi_status)
    class(bmi), intent(out) :: self
    character(len=*), intent(in) :: config_file
    integer :: bmi_status

The other approach (which I don’t really like) is use some kind of pseudo-Fortran, like

function initialize(class(bmi)::self, character(len=*)::config_file) result(integer::bmi_status)

Also, the Fortran spec uses this but C/Python uses self - any preferences?

Thought I’d throw this out here for comments - @mdpiper and @mcflugen I’m looking at you :grinning: - before going down a particular route! We could pop this discussion across to the bmi-map repo if it’s better placed there, but I thought it might be broadly of interest to folks here.

9

…another Fortran question. How do we deal with functions that could take integer, float or double as a parameter, like the src parameter of set_value? These are implemented as separate interfaces in the Fortran spec, but that doesn’t align with the docs or bmi-map definition.

Pseudo-Fortran code could be an option again…

function set_value(this, name, src) result(bmi_status)
    class(bmi), intent(inout) :: this
    character(len=*), intent(in) :: name
    [integer|real|double precision], intent(in) :: src(:)
    integer :: bmi_status
10

I chose this because both modflow6 and prms6 use it, and they were the big Fortran models I was looking at when I was thinking about the mappings.

As an aside, when I was working on the Fortran mappings years ago, I had a really hard time finding anyone to talk to about modern Fortran development techniques. So you’re right to be suspicious about any part of the Fortran mappings that I wrote!

1 Like
11

What about using only the function signature? So

function initialize(self, config_file) result(bmi_status)

There’s so much more one needs to know about implementing a BMI in Fortran that I don’t think giving an incomplete sketch of the BMI function is a bad thing.

This would also handle the problem of multiple type definitions in, e.g., set_value.

1 Like
12

I would be happy with that! Maybe the docs can say somewhere to look at the full BMI spec for info on types.

1 Like
13

Makes sense, and I guess Java will use this too (that’s a Java thing, right?). I have no preference for either!

1 Like
14

PR for bmi-map submitted :slightly_smiling_face:

For the docs, is it a case of manually editing the relavent .md files (e.g. this one) or is there a cleverer way than that? I spotted the map-bmi-function directive here but wasn’t exactly sure if/how it was used.

1 Like
15

@samharrison7 Thank you! We can discuss more in your PR but I think the output should be more along the lines of the verbose output that includes the type information.

As far as the docs go, have a look at that same file you linked to but on the stable branch (you’ve linked to the develop branch, which I’ve yet to update with these latest documentation changes). On the stable branch you’ll see that we use the map-bmi-function directive to automatically generate the language mappings.

1 Like