Proper API for GoldSim

Answered

Follow

Ifariasg

• July 23, 2025 17:11

Hello,

I know this topic has already been discussed before and discarded (Goldsim API? – GoldSim Help Center), but I feel a lot has changed in the past seven years.

Perhaps it's time for GoldSim to reconsider and adopt what many other Earth system modeling software do: Have an API in some programming language.

GoldSim is still unique, but not being able to easily interact with models from "outside" is a problem. Standards like BMI (BMI • CSDMS: Community Surface Dynamics Modeling System. Explore Earth's surface with community software), I "feel" are not that far-off considering there is already a (limited) CLI interface for GoldSim (and no, GSPy or linking with DLLs is sadly not the solution).

0

• Official comment

  

  Rick Kossik

  • July 23, 2025 18:40

  What organization are you with (I see you are using a gmail address)?

  Comment actions Permalink
• 

  Rick Kossik

  • July 23, 2025 19:01

  Just so I understand: You want an API so that some other program could run (and presumably edit, etc.) a GoldSim model (as opposed to GoldSim calling other programs)?  Can you explain exactly what you wish to do? 

  0

  Comment actions Permalink
• 

  Ifariasg

  • July 23, 2025 19:36
  • Edited

  Hello Rick,
  I just logged into the forum with the easiest option that in my case was Gmail. I'm currently affiliated with a university in case you need to know.

  I didn't write this thinking on a particular use case, but for the past couple of years I've been exposed to several models that are BMI compliant and had always though how powerful it would be to have such a feature in GoldSim.
  The immediate use case that I can think is easy 2-way coupling of Goldsim with external models. I know this is currently possible through GSPy or other Dll's but it's really night and day how easy it can be done through an external control script that runs and updates 2 BMI compliant models.
  If it helps, I can expand on more use cases later.

  0

  Comment actions Permalink
• 

  Rick Kossik

  • July 23, 2025 19:59

  Thanks for the response.  The use case is critical.  When you speak of an API, I am thinking that you want another program to call and control GoldSim (not vice versa, which is what our current DLL implementation does). If you want to use an API to control GoldSim, the question becomes what exactly do you want to do? Which features of GoldSim do you want the external program to be able to  interact with?  Do you want the external program to create and edit elements (in which case this would be a massive task indeed)? Or do you just want it to run GoldSim?  If running GoldSim, do you want to control the simulation settings?  How would the external program access results - directly or via spreadsheets or databases? And if an external program is going to run GoldSim, how would licensing be handled? (GoldSim may be free for academics, but if we provided it free to everyone we obviously could not stay in business).  Moreover, for this to be "easy" it sounds like this would require both GoldSim and the program GoldSim is talking to to be BMI compliant? In that case, we would surely need to know how many commercial products that customers might want GoldSim to link to are BMI compliant. None of these tasks are trivial, so without specific use cases (and, more importantly, customer demand), it would be very difficult for us to embark on such a large (and time and cost intensive) undertaking.

  0

  Comment actions Permalink
• 

  Ifariasg

  • July 23, 2025 20:57

  We are fully theorizing now, but how I see it, indeed making GoldSim 100% BMI compliant would be a huge task but a midpoint between what the current CLI provides and BMI capabilities would be very interesting.

  What I imagine, first, lets think python is the programming language of choice. There is a GoldSim model that is saved as a GoldSim Player file. Currently that would mean that it is only possible to run and visualize outputs. A python API would need to be able to do the following:

  1. Initialize model (Retrieve all input data required to run)
  2. Get all the time step information
  3. Run one time step
  4. Retrieve a variable result.
  5. The "other" model is run for 1 time step with the output from GoldSim, and its result is saved
  6. The result is set on GoldSim as an updated value
  7. Repeat steps 3-6 until the model finishes.

  Some of this features are awfully close already through the CLI with commands like -d, -r, -starttime, etc... or they could be implemented in some hacky way. Basically it boils down to "exposing" more model parts, allow for finer time control and wrap it into a python package. The point is through this interfacing the user would not be able to create new elements or modify existing model logic, but just update already existing ones (Would this be enough to avoid licensing problems?).

   

   

  0

  Comment actions Permalink
• 

  Rick Kossik

  • July 23, 2025 21:59

  What you described has GoldSim as the "controller".  It calls the external program and runs it for one timestep (and holds things in memory for the next timestep).  The external program does not call GoldSim.  As you are aware, we can currently do this via DLLs: it has been done for years with groundwater flow models (like FEHM and Modflow) and geochem programs (like PHREEQC). The problem, of course, is that it requires you to write a "wrapper" (the DLL) around the external program so it can talk to GoldSim.  This requires programming expertise and, more importantly, access to the external program's source code. Using a tool like BMI would still require programming/scripting, but would avoid having to access the external source code (since it would know BMI). But of course both GoldSim and the external code would need to know BMI.

  By the way, note that for technical reasons the command line approach does not allow Player files to use the -d command.  This is only allowed for GoldSim files.  Having an external program access GoldSim (and change values) would require GoldSim (not the Player).  Hence, there would need to be a licensed version of GoldSim on the machine. Moreover,  the -d command modifies things at the beginning of the simulation (not dynamically). So it is simpler than what you want.

  But the command line approach is all about allowing other programs to call GoldSim.  As I noted, what you outlined above does not really require this; GoldSim could be the "controller" and simply call the external program. Basically, BMI would effectively make it easier for GoldSim to call another BMI-compliant program (without you accessing that program's source code).

   

  0

  Comment actions Permalink

Please sign in to leave a comment.