Seitenhierarchie
Zum Ende der Metadaten springen
Zum Anfang der Metadaten

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

Prerequisites

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).

1Install .NET Core for your Systemhttps://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/

  1. Go to https://www.microsoft.com/net/core
  2. If you're running Windows, select "Visual Studio 2017".
  3. Or (maybe): https://www.microsoft.com/net/download/core
  4. On Mac, follow the "brew" installation guide
  5. Open a new Terminal (don’t use the one from the Homebrew installation)
  6. Execute each command as shown on the homepage
  7. Close the Terminal
2Install Mono
(only on MacOS and Linux!)
http://www.mono-project.com/download/Mono is required to run the ReSharper sidecar in Project Rider IDE 
3Install MSBuild 2015 Toolkit (only on Windows)https://www.microsoft.com/en-us/download/details.aspx?id=48159  
4Install Jetbrains Rider IDEhttps://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.

  1. Go to https://www.jetbrains.com/rider/download/
  2. Download the edition for your platform
  3. Install the program
  4. Start Rider

(if Rider fails to start, you probably forgot to install Mono – see step 2)

5Install the MARS Cloud 2.0 Plugin for Rider

Instructions: https://gitlab.informatik.haw-hamburg.de/mars/mars-rider-plugin

Download:https://gitlab.informatik.haw-hamburg.de/mars/mars-rider-plugin/raw/master/mars-rider-plugin.zip

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)
  1. Download the ZIP file by using the download link to the left
  2. Start Rider, if not already open.
  3. On the welcome screen, click "Configure" → "Plugins". A list with all plugins will show up.
  4. Click "Install plugin from disk", browse to the downloaded file and select it.
  5. You now should have an option "New MARS model" available on the Rider welcome screen!
6Install GIT Client
(only if you want to check out example models from our Gitlab) 
https://www.sourcetreeapp.com (free, but requires registration)
OR
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-CoreThe LIFE-Core package contains the LIFE runtime and everything you need to run a simulation
LIFE-ComponentsThe 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.
Hint for updates to the packages!

When updating any of the two packages you should update the other one too! Make sure the versions match, by that you'll have guaranteed compatibility.

There is always a stable version (i.e. LIFE-Components.2.1.1) and a variety of unstable versions (if you feel adventurous (Zwinkern) ), which have an "-unstable-" tag in their name.

Setting Up a HelloWorld-Model

 

Tip

All example models are available from an Example Repository. You may check it out here: https://gitlab.informatik.haw-hamburg.de/mars/model-examples

 

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 (Lächeln) Let's start (click on the images to enlarge!):

  1. Start JetBrains Rider and select "New MARS Model" from the Menu:
  2. Provide a name and folder for your model and click Ok:
  3. 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:
  4. Unfold the "Models" folder and double click the "DefaultLayer.cs" file. Your screen should look like this:
  5. 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".
  6.  You should get a file created like so:
  7. 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:
  8. Now let's add some code! In the Tick() method of your HelloWorldAgent add this line:

    Console.WriteLine("Hello World!");

    It should now look like so:
     

  9. Next up you need to instantiate your Agent. To do so add this code in your DefaultLayer InitLayer() method:

    var helloWorldAgent = new HelloWorldAgent();
    registerAgentHandle(this, helloWorldAgent);

    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

  1. Publication of Model to MARS Cloud

    1. Open a Terminal (either in Rider or natively on your OS and navigate to the LIFEStarter folder of your project

    2. Run 'dotnet publish -c Release -o out' from within the LIFEStarter folder (the name MUST be "out")

    3. Zip the resulting 'out' folder and rename it to 'HelloWorldModel.zip'

  2. Open https://mars.haw-hamburg.de in your browser (tested with Safari, Chrome and Firefox). You'll see this: 
  3. 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! 
  4. 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! 
     
  5. 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).
  6. 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:

  7. Click Upload and wait until the State of the Import changes to “Finished” in the Imports table:
  8. 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:
  9. 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:
  10. 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

  • Keine Stichwörter

Kommentar

  1. Very nice plugin and tutorial, worked right away in way under 5 minutes.