This section is meant to get you started with model development. It covers the basic parts including setup of the development environment and the creation of a simple Hello World model.
For more advanced topics please refer to one of the more specific and in depth topics in the LIFE Documentation.
Terms & Wording
Throughout these guides we are going to use a lot of terms and maybe a wording which has evolved throughout the past years of working on MARS. In order to make clear which term means what, there's a Glossar provided. Find it here: Glossary
In order to implement a model with C# you need to install a bit of software first. The MARS Team decided to use the Jetbrains Rider IDE for a unified model development across all three major desktop platforms (Windows, macOS, Linux).
|1||Install .NET Core for your System||https://www.microsoft.com/net/core|
This is the SDK to develop cross-platform C# applications. Further documentation can be found here: https://docs.microsoft.com/en-us/dotnet/
|2||Install Mono |
(only on MacOS and Linux!)
|http://www.mono-project.com/download/||Mono is required to run the ReSharper sidecar in Project Rider IDE|
|3||Install MSBuild 2015 Toolkit (only on Windows)||https://www.microsoft.com/en-us/download/details.aspx?id=48159|
|4||Install Jetbrains Rider IDE||https://www.jetbrains.com/rider/download/|
The Jetbrains IDE for C# application development. If you've ever worked with IntelliJ IDEA for Java development you'll feel right at home.
(if Rider fails to start, you probably forgot to install Mono – see step 2)
|5||Install the MARS Cloud 2.0 Plugin for Rider||A MARS plugin for Jetbrains Rider. It allows you to create LIFE models and add layers and agents with a few clicks. Also there's a work-in-progress integration with the MARS Cloud, which allows you to directly interact with cloud features without leaving the IDE (i.e. Model Upload)|
|6||Install GIT Client|
(only if you want to check out example models from our Gitlab)
|https://www.sourcetreeapp.com (free, but requires registration)|
https://www.gitkraken.com (more fancy looking)
A Word About C#
The reasons why MARS LIFE has been built with C# instead of for instance Java or another language are manifold and would exceed the scope of this text. However, if you've already done some Java programming you will quickly pick up C# as the base syntax is almost identical. There are some additional features like delegates or the LINQ API that work a bit different. For that reason, you might enjoy this quick overview of the C# language:https://docs.microsoft.com/en-us/dotnet/articles/csharp/index.
In .NET libraries are called DLLs and are packaged into NuGet packages. This is the equivalent to Java's JAR files and Maven packages. For MARS LIFE 2.1 you only need two packages:
|LIFE-Core||The LIFE-Core package contains the LIFE runtime and everything you need to run a simulation|
|LIFE-Components||The LIFE-Components package contains all of the provided pre-implemented components like GridEnvironment, GeoGridEnvironment, various layer types, some basic agent implementations including Movement for GPS etc.. Reference this package if you want to make use of the provided LIFE libraries.|
Setting Up a HelloWorld-Model
Now that you're all set, let's start doing something with MARS LIFE. In this section we'll set up a simple HelloWorld model. It incorporates only a single Layer and a HelloWorldAgent, whose sole meaning of life it is, to print "HelloWorld" on the command line and then die Let's start (click on the images to enlarge!):
- Start JetBrains Rider and select "New MARS Model" from the Menu:
- Provide a name and folder for your model and click Ok:
- The folder and the model structure will be created. Also the MARS LIFE dependencies will be added to the project. At first you'll see a rather empty screen. Click on the "Solution Explorer" Panel on the top left side to expand the project structure view:
- Unfold the "Models" folder and double click the "DefaultLayer.cs" file. Your screen should look like this:
- Right click on the Default Layer project in the Solution Explorer and select "New"→"Agent". Type in "HelloWorldAgent" in the name field and leave the rest at the defaults in the following dialogue. Then hit "Ok".
- You should get a file created like so:
- Hit CMD+Alt+Enter on macOS or Ctrl+Alt+Enter on Windows to apply proper formatting to the generated code. The result should look like so:
Now let's add some code! In the Tick() method of your HelloWorldAgent add this line:
It should now look like so:
Next up you need to instantiate your Agent. To do so add this code in your DefaultLayer InitLayer() method:
Line 1 instantiates an agent of type HelloWorldAgent. Line 2 calls the registerAgentHandle method, which is provided in the InitLayer method and registers the agent instance with the MARS LIFE execution runtime. The first parameter is the reference to the layer itself, since MARS LIFE needs to know on which layer this agent is located. The result should look like so:
Congratulations! Your first model is now ready to be deployed to the MARS Cloud!
Deploying the HelloWorld Model to the MARS Cloud
Publication of Model to MARS Cloud
Open a Terminal (either in Rider or natively on your OS and navigate to the LIFEStarter folder of your project
Run 'dotnet publish -c Release -o out' from within the LIFEStarter folder (the name MUST be "out")
Zip the resulting 'out' folder and rename it to 'HelloWorldModel.zip'
- Open https://mars.haw-hamburg.de in your browser (tested with Safari, Chrome and Firefox). You'll see this:
- You'll first have to register, So do that by clicking on the Sign Up button and fill out the form:
Note: Currently your account has to be verified by a MARS member.The MARS Group will receive an e-mail, so that it may verify and unlock your account. You may then proceed with this tutorial!
- Once logged in, you see the dashboard view. Navigate to the "Select a Project" menu item and hit the Create button:
After choosing a name and optionally providing a description for your new project, you now should see this:
Select your project by ticking the little blue box in the upper left corner!
- Now switch to the "Imports" menu item:
In this view you will upload all your model assets including the Model's code ZIP file and all required data files (for the HelloWorld Model it will only be the ZIP file).
- Select the file “HelloWorldModel.zip” from the LIFEStarter folder inside the code folder and drag and drop it onto the file chooser icon (alternatively click the icon and select the ZIP file from your file system). The result should look like this:
Now select the Type from the dropdown box to be 'Model'. You need to provide the type as the MARS Cloud cannot tell yet what your ZIP contains with 100% certainty:
- Click Upload and wait until the State of the Import changes to “Finished” in the Imports table:
- Next create a Scenario by changing to the "Select a Scenario" menu item and clicking the "Create" button:
Fill the form and hit "Create". Then select your created scenario by ticking the blue box again:
- Now switch to the "Mapping" menu item:
You see that it asks your for an InstanceCount for your HelloWorld agents, this is a feature which only applies if you used the AgentManager. For now simply key in any number you want, as it won't have any effect (we have a single hardcoded agent)
In the "General" tab you set up the wallclock start and end date and time for your scenario and also provide information about the DeltaT you want each tick to represent. For now select whatever you feel comfortable with. In more advanced models this information can be used in layers to adjust the agent's behavior (i.e. in movements).
When done, click "Apply". The view should look like this:
- Now switch to the "Runs" menu item and click on the "Create" button for new simulation plans:
You get this:
Now click the Run/Play button! You will see that a new run is created in the panel below:
Wait for a moment and then try to click on the small icon for the details panel:
A modal will open and show you the output of your simulation run like so:
Note: The 'Hello World' output being written to the log! That's what you wrote in the agent's Tick() method.
Congratulations! You just ran your first model in the MARS Cloud!
Where to go from here
To get more details about the MARS Rider Plugin take a look at the extended documentation available here: Working with MARS Rider Plugin
To continue reading about more advanced and in depth LIFE topics and components, check out the full LIFE documenation: LIFE Documentation