Submit Model

‘How can I submit a Morpheus model?’

All Morpheus models including their complete version history are stored in a Git repository: gitlab.com/morpheus.lab/model-repo (from this Git repository all model pages you can find on this website are automatically generated).

Model Submission via GitLab

Models can be submitted in eight simple steps. The complete model upload procedure is shown in this short video:

Below you’ll find a more detailed, illustrated walkthrough explaining each step.

Step-by-step Guide

Prepare a valid and running XML model file including meaningful title and description, e.g. using your local Morpheus GUI.
A (free) user account at GitLab.com is needed (which hosts Morpheus' open source repository). You can also sign in using an existing GitHub/Google/Twitter account. This account will also allow you later to track and modify your model. You need to be logged in at GitLab via the ‘Sign in / Register’ button on the top right to proceed to the next step.

When registering, please note that the name (and email address) you provide in your GitLab profile will be automatically listed as the model’s ‘contributor’ by default. (However, you may add additional contributors or make corrections later).

Now fork the repo, i.e. save a copy of the repository under your GitLab user account, by clicking on ‘Fork’ at gitlab.com/morpheus.lab/model-repo. On the next page ‘Select a name space’, which is usually your name and set the visibility level to ‘Public’. Finish by clicking on ‘Fork project’.

Screenshot of the model repository webpage on GitLab with the "Fork" button highlighted — Fork the Morpheus model repository.

Screenshot of the fork site on GitLab with the ‘Select’ button highlighted — Select your namespace for the public fork.

If you have previously submitted a model but there is no longer one in the review process, please delete your fork first and create a new one so that your copy of the repo is up to date. Otherwise you will get this error message:

Screenshot of the fork repository settings site on GitLab with an error in a red box at the top reading ‘An error occurred while forking the project. Please try again.’ — ‘An error occurred while forking the project’ because you already have an old fork that needs to be deleted first.

To remove your old fork, click on ‘Menu’ at the top. Now either use the search to find your old ‘model-repo’ fork or go to ‘Your projects’ and select the fork from the list there.

Screenshot of the expanded GitLab ‘Menu’ at the top menu bar. — Navigate to your old ‘model-repo’ fork.

Then go to ‘Settings’ → ‘General’ in the navigation on the left, scroll all the way down to ‘Advanced’, click on ‘Expand’ and then on ‘Delete project’. Follow the instructions to finally delete your fork.

Screenshot of the fork repository settings site on GitLab with the ‘Delete’ button highlighted — Delete your old fork. Make sure you have no more unpublished models in open merge requests.

Now go back to the Morpheus Model Repository and fork as described above.

Create a new branch by selecting ‘+’ → ‘New branch’, give the branch a name such as ‘add-model’, keep the option ‘Create from’ set to master and finish with ‘Create branch’.

Screenshot of the model repository webpage on GitLab with the ‘+’ and ‘New branch’ buttons highlighted — Open the ‘New branch’ form.

Screenshot of the model repository webpage on GitLab with the ‘Branch name’ field and the ‘Create branch’ button highlighted — Name and create the branch.

Now browse to the model category and a topic area to which you want to contribute (you can also suggest a new one if you think that a suitable topic is still missing) and create a new directory for your model by clicking ‘+’ → ‘New directory’.

Screenshot of the model repository webpage on GitLab with the ‘+’ and ‘New directory’ buttons highlighted — Open the ‘New directory’ form.

Screenshot of the model repository webpage on GitLab with the ‘Directory name’ field and the ‘Create directory’ button highlighted — Name and create the new directory.

Choose a concise folder name. This will be displayed in the model list in the sidebar and is the first thing other Morpheus users will see of your model when they browse the repository on the Morpheus website!

Click the ‘+’ button again and then ‘New file’ to paste your model from the clipboard or ‘Upload file’ to choose a XML file on your computer. This will open a simple form. Fill in/upload the model and click ‘Commit changes’ or ‘Upload file’. You may but do not need to add text in the comments field (‘commit message’).

Screenshot of the model repository webpage on GitLab with the ‘+’ and ‘Upload file’ buttons highlighted — Open the ‘Upload file’ form.

Screenshot of the model repository webpage on GitLab with the drag & drop file field and the ‘Upload file’ button highlighted — Choose and upload the model file.

In the same way, you can upload additional files that belong to the model, such as input data needed for the simulation or results in the form of images, videos etc.

Optional: You may add an index.md file for an extended explanation of your model, similar to the built-in models.
When you are finished adding files and folders, click on ‘Create merge request’ in the top right corner.

Screenshot of the model repository webpage on GitLab with the ‘Create merge request’ button highlighted — Create a merge request.

Go to ‘Change branches’ and switch the target project in the right column from your fork to the project ‘morpheus.lab/model-repo’. Keep the target branch to the right of it as it is, set to ‘master’. When finished, click on ‘Compare branches and continue’.

Screenshot of GitLab's ‘New merge request’ page with the ‘Change branches’ link highlighted — Change branches.

Screenshot of GitLab's ‘Source’ and ‘Target branch’ settings page for merge requests with the project ‘morpheus.lab/model-repo’ and the button ‘Compare branches and continue’ highlighted — Switch target project.

If you like, change the title and description of your submission, check the box ‘Contribution’ (please keep all ‘Merge options’ checked) and submit your model files by clicking on ‘Submit merge request’.

Screenshot of the model repository webpage on GitLab with the ‘Contribution’ box checked and the ‘Submit merge request’ button highlighted — Check the ‘Contribution’ box and finally submit the merge request.

Important: Do not forget to tick the box next to ‘Contribution: Allow commits from members who can merge to the target branch’. This allows the maintainers to make adjustments directly in your branch together with you during the review process.

Explanation for the ‘Merge options’:

‘Delete source branch when merge request is accepted’: This option only means that after the successful publication of your model on the website, the system automatically cleans up by deleting your old branch. This old branch, however, represents only a copy of your submission at this point, since your model is now also located in the master branch and hence published on the Morpheus website. So no information is lost here on deletion.
‘Squash commits when merge request is accepted’: This means that all small adjustments made by you and the curators during the review process are combined into a single change in the version history when your model is accepted (merged). Your initial commit (the first edit made when you created your new model), including your name, will always remain visible to all in the repository’s history.

Now the review process starts. In the meantime you can make further changes to your model and, if created, to the index.md description page at any time.

Don’t forget to work within your newly created branch for the new model so that your changes are mirrored in the open merge request.

Screenshot of the model repository webpage on GitLab with the ‘Switch branch/tag’ drop-down menu and the ‘add model’ branch highlighted — Make sure that your recently created branch is selected before making any further changes to your model.

Last updated on Tue, 30 Nov 2021