 I'm Mark. I'm a research software engineer at the CSDMS integration facility. Along with Eric Hutton, I make software that helps CSDMS members do science. And today, I'd like to talk about one of our products. It's the CSDMS Basic Model Interface, or VMI. Before I get into it, though, a couple logistical items. So one, everyone's mic is muted, and we'll do that until the end of the webinar. You can then heckle me at the end of the webinar. If you have any questions during the webinar, please enter them in the chat window. And at the end of the webinar, I'll review them and try to answer them. I think my presentation should take maybe about 30 minutes or so, depending upon how quickly I talk. Also, if you see me looking down, I have all my notes here on my iPad. So it's really interesting to try to read my notes and look at the camera at the same time. So just be aware of that. All right, so let's start. Today, in this webinar, I want to try to answer five questions. One, what is a BMI? Two, why is a BMI useful? Three, how does it work? Four, why would you, listen in the audience, want a BMI for your model? And five, how would you start? That's always the hardest part. All right, so the first question, what is a BMI? So a BMI is a defined set of functions that can be used to query, access, and control the state of a model. That's it. I'm done. Just kidding. So the details, the details are what makes this interesting. All right, so BMI includes functions for setting up and tearing down a model. It includes functions for advancing a model state through time, functions for getting and setting variables that are exposed by the model, as well as several helper functions as well. Now, just so that you're not surprised, here's a list of BMI functions. So yeah, there's a lot. The thing is, is that many of these are pretty simple to implement. They may only be a couple lines apiece. So I'm not saying it's easy to do a BMI. It's definitely not. It takes some time. But if you develop a model, you can definitely add a BMI to it as well. All right, so that's our first question. What is a BMI? It's a set of functions that we use to control a model. Here's our next question. Why is a BMI useful? And to answer this question, I'm going to go back in time, way back in time to the beginnings of CSDMS 10 years ago. So to answer this, CSDMS was designed to embrace a community-driven bottom-up approach to modeling. This differs from how modeling is done in other fields. I'm thinking atmospheric science, for example. There's a lot of really big models that people work with. So the idea is that, this is step one, individual researchers in the community could write their own models in the language of their choice. So as shown in my diagram, models come in all shapes and sizes. Some of them are big, some of them are small, some of them are written in C, others in Fortran, others in Python, et cetera. So in the next step, step two, the models could be coupled together in a model coupling framework. The idea is that they could exchange information and possibly have feedbacks as well. So for example, let's say I have a riverine sediment transport model and also a landscape evolution model. I could couple them together. And for example, maybe the landscape evolution model has an uplift event. The river model could then erode the landscape and transport sediment away downstream. Maybe that could be coupled to a delta model then. You get the idea. So step three then is it was hoped that this flexible, bottom-up, community-driven approach to science could advance science. All right, so that second step, that's what became the CSDMS modeling framework. But the question is here, how do we get to a model coupling framework from what I've shown in this diagram, from this crazy assemblage of models, this mishmash of models? And I think you know where I'm going here. If we can standardize the way that we interact with models, it's easier to work with them, both for us as humans writing code as well as for machines to automatically couple models. This is where BMI comes in. It's one part of the CSDMS modeling framework. So here's a little sketch that can help show why a BMI would be useful. So say, for example, that I have two models, A and B. For simplicity, let's assume that they're written in the same language. They don't have to be, but for this case, we'll use that. Even though they're in the same language, they could have very different setups and ways of running them, for example. If we wrap these models with the BMI, and again, let's assume that the BMIs are in the same language, although again, they do not have to be. Then you can see that each model has a standard interface as depicted by the pleasingly congruent puzzle pieces. All right, and then we could, in theory, couple these models together. They could exchange information through their BMIs. You can see the puzzle pieces snap together with a click. So this actually does work. I can couple models. I've done this like in Python, as it's pretty easy to do there. You can couple models through their BMIs. This really, though, is the domain of a model coupling framework, because there's a bunch of other things to consider, but it is possible with a BMI. So this is a little bit about why a BMI is useful. The idea is that we could couple models together to exchange information. The third question, how does a BMI work? When a scientist writes a model, they can choose to wrap it with a BMI. It doesn't change anything about the model. The model still works just as it did before, but now their model has a standardized interface, and this is key, because once you've seen one BMI, you've seen them all. All these functions are the same across languages in Fortran I have initialized, in C I have initialized, in Python I have initialized, to dig a little deeper. In computer science, an interface is roughly defined as a set of functions that contain no data themselves, but they do define the types and shapes and sizes of the inputs and outputs to the function. When a developer implements an interface, they fill out the details, the insides of the functions. The advantage of having an interface is that a person using it knows exactly what goes in and goes out of each function. So when you, the model developer implements a BMI, you're gonna fill in the insides of these BMI functions. You're gonna fill it in with details that are particular to your model. All right, so why would you want to use BMI in your model? I've given you a story so far that seems like a little bit hard to use and hard to work with, but there's some good value that you get from using it. All right, I've got five items I like to elaborate on. So one, you get a standardized interface. Again, this may not be helpful for you, but by adding a standardized interface, it makes it easier for others to work with your model, because again, once you've seen one BMI, you've seen them all. Two, exposure. So a BMI model contributed to the CSDMS model repository gets more exposure on the CSDMS website. Further, and this is a little bit outside of the domain of this webinar, but further, if the community desires it, a BMI model can be integrated into the CSDMS modeling framework. It can then be called programmatically through PyMT, the Python modeling toolkit, or interactively through WMT, the web modeling tool. So you can gain some notoriety for having a model that has a BMI. All right, three, good programming. So in order to add a BMI to a model, the model has to have some degree of modularity. You have to be able to tease out the initialize, run, and finalize steps at the very least. And so modular programming is a good thing. It makes it easier to test and debug programs. So by adding a BMI, oftentimes people have to go back and refactor their initial model code, thereby making it better in the process. Four, community. So by adding a BMI to your model, you are contributing to a community of modelers. Recall that we're a bottom-up organization. We gain strength in numbers. The more people BMI their models, the more people in turn will BMI their models. Lastly, five, and I'm shooting big here, but coupling with other models, possibly serendipitously, written by other people in other areas of research. This is facilitated by BMI. What you write could be used by someone else that you may not know to make a scientific discovery. We're enabling science. All right, so these are examples of why it's good, why you would want to add a BMI to your model. The last question is where to start? How would you start doing this? This is again, always the hard part. And so I want to go through four resources that we have. These are all online and let me quickly enumerate them. Then I'll share my web browser and we'll look at them together. So first of all, on the CSDMS Wiki, we have a page for BMI that describes it and gives links. Second, we have documentation, user documentation for working with BMI. Third, you can see the GitHub repository where we collect all the BMI's for the languages that we support in CSDMS. And finally, I have an example that I've used for a couple of years in the CSDMS annual meeting in the BMI live play. And I think it gives a nice and simple, like I tried to make it as simple as possible for adding a BMI to a model. Okay, let's take a look at my web browser. I'm trying to figure this out here. Okay, so we're starting here at the CSDMS Wiki, csdms.colorado.edu. Let's go first to the BMI page. So you can see under products, basic model interfaces listed first. All right, so this page gives a short overview of BMI and importantly, it collects some very useful links. The first link is a link to the BMI documentation. So this is where you can get the details, things that I'm glossing over in this presentation about using BMI. So for example, I'm just gonna go to one of the pages. Okay, so you can see the functional prototypes of initialize the time stepping functions and finalize. All right, so these are, we're prototyping, we're saying basically what goes in and what goes out of each of these BMI functions. We've listed prototypes in CIDL. This is the scientific interface definition language. It's kind of a generic way of prototyping functions, as well as C and C++. I need to add Fortran, which I've been working on and Python and Java here as well. All right, so this is the documentation. Next then, the BMI GitHub repository. Again, this is just linked from our Wiki. All right, so this is where we collect all of the BMI's that we have written, that we support here at CSDMS. You can see them underneath the bindings link. So this is a made-up package. You'd actually click on these to go to the individual BMI's. So C, C++, Python, Java, and Fortran. I'm particularly pleased I've been working on the Fortran one lately. I've been having a lot of fun with that. So the Fortran one I'm currently working on as well. All right, then the last item I want, well, I guess I can also show the original article. This is the Peckham, Hutton, and Norris article where BMI was defined initially. That's also linked from this page. And then finally, the BMI live repository. Let me take a few minutes to talk about this because I think this is, again, a nice place to start. Not everyone knows Python, but it's a nice enough language that many people have at least some exposure to it. So I've found this to be a useful way to try to talk about and show BMI to people. All right, so this is a package. You can just download, you can clone it, and then Python set up develop in order to make it work. If anyone tries this and has issues, please email me and let me know I can help. Let me show the code that I've developed for it quickly as well as the notebooks that I use to drive the examples. All right, so under the BMI live folder, I wanna look at two files. There's a file called diffusion.py and a file called BMI diffusion.py. You can guess which is which. Let's look at diffusion.py first. So this is a model. I called it diffusion. I chose to write it as a class. You don't have to do that though. If you don't wanna do object-oriented programming, you can just do procedural programming in Python. All right, so this is just a simple model of diffusion. I think I used temperature. So temperature diffusion over a 2D plate. So that's it for the model. So you can see it has an initialize, it has an advance and a solve method. So that's 54 lines of code for a very short little model. And I tried to make the model language agnostic as well. So I didn't use any Python tricks for my for loops. I wrote them out. So this code could almost be rewritten verbatim in C or Fortran. All right, so that's the model itself. The BMI for the model is in BMI diffusion.py. Again, I chose to write it as a class because as you scroll down, you can see there's initialize. There's update. You can see update just takes one line, for example. Update frack, update until. There's finalize, finalize is another one liner. So some of the methods are pretty straightforward to implement. But in this example, I tried to make a full BMI for this little model. Going back up to the top directory. So that was the code under the NB directory. I have Jupyter notebooks to try to drive the examples. I have three notebooks. One just runs the model. Two runs the model through its BMI. And three just does some visualization. Let me show the second one where I run the model for the BMI. All right, so some instructions for setting it up. You scroll down, you can see, I make a new instance of my BMI model and I'm calling BMI methods then. Now, importantly, the neat thing about this is that I could almost copy and paste this Jupyter notebook because I'm gonna call initialize. And again, it's a standardized interface. So I call initialize with a configuration file. I call get start time, get end time. I'm gonna call update, all right? So all these methods are standardized. You don't have to know that underneath the hood, my little model has a solve method or an advance method. All you need to know are the BMI methods. Okay, so hopefully what I've shown here now are some resources that you can use to get started writing a BMI for your model. And again, if you have questions, Eric and I are more than happy to help. You can just email us and we can try to help you get started as well. All right, let me get back to my slides. Here are my slides, there they are. So resources. All right, so that's it. So in summary, the idea of a BMI provides a standardized interface for a model. And this is really helpful because once you've seen one BMI, you've seen them all. If someone else writes a BMI, I know exactly how to control and talk to the model through its BMI. I'm going big in my summary here as well. The idea is that if you have a BMI model, you can add it to a modeling framework. Maybe not the CSDMS modeling framework. Maybe someone else's modeling framework. And through this, you can do science. All right, thanks for your attention. If you have any questions, I will help, I will ask Linda unmute the mics and I'll also look at any questions in the chat window. Thank you, I need to find my chat window here. Mark, I don't see anything in chat yet. Oh, good, all right, thank you. Because I can't figure out how to change this without unsharing my screen. If anyone has any questions, if your mics are on, so feel free to shoot away. Actually, I think they may need to unmute themselves. Oh, okay, all right. Lower corner. Got it. Everyone, you are allowed to unmute yourselves. While people are thinking about questions, one little item you saw in my example that I placed the BMI for my model in the same directory as the source code, that's kind of a convention that we've been using, but it's not necessary. You can put the code for your BMI anywhere just as long as it knows where the source code is. Because it needs to talk to the source code for the model or the compiled library for the model. Okay, well, if there are no questions then, maybe we can wrap up. So again, I invite everyone, if you have questions, feel free to contact me. My emails listed here, my GitHub handle, my Twitter handle are here. Also, feel free to come to our CSDMS annual meeting. You can talk BMI. I'll do a BMI live clinic again this year. All right, so thanks everyone for attending. Thanks, Mark. All right.