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

  1. Prepare a valid and running XML model file including meaningful title and description, e.g. using your local Morpheus GUI.
  2. 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.
Screenshot of the model repository webpage on GitLab with the ‘Sign in / Register’ button on the top right highlighted
Sign in or register on GitLab.
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).
  1. 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 and then on ‘Select’ under your name.
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 private namespace for the 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.

To do this, click on ‘Fork’ as described above. Instead of ‘Select’, ‘Go to project’ appears under your name. Follow this link, 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.

  1. 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.
  1. 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!
  1. 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.
  1. Optional: You may add an index.md file for an extended explanation of your model, similar to the built-in models.

  2. When you are finished adding files and folders, click on ‘Create merge request’ in the top right corner. 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 ‘Create merge request’ button highlighted
Create a 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.
  1. 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.
Previous
Next