This article details the new export feature in QSP Designer software, enabling the generation of scripts in the QSP Notebook domain-specific language (DSL).
Certara recently expanded its QSP activities with the acquisition of Applied BioMath, bringing additional QSP modeling software, specifically the QSP Notebook software. Unlike the QSP Designer software previously developed within Certara, which uses a graphical editor, the Applied BioMath software allows users to create text files with scripts using a domain-specific language for simulations and other simulation-based tasks such as fitting. To enable the use of tools offered within QSP Notebook with models defined in the QSP Designer software, there is a desire to be able to generate QSP Notebook DSL scripts from QSP Designer workspaces. This article describes the addition of such export functionality to the QSP Designer software.
User Interface Updates
The user interface in the Generate Script window has been updated to include an option for exporting a QSP Notebook DSL script and its associated files. Additionally, related options have been added to the options tab.
Generate Script Modal (Scripts Tab)
The tab for selecting scripts to generate in the Generate Script window has been expanded to include a new QSP Notebook section. This addition allows users to easily choose and manage QSP Notebook DSL scripts, streamlining the script generation process and enhancing overall functionality. Additionally, this new section enables users to export a QSP Notebook DSL script and select a VPop file for conversion during the import process.
Generate Script Modal (Options Tab)
The Options tab in the Generate Script window has been enhanced with new settings specifically for exporting QSP Notebook DSL scripts. These improvements provide users with greater control and flexibility in generating and managing their scripts.
Additionally, two new options have been added for this export: 'Generate QSP Notebook Dosing File' and 'Generate QSP Notebook Conversion File.' These options allow users to create dosing and conversion files tailored to the QSP Notebook DSL, further enhancing the script generation process.
Changes to the Code Export
Key Differences Between QSP Notebook DSL and QSP Designer
The design choices of the QSP Notebook DSL differ from those of the QSP Designer modeling language in ways that present challenges when converting models between the two. Key differences include:
Fixed Set of Units: The QSP Notebook DSL supports only a fixed set of units, unlike QSP Designer, which allows the definition of arbitrary units.
ODE States as Amounts: For correct simulation in the QSP Notebook DSL, all ODE (ordinary differential equation) states must correspond to amounts.
Parameter Restrictions: In the QSP Notebook DSL, parameter entities are restricted to representing 'true' parameters, meaning non-time-varying inputs to the model.
No 'Initial-Only' Assignments: The QSP Notebook DSL does not support 'initial-only' assignments; if an assignment references time-varying variables, it will always be evaluated throughout the simulation.
Addressing Differences in Unit Systems
To address these differences, the export QSP Notebook script creates all state variables as amounts expressed in the simulation base units defined in the QSP Designer workspace. Since arbitrary units cannot be defined in the QSP Notebook DSL, all variables in the exported script are dimensionless. To facilitate the use of simulation results, variables in the exported script are given a '_sim' suffix if their units differ from those in the original QSP Designer model. Concentrations converted to amounts are handled similarly.
Handling Model Parameters and Assignments
Issues related to model parameters and the lack of 'initial-only' assignments are managed by introducing separate initialization quantities with '_init' suffixes. A parallel tree of 'initial-only' assignments is created to ensure initial values are correctly calculated and used where required.
Processing Model Features
Since the QSP Notebook DSL lacks features like indices, sub-graphs, and workspace imports used for concise model definition in QSP Designer, the model is processed to transform it into a form without these features before exporting.
Converting VPop Files
If a VPop file is selected for conversion alongside the export, the converted VPop file will contain values expressed in simulation base units, consistent with the DSL script, and will use modified names with '_init' suffixes.
Defining Individual Dosing
In QSP Designer, individual dosing is often defined using runtime-indexed parameters initialized with VPop files containing value lists. In the QSP Notebook, there is no equivalent of runtime indexing, but individual dosing can be defined via a separate dosing file. Therefore, parameters related to dosing definitions using runtime indexing are excluded from converted VPop files and translated to entries in a dosing definition file if this option is chosen.
Conversion File Option
To assist in converting between values expressed in the original units defined in QSP Designer and those used in the exported script, an option to include a conversion file, which provides a table of conversion factors in CSV format, is also included.
Key Takeaways
Fixed Units vs. Arbitrary Units: QSP Notebook DSL supports only fixed units, while QSP Designer allows arbitrary units.
ODE States as Amounts: All ODE states in QSP Notebook DSL must correspond to amounts.
Parameter Restrictions: QSP Notebook DSL parameters are non-time-varying inputs.
No 'Initial-Only' Assignments: Assignments in QSP Notebook DSL are always evaluated if they reference time-varying variables.
State Variables as Amounts: Export script creates state variables as amounts in base units.
Initialization Quantities: Separate '_init' quantities handle 'initial-only' assignments.
Model Processing: Model features not supported by QSP Notebook DSL are removed before exporting.
VPop File Conversion: Converted VPop files align with DSL script units and naming conventions.
Individual Dosing: Defined via a separate dosing file in QSP Notebook.
Conversion File: Option to include a conversion file with unit conversion factors.