Package {DynMSR}

Compile a DynMS model with mrgsolve

Description

Generates an mrgsolve model source file and compiles it with mrgsolve. The mrgsolve package is optional and is required only when this function is called.

Usage

build_mrgsolve(model, filepath = NULL, observables = NULL, ...)

Arguments

Value

A compiled mrgsolve model object.

Examples

if (requireNamespace("mrgsolve", quietly = TRUE)) {
  model <- get_model(dynms_load(dynms_lib("repeated-dose")), 1)
  compiled <- build_mrgsolve(model, observables = "ke", quiet = TRUE)
  simulation <- mrgsolve::mrgsim_df(compiled, end = 48, delta = 0.1)
}

Locate bundled DynMS examples

Description

Returns the available example names or the path to one bundled DynMS JSON file. Use dynms_load() to load the selected example.

Usage

dynms_lib(name = NULL)

Arguments

Value

If name is NULL, a character vector of example names. Otherwise, the path to the selected DynMS JSON file.

Examples

dynms_lib()
platform <- dynms_load(dynms_lib("first-order-decay"))

Load a DynMS platform

Description

Reads a DynMS JSON file, validates it against the bundled schema, runs backend-independent semantic validation, and returns a platform list.

Usage

dynms_load(path)

Arguments

Details

Schema and semantic validation are both attempted before loading fails. Validation messages are reported with message(), followed by one final error when any validation issue is found.

DynMSR currently supports only expressions with format: "math-json".

Value

A platform list. Use platform$models[[i]] to select one model for backend-specific operations.

Examples

platform <- dynms_load(dynms_lib("two-state-conversion"))
platform

Read a DynMS JSON file

Description

Reads a DynMS JSON file into an R list. DynMS documents are parsed with jsonlite::fromJSON(..., simplifyVector = FALSE) to preserve the document structure.

Usage

dynms_read(path)

Arguments

Value

An R list parsed from JSON.

Examples

path <- dynms_lib("first-order-decay")
dynms_read(path)

Validate a DynMS document against the JSON Schema

Description

Validates a DynMS document against a JSON Schema. The document can be passed as a file path or as the raw R list returned by dynms_read(). Validation always uses the schema bundled with DynMSR. It uses the ajv engine because the bundled schema uses modern JSON Schema features.

Usage

dynms_validate_schema(x, error = FALSE)

Arguments

Value

A list with valid, errors, and warnings fields.

Examples

validation <- dynms_validate_schema(dynms_lib("first-order-decay"))
validation$valid

Validate DynMS semantic consistency

Description

Validates backend-independent semantic consistency of a schema-valid raw DynMS platform object. Unlike schema validation, this function collects all currently known semantic issues before returning. It does not validate the document structure; use dynms_validate_schema() first when the input has not already passed schema validation.

Usage

dynms_validate_semantic(raw_platform, error = FALSE)

Arguments

Value

A list with valid, errors, and warnings fields.

Examples

raw_platform <- dynms_read(dynms_lib("first-order-decay"))
validation <- dynms_validate_semantic(raw_platform)
validation$valid

Get one model from a platform

Description

Selects one model from a DynMS platform by numeric index or by name.

Usage

get_model(platform, model)

Arguments

Value

A model list.

Examples

dynms_path <- dynms_lib("repeated-dose")
platform <- dynms_load(dynms_path)
model <- get_model(platform, 1)

Build a Heta project

Description

Runs ⁠heta build⁠ for a Heta project directory. The arguments map directly to Heta compiler CLI options, for example units_check = TRUE adds --units-check.

Usage

heta_build(
  dir,
  output_dir,
  source = NULL,
  type = NULL,
  debug = FALSE,
  units_check = FALSE,
  log_mode = NULL,
  declaration = NULL,
  log_level = NULL,
  skip_updates = FALSE,
  export = NULL
)

Arguments

Details

Requires a heta command that satisfies DynMSR's bundled compatibility rule. Use heta_check() to inspect availability and the supported version range before building. Compiler output paths are placed under output_dir: ⁠dist/⁠, ⁠meta/⁠, and, when selected by log_mode, build.log. The output directory must be supplied explicitly and remains available after the build.

Value

Invisibly returns a list with the command, arguments, exit status, captured output, and output_dir.

Examples

