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!
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!
Note that the old URL, bmi.readthedocs.io, still worksâit automatically redirects to bmi.csdms.io.
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).
Great work! I was already reading the old docs so will switch to reading this!
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.
Yup, thatâs it! @mcflugen has a repository for the mappings that we can PR into.
Nice, thatâs very clever
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 - 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.
âŚ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
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!
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
.
I would be happy with that! Maybe the docs can say somewhere to look at the full BMI spec for info on types.
Makes sense, and I guess Java will use this
too (thatâs a Java thing, right?). I have no preference for either!
PR for bmi-map submitted
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.
@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.