A Frontend application with Desktop and Web Based GUI for creating a simulation model to assist decision making and education in evaluating animal disease incursions. ADSM is an upgrade of the NAADSM application.
Project Owner - Missy Schoenbaum, USDA:APHIS:VS:CEAH Modeling Team contact melissa.schoenbaum@usda.gov. Training materials are provided at http://navadmc.github.io/ADSM/
This repo is the primary repo for the ADSM project and houses the main Frontend that users will be interacting with.
It creates scenarios by storing their parameters in a SQLite file and displays results after running a simulation.
A more detailed breakdown of this application will follow.
ADSM can be installed on either x86-64 Windows 7 - 10 or x86-64 Debian based Linux Systems (Ubuntu preferred) running under the English Locale (language). Other Locales may work, but have not been tested and are not supported at this time.
There is a Beta and Release channel available for installation.
You can find the latest Release here: https://github.com/NAVADMC/ADSM/releases/latest
NOTE: v3.3.7.0 was the last version that had a Linux Build compiled. For now, Linux users should follow instructions for Installing ADSM For Development.
You can find the latest Release here: https://github.com/NAVADMC/ADSM/releases/latest
If you selected "No" to specifying a Workspace location and the Workspace was automatically created in the ADSM folder, your installation is considered "Portable".
This means that you can move the entire ADSM folder from one computer to another and have all your data and settings move around with it.
It is NOT suggested to attempt to run the ADSM program from a portable drive as there may be performance issues.
If you put your installation on a portable drive to do work on another computer, copy the installation onto the new computer's internal Hard Drive before doing your work.
You can change where ADSM looks for the Workspace Folder at any time by opening the Scenario Browser in the right nav panel of the program and clicking "(change)" next to the Current Workspace path.
Doing this will prompt you to close the program and launch again going through the initial setup as described during the installation process.
NOTE: v3.3.7.0 was the last version that had a Linux Build compiled. For now, Linux users should follow instructions for Installing ADSM For Development.
You can find the latest Pre-release on the Releases page: https://github.com/NAVADMC/ADSM/releases
WARNING: If you have a Release installation on your computer, the Beta install MAY overwrite your scenarios from the Release version if you point both installations to the same Workspace Folder.
If ADSM is automatically putting the Workspace Folder in the ADSM folder, there will be no conflict.
NOTE: ADSM was developed with the intention to move it towards a Cloud Hosted environment. It is setup to run as a webserver already. HOWEVER, it is not multi-user friendly yet so should not be setup in this way except for demo purposes.
Installing on a Server does not required a compiled frontend, only a compiled CEngine. These steps will be similar to setting up a development environment in that the Server will serve the program directly from a Python Virtual Environment.
ADSM has a bundled update program which can handle updating and fixing corrupted installations of the program.
This update process works in both Production and Beta releases.
You can update ADSM from within the Frontend GUI.
You can run the Update Client manually outside of the ADSM application.
This can be useful if you need to run the update process with elevated rights as an Admin.
There are two main applications to the ADSM project and three support applications provided by Newline Technical Innovations.
ADSM-CEngine ( https://github.com/NAVADMC/ADSM-CEngine ) is the C code that runs the stochastic modeling simulation.
Scenario parameters are sent to the CEngine via a Scenario SQLite file.
Results are written back via stdout, and supplemental result files are written to a directory alongside the SQLite scenario file.
ADSM ( https://github.com/NAVADMC/ADSM ) is the main Frontend GUI that users will be interacting with. It creates scenarios by storing their parameters in a SQLite file and displays results after running a simulation.
A more detailed breakdown of this application will follow.
Django-ProductionServer ( https://github.com/BryanHurst/django-productionserver ) is a cross-platform local application server utilizing CherryPy and Nginx for hosting Django projects locally on a desktop environment.
Viewer is a distribution of Chromium customized by Newline Technical Innovations for displaying web based applications hosted locally.
NPU, or Newline Program Updater, is an application created by Newline Technical Innovations with an endpoint server hosted by Newline for getting updates to the installed ADSM application. NPU will also detect and attempt to repair a bad/corrupt installation.
The ADSM Frontend Application is written in Python and utilizes a modified copy of the Django Web Framework.
You will want to read up on the Django docs and their very useful tutorial.
As it is a Python project, the ADSM Frontend does NOT need to be compiled for testing or deployment on a web server.
The compile process for the Frontend application is solely to create a distributable that can be installed and run standalone on an End User's system.
Windows is currently the primary target of distribution compilation.
However, you can run the ADSM Frontend on any system by setting up a Python Virtual Environment as will be detailed below in "Installing ADSM For Development".
The following is a short description of the Django "apps" of the ADSM Frontend Application.
The base app which holds the settings and site wide static files.
There are a few things to note about the settings of this project.
Application used to store user settings and track simulation progress. This is mostly behind the scenes data storage.
These are the blank state databases for a scenario (blanks.db) and the ADSMSettings app (settings.db).
Blank state databases are required to help the program startup faster so the database doesn't have to be created from the schema each time.
The application which runs simulations and parses results returned from the CEngine.
The parsed results are written to the scenario db under the Results app and allows for displaying results graphically.
Where sample scenarios and populations are stored for distribution with the application.
The main portion of the ADSM Frontend.
This is where the user will spend most of their time creating a scenario and inputting parameters.
As described above.
This folder is where the ADSM-CEngine and its dependencies will be placed. The results app looks here for the simulation executable.
This folder is not part of the repo, but will be generated when you compile the Frontend for distribution.
Some useful scripts used during development either for discovery, testing, or benchmarking.
These are not used in the program at all.
This folder is not part of the repo, but will be generated when you create the installer for the compiled Frontend.
This folder is not part of the repo, but will be created when setting up a development environment.
This is where node packages specific to the ADSM project will be installed.
This folder is not part of the repo, but may be generated when doing production testing.
When you install ADSM for Development, you can run the Frontend locally without the need for compiling. This is useful for testing and web hosting.
Supported Operating Systems:
ld_args.append('/MANIFESTFILE:' + temp_manifest)
add ld_args.append('/MANIFEST')
at the same indentation level.DRIVE:\\path\to\python34\python -m venv DRIVE:\\path\to\projects\adsm_venv
DRIVE:\\path\to\projects\adsm_venv\Scripts\activate.bat
python
and pip
commands are located in the virtual environment created above by doing where python
and where pip
.
DRIVE:\\path\to\projects\adsm_venv\Scripts\python.exe
or DRIVE:\\path\to\projects\adsm_venv\Scripts\pip.exe
cd DRIVE:\\path\to\projects
git clone git@github.com:NAVADMC/ADSM.git
cd adsm
pip install -r Requirements.txt
pip install -r Requirements-Windows.txt
pip install DRIVE:\\path\to\downloads\wheelname
npm install
DRIVE:\\path\to\projects\adsm_venv\Scripts\easy_install.exe DRIVE:\\path\to\downloads\pywin32-219.win-amd64-py3.4.exe
pip install hg+https://bitbucket.org/BryanHurst/cx_freeze
pip install cx_freeze==4.3.4
WARNING: You cannot use the Python which is shipped with the OS or that is installed via aptitude due to broken links to requirements that cx_freeze will need for compiling a distributable.
sudo su
(or be logged in as root)apt-get install git mercurial build-essential python3-dev
apt-get build-dep python3-matplotlib python3-scipy
curl -sL https://deb.nodesource.com/setup_4.x | bash -
apt-get install -y nodejs
curl https://bootstrap.pypa.io/get-pip.py | python3
apt-get install zlib1g-dev libbz2-dev libncurses5-dev libreadline6-dev libsqlite3-dev libssl-dev libgdbm-dev liblzma-dev tk8.5-dev
exit
(to exit sudo if you want to build ADSM as a lesser User)cd
wget https://www.python.org/ftp/python/3.4.3/Python-3.4.3.tgz
tar zxvf Python-3.4.3.tgz
rm Python-3.4.3.tgz
cd Python-3.4.3/
./configure --prefix=/path/to/projects/adsm_python --exec_prefix=/path/to/projects/adsm_python
make
make altinstall
cd ..
rm -r Python-3.4.3
/path/to/projects/adsm_python/bin/pip uninstall setuptools
/path/to/projects/adsm_python/bin/pip uninstall pip
wget https://pypi.python.org/packages/source/s/setuptools/setuptools-3.4.4.tar.gz
tar -vzxf setuptools-3.4.4.tar.gz
rm setuptools-3.4.4.tar.gz
cd setuptools-3.4.4
/path/to/projects/adsm_python/bin/python setup.py install
cd ..
rm -r setuptools-3.4.4/
wget https://pypi.python.org/packages/source/p/pip/pip-1.5.6.tar.gz
tar -vzxf pip-1.5.6.tar.gz
rm pip-1.5.6.tar.gz
cd pip-1.5.6
/path/to/projects/adsm_python/bin/python setup.py install
cd ..
rm -r pip-1.5.6
cd /path/to/projects
git clone git@github.com:NAVADMC/ADSM.git
cd adsm
/path/to/projects/adsm_python/bin/pip install -r Requirements.txt
/path/to/projects/adsm_python/bin/pip install -r Requirements-Nix.txt
/path/to/projects/adsm_python/bin/pip install hg+https://bitbucket.org/BryanHurst/cx_freeze
cd /path/to/projects
hg clone hg+https://bitbucket.org/BryanHurst/cx_freeze
cd cx_freeze
/path/to/projects/adsm_python/bin/python setup.py install
cd ..
rm -r cx_freeze
cd /path/to/projects/adsm
npm install
During Development, it would be a pain to continually build the project just for testing.
Thankfully, this is a Python project and so does not actually need to be compiled to run if you have the Virtual Environment setup.
Just like if you were to install ADSM on a server for hosting cloud services, you don't need a compiled distributable.
DRIVE:\\path\to\projects\adsm_venv\Scripts\python.exe DRIVE:\\path\to\projects\adsm\manage.py devserver
/path/to/projects/adsm_python/bin/python /path/to/projects/adsm/manage.py devserver
List of Relevant Branches: master, Stable
Development should be done in feature branches and merged into master. Master is the general development branch, and where Beta releases come from.
Master branch is what will be tagged in GitHub Pre-Release (Beta) Releases.
Stable is the branch we merge master into when we are ready to do a production release.
Stable branch is what will be tagged in the GitHub Releases.
The version number is broken into four parts by periods: SimulationMajor.SimulationMinor.UIRelease.UIMinor/Beta.
Note that this does mean that the first two digits can advance without resetting the last two digits.
A progression could be 3.3.4.5 -> 3.4.4.5.
The Master/Beta Branch will always be the first into a new UIRelease version.
After pushing a Stable release, the next set of new feature work will bump the UIRelease version and reset the UIMinor version in the master branch (3.3.4.5 -> 3.3.5.0).
Once work in master is deemed ready for release, Stable is bumped to the latest UIRelease.UIMinor version that we have been working on in master; meaning Stable won't see 3.3.5.1, 3.3.5.2... and so on but go directly to the current state of Master (3.3.5.8?).
The NPU server is currently hosted by Newline Technical Innovations.
Developers will not need to log into the web panel provided by that server.
Each release line of ADSM has a "Program_id" and "Password" associated with it on the NPU Server. You need the id and password to push release to the server. Please talk with your development team to acquire these sensitive credentials.
The ADSM releases are:
ADSM/__init__.py
and in package.json
python setup.py build
build
directory and attach it to this new release.cd build
npu --create_update --program=ADSM_Beta --program_id=PROGRAM_ID --password=PASSWORD
ADSM/__init__.py
, in package.json
and in installer_windows.nsi
python setup.py build
build
directory and attach it to this new release.cd build
npu --create_update --program=ADSM --program_id=PROGRAM_ID --password=PASSWORD
Project Members:
Noun Project Icons: