NISMOD v2.0 includes the integration framework smif and released versions for each of the sector models developed as part of the ITRC-MISTRAL project together with the configuration necessary to get the model communicating as a system-of-systems model.
The Vagrantfile defines the automated setup for a virtual machine, which will provide a reproducible development environment.
In virtual machine terminology, the virtual machine (vm for short) is sometimes called the ‘guest’ machine and the physical computer is called the ‘host’ machine.
To use the NISMOD virtual machine, first install:
If you see only 32-bit options in Virtualbox, please ensure that:
- Hardware virtualization is enabled in the BIOS
- For Intel x64: VT-x (Intel Virtualization Technology) and VT-d are both enabled
- For AMD x64: AMD SVM (Secure Virtual Machine) is enabled
- For Windows: in Windows Features, "Hyper-V platform" is disabled.
Note for Ubuntu 17.10 users: If you are experiencing the issue The box ‘bento/ubuntu-16.04’ could not be found or could not be accessed in the remote catalog. Make sure that you have the latest version of Vagrant (>v2) installed. This version is currently not in the standard package archive (PPA) but can be downloaded from the vagrant website.
Note for Windows users: Virtualbox requires that Hyper-V is disabled.
The latest release of NISMOD v2.0 is available from Github Releases.
Download the .zip archive and unzip it into a directory.
Now, goto [Running for the first time](Running for the first time)
Clone the NISMOD v2.0 repository using the command
Then on the command line, from this directory (wherever you have placed the NISMOD folder, either downloaded as a release or cloned from a git repository), run:
git checkout v2 # check out the NISMOD v2 branch
git submodule init
git submodule updateAdd your credentials for the NISMOD FTP server to provision/ftp.ini within the
NISMOD folder:
[ftp-config]
ftp_server=ceg-itrc.ncl.ac.uk
username=<username>
password=<password>
Create and configure the guest machine:
vagrant upThis will download a virtual machine image, install all the packages and software which are required to test and run NISMOD onto that virtual machine and download the data and model releases from the FTP.
Once it has run, you should be able to:
vagrant ssh # log in to the virtual machine on the command line
cd /vagrant # move to the folder that’s shared between the host and guest machines
ls # list files and folders
smif list # list available model runs
smif run energy_supply_toy # to run the energy_supply_toy model run
logout # log out of the virtual machine (or shortcut: CTRL+D)Then results are written to subfolders within the results directory – I’m working with Will on a reasonable way to view intermediate and final results at the moment.
The vagrant box hosts a local jupyter notebook server which can be accessed by
nagivating your browser to localhost:8910
First, spin up the notebook server in the background with the command:
vagrant ssh
cd /vagrant
jupyter notebook &> /dev/null &
Some sector models use a database which runs within the virtual machine and is set up when the virtual machine is provisioned.
The virtual machine exposes the database on port 6543 on the host machine, so you should be able to connect with the following details:
| key | value |
|---|---|
| Host | localhost |
| Database | vagrant |
| User | vagrant |
| Password | vagrant |
| Port | 6543 |
For example, on the command line, assuming the psql postgres command line
client is installed on the host machine, you should be able to connect with:
psql -d vagrant -h localhost -U vagrant -p 6543
This database setup is intended for testing and development only and assumes that high-numbered ports are only accessible to the local user. Strong passwords and secure login methods should be used if the host machine is expected to be accessed by multiple users.
To update NISMOD to the latest development version:
cd projects/nismod # or to wherever you’ve put the nismod folder
git checkout v2 # to make sure you’re on the v2 branch
git pull # pull changes from Github to your local machine
git submodule update # update the sector modelsThen reload and re-provision the virtual machine:
vagrant reload --provisionAll model configuration is contained in the config folder, data in the data
folder, model wrappers in the model folder, and results in the results folder
The tests in this repository are intended to test the integration of the various
NISMOD sector models with smif, the simulation modelling integration
framework. In outline, tests here should:
- validate possible system-of-systems model configurations
- run each sector model through
smifwith only scenario dependencies (not coupling with any other models)- without unexpected error
- with the expected type contract of results
- run combinations of sector models
- without unexpected error
- with the expected type contract of results
- (optionally) with regression tests against known-good modelled outputs
- v2 branch is protected against push and force-push.
- The v2 branch should be treated as live and is used for major releases only
- All development occurs on the
developbranch - New features are never added to an existing release branch
For further detail, see this article
- Create a new feature branch from the develop branch
git checkout -b feature/<feature_name> develop - Develop your feature
- Submit a pull request against the develop branch
- Merge the changes into the develop branch
-
Update the changelog under the heading Version X.Y
-
Check versions of models and data specified in
provision/config.ini -
Now, create a branch from develop e.g.
checkout -b release-x.y develop -
Tag this as a release candidate
git tag -a vx.y-rc1 -
Any bugfixes are committed to this branch and should be tagged with incremented release candidate tags e.g.
git tag -a vx.y-rc2 -
Once the release candidate is stable, submit a pull request to the
v2branch -
Merge the pull request and tag
git tag -a vx.y.0
- Create a branch from master
git checkout -b hotfix/<bug_name> master - Fix the bug by committing to the branch
- Submit a pull request to master and tag the fix
git tag -a vx.y.zincrementing the minorzdigit