MATLAB Converter Files

PharmML to MATLAB Converter
===========================

Version: 1.0 (Alpha, Reference Implementation)
Dated:	 31/08/2016

Overview
========

This document provides instructions on how to use
the binary release of the reference PharmML->MATLAB converter.
This release is a reference implementation of a MATLAB converter and connector.

The converter transforms language neutral PharmML into MATLAB syntax.
The connector allow the MATLAB converter to be run as a shell tool.

Due to deployment constraints, this converter will only generate simulation code
for MATLAB using core MATLAB syntax and functions. 
It uses mathematical instructions from a input PharmML model to define 
the content of a model in MATLAB syntax.

The source code of this converter is based on the DDMoRe 
libPharmML ( https://sourceforge.net/projects/libpharmml.ddmore.p/ )
and CCoPI-Mono converter engine ( https://sourceforge.net/p/ccopi-mono/code/ci/master/tree/ ).

The source code of this converter is found at the following web-site:-

https://sourceforge.net/projects/matlabconverterddmore/

The above web-site contains all the Java source-code and Maven projects required to build this application.
This converter framework can be extended for different MATLAB model forms and toolkits.

The remainder of this document describes the reference PharmML models
and gives instructions on how running the converter software to generate 
MATLAB source-code from PharmML.

System Requirements
===================
Java 1.7 or 1.8 run-time environment (JRE).

Reference Models
================

7 PharmML reference models are supplied with this MATLAB converter.
These reference models show how to generate MATLAB code from PharmML.
The model PharmML was created from an MDL input file, the MDL source files are 
supplied with this release. 
MDL is the mathematical scripting language developed by DDMoRe.

A brief description of reference models and the model content is listed below.
The output filename listed below is the filename of the MATLAB file created 
in the output directory when the converter demonstration script is executed.

Model:	bp2007
Info:	Docetaxel PBPK (Bradshaw-Pierece 2007, Dependency Sorting of Model Elements)
Output File: call_bp2007.m

Model:	brain_distribution
Info:	PBPK Brain Distribution Model (Winterhout 2012)
Output File: call_brain_distribution.m

Model:	dde1
Info:	dde1 (Delay Derivative Model (DDE), solver switching based on model content)
Output File: call_dde1.m

Model:	hh1952
Info:	Axon Model (Hodgkin-Huxley 1952)
Output File: call_hh1952.m

Model:	rigid_body1
Info:	Rigid Body w/o external Forces (Standard ODE45 reference model)
Output File: call_rigid_body1.m

Model:	rigid_body2
Info:	Rigid Body w/o external Forces (Parameters defined in model function)
Output File: call_rigid_body2.m

Model:	warfarin_pk
Info:	Warfarin PK (Analytical Model, Piecewise conditional, Reserved word filtering)
Output File: call_warfarin_pk.m

Running the Converter Examples
==============================

1. Download the file 'matlab-bin.zip' from this web site.
2. Unzip and change directory to the root folder.
3. Run the shell command 'demo.sh' or 'demo.bat' to generate output MATLAB source files
   in the output directory.

The MATLAB converter is run as a shell tool from the console.
The shell command is listed in the demonstration script files.

The MATALAB converter is packaged in the form of an executable JAR file, i.e. 'converter-pharmml2matlab.jar'.
This is a shaded JAR so all dependencies are included in the archive.

The MATLAB converter takes 3 command-line arguments.

-i <File Name> 		= The path to an input PharmML model.
-o <Directory> 		= The name of an output directory for the generated MATLAB source files.
-s <File Output Stem>	= The name of the file stem of the generated MATLAB source files.

For example running the following command:-

java -jar converter-pharmml2matlab.jar -i xml\bp2007.xml -s bp2007 -o output

This generates a MATLAB representation of the input PharmML model (bp2007.xml) 
with the generated source file (e.g. call_bp2007.m) created in the output 'o' directory.

For a given input model, the converter generates a model function and a main script to
execute and plot the model.

Generating PharmML from MDL
==========================

The XML of the input PharmML models were generated from MDL syntax.
MDL is the mathematical scripting language developed by DDMoRe.
MDL defines a model as a series of algebraic expressions and statistical declarations.

The reference PharmML models files are created by 
running the scripts 'test_models.bat' or 'test_models.sh'.

Running these scripts creates 'fresh' PharmML models in the XML directory.

The MDL syntax the defines the reference model is found in the files contained within the MDL directory.
MDL is declarative in nature so model elements can be defined out of sequence.
Modify these MDL models to create new PharmML models.