GroIMP wiki

a part of grogra.de

User Tools

Site Tools

Trace:
tutorials:interfaces:tour

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
tutorials:interfaces:tour [2025/06/04 09:28] – [Headless] tim2tutorials:interfaces:tour [2025/06/04 15:03] (current) – [Minimal required preparations] tim2
Line 1: Line 1:
 ====== A tour through GroIMP interfaces ====== ====== A tour through GroIMP interfaces ======
  
 +In the following, we will use the same model in different GroIMP user interfaces.
  
 +| {{page>user-guide:additional_interfaces}} |
  
 ===== The model ===== ===== The model =====
  
-To highlight the flow of simulations in the different interfaces we use a simple model of a plant that can grow apically and with a second function split one bud into two of half the strength. +To highlight the flow of simulations across different interfaces, we use a simple model of a plant that can grow apically and, with a second function, split one bud into two, each with half the strength. 
-The idea is to see how different indicators change over 10 growth steps depending on the time the buds split.+The idea is to observe how different indicators change over 10 growth stages, depending on when the buds split.
  
 {{ :tutorials:interfaces:split_plant.png?400 |}} {{ :tutorials:interfaces:split_plant.png?400 |}}
Line 97: Line 99:
 </code> </code>
  
 +
 +{{ :tutorials:interfaces:cut.gsz |}}
 ===== Headless ===== ===== Headless =====
  
-Now that we have a function that only requires us to press one button to get all steps, we are already closer to run it completely automatically.+Now that we have a function that only requires us to press one button to get all steps, we are already closer to run it completely automatically. The  simplistic way to do so is using the headless mode.  
 + 
 + 
 + 
 +| {{page>user-guide:additional_interfaces:headless}} | 
 + 
  
-The  simplistic way to do so is using the headless mode. In this mode GroIMP starts executes a model or a command and closes again after it was done.  This way we can execute our model with only one system call. +In this mode, GroIMP starts executing a model or a command and closes again after it is done.  This way we can execute our model with only one system call. 
-For that to work we have to take care of three things, first that GroIMP knows what to do with the model once its opened, then that the model closes it self at the end and finally that we can get the data out of it.+For that to work, we have to take care of three things, first GroIMP knows what to do with the model once it's opened, then the model closes itself at the end and finally, we can get the data out of it.
  
 === startup === === startup ===
Line 124: Line 134:
 === run(Object info) === === run(Object info) ===
  
-In this run function we must describe everything that is suppose to happen in the simulation, including closing the software.+In this run function, we must describe everything that is supposed to happen in the simulation, including closing the software.
  
 <code java> <code java>
Line 137: Line 147:
  
 Even though GroIMP ran the simulation to completion we did not define any output for our data. Even though GroIMP ran the simulation to completion we did not define any output for our data.
-There are several ways to do this using java, but for this tutorial we are going with one of the simplest. +There are several ways to do this using Java, but for this tutorial, we are going with one of the simplest. 
-We are exporting the dataset we anyway already created to a csv file in and save this in the same directory as the project.+We are exporting the dataset we already created to a CSV file and saving it in the same directory as the project.
  
 <code java> <code java>
Line 154: Line 164:
 === Parameters === === Parameters ===
  
-GroIMP gives us the ability to forward custom parameter form command line, in general these are model independent but in headless this is no issue since we have to start GroIMP for every model any way.+GroIMP gives us the ability to forward custom parameters from the command line, in general, these are model-independent but in headless this is no issue since we have to start GroIMP for every model anyway.
  
 The usage of this is quite simple, every value we add with -X<key>=value will be added to Main.getProperty(<key>). So in our case: if we put -Xsp=6 to the command line we can use: The usage of this is quite simple, every value we add with -X<key>=value will be added to Main.getProperty(<key>). So in our case: if we put -Xsp=6 to the command line we can use:
Line 168: Line 178:
 </code> </code>
  
 +And to make the csv a bit clearer:
 +
 +<code java>
 +protected void init ()[
 + Axiom ==> A(1);
 + {time=0;
 + dataset("data").clear();
 + dataset("data").addRow()
 +  .setText(0,"time")
 +  .setText(2,"sumFlength")
 +  .setText(3,"meanFlength")
 +  .setText(4,"countLeaf")
 +  .setText(5,"sumLeafgetArea")
 +  .setText(6,"meanLeaf getArea");
 + }
 +]
 +</code>
 +
 +{{ :tutorials:interfaces:cut_headless.gsz |}}
  
 This setup would now allow us to integrate the model into pipelines, e.g. an R script: This setup would now allow us to integrate the model into pipelines, e.g. an R script:
Line 176: Line 205:
 data <- read.csv("data.csv", header = TRUE, sep = ",") data <- read.csv("data.csv", header = TRUE, sep = ",")
 </code> </code>
 +
  
  
 ===== HTTP ===== ===== HTTP =====
  
 +With a bit of scripting, we could use the headless mode also for orchestration or automation, yet we would start and stop GroIMP every time which of course takes a bit of time. To avoid this, and to also allow us to execute on a remote server or in parallel on a GroIMP instance we can use the HTTP-Server
  
-<code>+| {{page>user-guide:additional_interfaces:http}} | 
 + 
 + 
 +==== Minimal required preparations ==== 
 + 
 + 
 +If we want to run our model through the HTTP-server we have to make three small changes first: 
 + 
 +__1. Change the condition in the startup function, to make sure it runs if the model was opened through the http server.__ 
 + 
 +To do so we test if we have an HTTPResponse object, this object is created when the model is opened through the server and holds the request from the client and the ability to respond.  
 + 
 +<code java> 
 +protected void startup(){ 
 + super.startup(); 
 + //check if we could get a HTTPResponse Object 
 + if( de.grogra.imp.net.HttpResponse.get(workbench())!=null){ 
 +  runLater(null); 
 + } 
 +} 
 + 
 +</code> 
 + 
 +__2. Make sure that we are not looking for the headless parameter anymore (its not there).__ 
 + 
 +we have to make sure we removed  the line 'splitPoint = Integer.valueOf (Main.getProperty("sp"));' since it would otherwise crash. 
 + 
 +__3. We have to stop stopping GroIMP __ 
 + 
 +In the headless mode, we finished the run(Object info) function with 'System.exit(0)' to close GroIMP, in the HTTP server we do not want to do that. Therefore we have to remove this line. 
 + 
 + 
 +==== First execution ==== 
 + 
 +To open a model through the HTTPServer we have to provide the path to the gsz file, this path is relative to a given "root directory".  
 +We can set this base directory in the GroIMP preferences under "HTTP > open Project", an easy solution is to just set this to the directory of your project. 
 + 
 +After we define our root directory we can start the HTTP server through the main menu through "Net > Open HTTP Server". In most cases we do not care about the port number, if you want/need to change it you can do so without any issues just keep chaining it in the examples below as well. 
 + 
 +If the server is running we can visit [[http://localhost:58080]] to see the installed plugins and possible HTTP commands. 
 + 
 +The command we are interested in is open (and yes is the only one ;-) ). To open we have to provide the path to the model in the given style: 
 + 
 +<code url> 
 +http://localhost:58080/open?path/to/your/model.gsz 
 +</code> 
 +So if you use the project directory as a root directory of the http server, the call would be: 
 + 
 +[[http://localhost:58080/open?http_model.gsz]] 
 + 
 + 
 +If we run this, its open and runs the model and then stops. The model stays open and the request in the  browser keeps loading because the browser never gets any feedback. 
 + 
 + 
 +To give the browser feedback we need to use the send function from the HttpResponse object at the end of our run function: 
 + 
 +<code java> 
 +de.grogra.imp.net.HttpResponse.get(workbench()).send(false); 
 +</code> 
 + 
 +The false value in the function defines that we do not intend to send information back. Therefore this will only give us "The content has not been set." as a message in the browser. 
 + 
 +==== LazyHTTP ==== 
 + 
 + 
 +To send content back and to also receive parameters we could now work with the HttpResponse object, but to make this a bit easier we will use the [[https://plugins.grogra.de/#de.grogra.imp.net.lazyhttp | LazyHTTP plugin]] which can be installed through the plugin manager: 
 + 
 +<code java> 
 +import de.grogra.imp.net.lazyhttp.*; 
 + 
 +... 
 + 
 +protected void startup(){ 
 + super.startup(); 
 + CsvWrapper resp = CsvWrapper.get(workbench()); 
 + if(resp!=null){ 
 +  runLater(resp); 
 + } 
 +} 
 + 
 +public void run(Object info){ 
 + CsvWrapper resp = (CsvWrapper)info; 
 + test(); 
 + resp.append(dataset("data")); 
 + resp.send(); 
 + closeWorkbench(); //close the project at the end  
 +} 
 + 
 +... 
 + 
 +</code> 
 + 
 + 
 +Additionally, we closed the workbench at the end of our execution because we do not need it anymore now since we got the data in the browser.  
 + 
 + 
 +=== Parameters === 
 + 
 +Using the LazyHttp library we can also parse given values from the HTTP request: 
 + 
 +<code java> 
 +public void run(Object info){ 
 + CsvWrapper resp = (CsvWrapper)info; 
 + splitPoint = resp.get("sp",5); //get the value of sp or the default value of 5 
 + ... 
 +</code> 
 + 
 +To give a parameter like this to the HTTP server we add '&sp=3' to our URL: 
 + 
 +[[http://localhost:58080/open?l_model.gsz&sp=3]] 
 + 
 + 
 +=== Integration in R === 
 + 
 + 
 + 
 +<code r>
 groIMP.HTTP <- function(path, param, url="http://localhost:58080"){ groIMP.HTTP <- function(path, param, url="http://localhost:58080"){
   parameters=""   parameters=""
Line 197: Line 344:
 } }
  
-df <- groIMP.CSV("Dokumente/ssc25/talks/GroLink/exampels/http/cut_grow.gsz",list(pre=1, initialLength=10.3))+df <- groIMP.CSV("l_http_model.gsz",list(sp=3))
  
 </code> </code>
  
  
-{{ :tutorials:interfaces:cut_grow.gsz |}}+ 
 +{{ :tutorials:interfaces:lazy_http_cut.gsz |}}
 ===== API ===== ===== API =====
  
 +If you require more interaction with the model during the simulation or want to have direct access to what happens we can use the GroIMP API.
 +
 +| {{page>user-guide:additional_interfaces:api}} |
 +
 +
 +To start the API is a bit more complicated than the HTTP-server, an instruction can be found here:
 +[[tutorials:startup-api|Start GroIMP in API mode]].
 +
 +
 +The API works without any changes in the GroIMP model, by using similar functionalities than the GUI, we can run RGG functions, execute XL queries, trigger import or export or view datasets.
 +
 +The full list of commands can be found here:
 +https://gitlab.com/grogra/groimp-plugins/api/-/blob/master/commands.md 
 +
 +And a browser based tutorial [[tutorials:getting-started-with-grolink-and-http|here]]
 +
 +Additionally GroIMP provides two libraries to connect to the API:
 +
 + - [[https://gitlab.com/grogra/groimp-utils/rapilibrary | GroR]]  ([[tutorials:getting-started-with-grolink-and-gror|Getting started with GroLink and GroR]])
 +
 + - [[https://gitlab.com/grogra/groimp-utils/pythonapilibrary | GroPy]] ([[tutorials:getting-started-with-grolink-and-gropy|Getting started with GroLink and GroPy]])
 +
 +
 +===== Application on our model =====
 +
 +<code>
 +library(dplyr)
 +library(httr2)
 +library(GroR)
 +
 +
 +wb<-GroLink.open("http://localhost:58081/api",content = readBin("/home/tim/Dokumente/ssc25/talks/GroLink/exampels/tut/cut.gsz", "raw", 10e6))
 +
 +WBRef.runRGGFunction(wb,"test")
 +data<-WBRef.getDataset(wb,"data")
 +df <- read.table(text = data, sep =",", header = TRUE, stringsAsFactors = FALSE)
 +
 +WBRef.runXLQuery(wb,"Model.INSTANCE.splitPoint:=1;")
 +WBRef.runRGGFunction(wb,"test")
 +data<-WBRef.getDataset(wb,"data")
 +df2 <- read.table(text = data, sep =",", header = TRUE, stringsAsFactors = FALSE)
 +
 +plot(df$sumLeafgetArea)
 +plot(df2$sumLeafgetArea)
 +</code>
tutorials/interfaces/tour.1749022110.txt.gz · Last modified: 2025/06/04 09:28 by tim2