## Not run: 
project_dir <- "path/to/your/heta-project"
output_dir <- tempfile("dynmsr-heta-output-")
heta_build(project_dir, output_dir, export = "SBML",
           log_mode = "always")

## End(Not run)

Check Heta compiler availability

Description

Checks whether the heta command is available, can report its version with heta --version, and satisfies the bundled DynMSR compatibility rule.

Usage

heta_check()

Value

A list with available, supported, command, version, supported_version, installation_url, output, and message fields.

Examples

heta_check()

Load a Heta project as a DynMS platform

Description

Builds a Heta project with the DynMS export enabled, reads the generated DynMS JSON file, and returns a DynMS platform object.

Usage

heta_load(
  dir,
  output_dir = NULL,
  source = NULL,
  type = NULL,
  debug = FALSE,
  units_check = FALSE,
  log_mode = NULL,
  declaration = NULL,
  log_level = NULL,
  skip_updates = FALSE
)

Arguments

Details

Requires a compatible heta-compiler installation. Compiler output is placed under output_dir in ⁠dist/⁠, ⁠meta/⁠, and, when selected by log_mode, build.log. When output_dir is omitted, a temporary directory is removed after loading.

Value

A platform list. Use get_model() or ordinary list access such as platform$models[[1]] to select one model.

Examples

## Not run: 
platform <- heta_load("path/to/your/heta-project")
model <- get_model(platform, 1)
compiled <- build_mrgsolve(model, quiet = TRUE)
simulation <- mrgsolve::mrgsim_df(compiled, end = 24, delta = 0.1)

## End(Not run)

Print a DynMS model

Description

Displays a compact inventory of model components and their identifiers.

Usage

## S3 method for class 'model'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

model <- get_model(dynms_load(dynms_lib("first-order-decay")), 1)
print(model)

Print a DynMS platform

Description

Displays the DynMS version and a compact summary of each model in a platform.

Usage

## S3 method for class 'platform'
print(x, ...)

Arguments

Value

x, invisibly.

Examples

platform <- dynms_load(dynms_lib("first-order-decay"))
print(platform)

Load an SBML file as a DynMS platform

Description

Builds one SBML file through Heta compiler with the DynMS export enabled, reads the generated DynMS JSON file, and returns a DynMS platform object.

Usage

sbml_load(
  path,
  output_dir = NULL,
  debug = FALSE,
  units_check = FALSE,
  log_mode = NULL,
  declaration = NULL,
  log_level = NULL,
  skip_updates = FALSE
)

Arguments

Details

Requires a compatible heta-compiler installation. The generated DynMS export is written to a temporary directory and removed after loading unless output_dir is supplied.

Value

A platform list. Use get_model() or ordinary list access such as platform$models[[1]] to select one model.

Examples

## Not run: 
sbml_path <- "path/to/your/model.xml"
platform <- sbml_load(sbml_path)
model <- get_model(platform, 1)
compiled <- build_mrgsolve(model, quiet = TRUE)
simulation <- mrgsolve::mrgsim_df(compiled, end = 24, delta = 0.1)

## End(Not run)

Write an mrgsolve model file

Description

Generates mrgsolve source from one DynMS model.

Usage

write_mrgsolve(model, filepath)

Arguments

Details

The exporter warns and ignores unsupported DynMS features: algebraic dynamic states, stopSimulation, and state-event trigger detection. Algebraic states are emitted as ordinary ODE states; state-event conditions are evaluated in generated code without root finding. The current exporter evaluates state-event conditions in ⁠$ODE⁠, which mrgsolve may call at internal trial times. The resulting state update can therefore occur at an output record before or after the true threshold crossing. Smaller delta or hmax values can sometimes make the approximation closer, but cannot reproduce the exact root-crossing time or guarantee which side of the threshold an event will be placed.

Identifiers reserved by mrgsolve are renamed with an ⁠_rnm_⁠ suffix. Further numeric suffixes are added when needed to avoid collisions. The exporter emits one warning and records the complete mapping in the generated model. The DynMS time symbol t is emitted as SOLVERTIME in ⁠$ODE⁠ and as TIME in other blocks.

Value

The path to the generated model file.

Examples

model <- get_model(dynms_load(dynms_lib("first-order-decay")), 1)
path <- tempfile(fileext = ".mod")
write_mrgsolve(model, path)
unlink(path)