# A new home for the BMI documentation

**URL:** <https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44>\
**Category:** BMI\
**Tags:** bmi, documentation\
**Created:** [November 25, 2024, 7:25pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44 "2024-11-25T19:25:38Z")\
**Posts on this page:** 15\
**Page:** 1

<div class="post-metadata">

**Author:** ![mdpiper](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/mdpiper/32/1_2.png) [@mdpiper](https://forum.csdms.io/u/mdpiper)\
**Post date:** [November 25, 2024, 7:25pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/1 "2024-11-25T19:25:38Z")

</div>

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](http://bmi.csdms.io). Please visit and check out the changes!

---

<div class="post-metadata">

**Author:** ![mdpiper](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/mdpiper/32/1_2.png) [@mdpiper](https://forum.csdms.io/u/mdpiper)\
**Post date:** [November 25, 2024, 7:26pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/2 "2024-11-25T19:26:26Z")

</div>

Note that the old URL, [bmi.readthedocs.io](https://bmi.readthedocs.io), still works—it automatically redirects to [bmi.csdms.io](https://bmi.csdms.io).

---

<div class="post-metadata">

**Author:** ![mdpiper](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/mdpiper/32/1_2.png) [@mdpiper](https://forum.csdms.io/u/mdpiper)\
**Post date:** [November 25, 2024, 7:29pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/3 "2024-11-25T19:29:01Z")

</div>

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).

---

<div class="post-metadata">

**Author:** ![dorchard](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/dorchard/32/8_2.png) [@dorchard](https://forum.csdms.io/u/dorchard)\
**Post date:** [November 25, 2024, 9:36pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/4 "2024-11-25T21:36:07Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![samharrison7](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/samharrison7/32/9_2.png) [@samharrison7](https://forum.csdms.io/u/samharrison7)\
**Post date:** [November 25, 2024, 9:46pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/5 "2024-11-25T21:46:24Z")

</div>

> [@mdpiper](#):
>
> Also note that we still have to do Fortran and Java mappings for the docs.

Do you mean the language-specific tabs on [this page](https://bmi.csdms.io/en/stable/bmi.control_funcs.html)? 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.

---

<div class="post-metadata">

**Author:** ![mdpiper](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/mdpiper/32/1_2.png) [@mdpiper](https://forum.csdms.io/u/mdpiper)\
**Post date:** [November 25, 2024, 10:42pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/6 "2024-11-25T22:42:53Z")

</div>

> [@samharrison7](#):
>
> Do you mean the language-specific tabs on [this page](https://bmi.csdms.io/en/stable/bmi.control_funcs.html)?

Yup, that’s it! @mcflugen has a [repository](https://github.com/mcflugen/bmi-map) for the mappings that we can PR into.

---

<div class="post-metadata">

**Author:** ![samharrison7](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/samharrison7/32/9_2.png) [@samharrison7](https://forum.csdms.io/u/samharrison7)\
**Post date:** [November 25, 2024, 10:50pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/7 "2024-11-25T22:50:49Z")

</div>

Nice, that’s very clever 🙂

---

<div class="post-metadata">

**Author:** ![samharrison7](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/samharrison7/32/9_2.png) [@samharrison7](https://forum.csdms.io/u/samharrison7)\
**Post date:** [December 6, 2024, 9:08am UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/8 "2024-12-06T09:08:50Z")

</div>

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.

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

```

But Fortran requires multiple lines:

```fortran
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](https://github.com/csdms/bmi-fortran/blob/master/bmi.f90) 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 😀 - 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.

---

<div class="post-metadata">

**Author:** ![samharrison7](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/samharrison7/32/9_2.png) [@samharrison7](https://forum.csdms.io/u/samharrison7)\
**Post date:** [December 6, 2024, 9:31am UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/9 "2024-12-06T09:31:10Z")

</div>

…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](https://bmi.csdms.io/en/stable/bmi.getter_setter.html#set-value) or bmi-map definition.

Pseudo-Fortran code could be an option again…

```auto
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

```

---

<div class="post-metadata">

**Author:** ![mdpiper](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/mdpiper/32/1_2.png) [@mdpiper](https://forum.csdms.io/u/mdpiper)\
**Post date:** [December 6, 2024, 4:47pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/10 "2024-12-06T16:47:42Z")

</div>

> [@samharrison7](#):
>
> Also, the [Fortran spec](https://github.com/csdms/bmi-fortran/blob/master/bmi.f90) uses `this` but C/Python uses `self` - any preferences?

I chose `this` because both [modflow6](https://github.com/MODFLOW-USGS/modflow6) and [prms6](https://github.com/nhm-usgs/prms/tree/6.0.0_bmi_dev) 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!

---

<div class="post-metadata">

**Author:** ![mdpiper](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/mdpiper/32/1_2.png) [@mdpiper](https://forum.csdms.io/u/mdpiper)\
**Post date:** [December 6, 2024, 5:30pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/11 "2024-12-06T17:30:00Z")

</div>

What about using only the function signature? So

```fortran
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`.

---

<div class="post-metadata">

**Author:** ![samharrison7](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/samharrison7/32/9_2.png) [@samharrison7](https://forum.csdms.io/u/samharrison7)\
**Post date:** [December 6, 2024, 5:51pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/12 "2024-12-06T17:51:52Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![samharrison7](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/samharrison7/32/9_2.png) [@samharrison7](https://forum.csdms.io/u/samharrison7)\
**Post date:** [December 6, 2024, 5:53pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/13 "2024-12-06T17:53:32Z")

</div>

> [@mdpiper](#):
>
> I chose `this` because both [modflow6](https://github.com/MODFLOW-USGS/modflow6) and [prms6](https://github.com/nhm-usgs/prms/tree/6.0.0_bmi_dev) use it, and they were the big Fortran models I was looking at when I was thinking about the mappings.

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

---

<div class="post-metadata">

**Author:** ![samharrison7](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/samharrison7/32/9_2.png) [@samharrison7](https://forum.csdms.io/u/samharrison7)\
**Post date:** [December 7, 2024, 8:09am UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/14 "2024-12-07T08:09:30Z")

</div>

PR for bmi-map submitted 🙂

> <https://github.com/mcflugen/bmi-map/pull/19>
>
> Based on the discussions \[here\](https://forum.csdms.io/t/a-new-home-for-the-bmi-…documentation/44), this PR adds Fortran mapping. This outputs only the function signature and so, for Fortran, doesn't include type/kind information. E.g., for \`set\_value\`:
> 
> \`\`\`
> function set\_value(this, name, src) result(bmi\_status)
> \`\`\`
> 
> rather than something more complicated like:
> 
> \`\`\`
> function set\_value\_\[int|float|double\](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
> \`\`\`
> 
> I'd happy to adapt to a different version that includes the type information, if that would be preferred.
> 
> I also added a couple of tests to make sure it works as expected.

For the docs, is it a case of manually editing the relavent .md files (e.g. [this one](https://github.com/csdms/bmi/blob/develop/docs/source/bmi.control_funcs.md)) or is there a cleverer way than that? I spotted the `map-bmi-function` directive [here](https://github.com/csdms/bmi/blob/0357f7287875c4e6621d1bf1df00c873d2a68931/docs/source/conf.py#L71-L96) but wasn’t exactly sure if/how it was used.

---

<div class="post-metadata">

**Author:** ![mcflugen](https://yyz2.discourse-cdn.com/flex012/user_avatar/forum.csdms.io/mcflugen/32/11_2.png) [@mcflugen](https://forum.csdms.io/u/mcflugen)\
**Post date:** [December 7, 2024, 10:16pm UTC](https://forum.csdms.io/t/a-new-home-for-the-bmi-documentation/44/15 "2024-12-07T22:16:51Z")

</div>

@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.