Maxima exercises calculate question values and correct answers when
an exercise is instantiated. One exported item can therefore produce
many random variants. You can write the calculations in a
{maxima} chunk, display their outputs with
template_value(), and bind a correct answer with
gap_numeric(solution_variable = ...) or
gap_text(solution_variable = ...).
Maxima support is experimental and not yet part of a CRAN release. Install the development version with R >= 4.1, then restart your RStudio R session:
remotes::install_github("shevandrin/rqti")Requirements
Install Maxima separately. rqti finds it on PATH, or you can select its executable explicitly:
options(rqti.maxima = "/usr/bin/maxima") # replace with your executable's pathOn Windows, PATH is the Windows environment variable. If Maxima is not on it, use the full path to the command-line launcher, for example:
options(rqti.maxima = "C:/maxima-5.44.0/bin/maxima.bat")Use your installation’s actual path, including the executable filename. Forward slashes work in Windows R strings. No additional R interface package is required; ordinary rqti exercises do not require Maxima. See Configuration for persistent settings.
Maxima support also uses a few suggested R packages. rqti names any that are missing; you can install them all at once:
install.packages(c("processx", "filelock", "later", "promises", "openssl"))rqti runs Maxima locally when checking Rmd chunks and generating
previews. An exported exercise needs a delivery platform that supports
the ONYX MAXIMA custom operator, such as ONYX/OPAL. The XML
retains the program; the sample values from the authoring check are not
fixed into the exported question.
Write an Rmd exercise
Here is the complete addition example shipped with this branch:
---
type: gap
identifier: maxima_local_addition
title: "Maxima addition in RStudio"
knit: rqti::render_qtijs
---
<!-- In the RStudio console, run rqti::start_server()
before clicking Knit. The preview opens in the RStudio Viewer. -->
```{r setup, include=FALSE}
library(rqti)
```
```{maxima addition}
block(
[a, b, answer],
a: random(100),
b: random(100),
answer: a + b,
string(['a = a, 'b = b, 'answer = answer])
);
```
# question
What is **`r template_value("a")`** + **`r template_value("b")`**?
Answer: `r gap_numeric(solution_variable="answer", tolerance_type="exact", points=1)`The Maxima block returns a string containing a named association
list: string(['a = a, 'b = b, 'answer = answer]). rqti
reads the output names and types from one local execution, creates the
template declarations, and keeps the calculation in the QTI template.
template_value("a") displays an output;
gap_numeric(solution_variable = "answer") uses the
generated numeric answer.
numericGap(solution_variable = ...) provides the same
binding in the S4 API.
Preview in RStudio
Start the preview server in the RStudio console before clicking Knit. Copy the installed example to a writable location first:
library(rqti)
rqti::start_server()
example <- file.path(tempdir(), "maxima-addition.Rmd")
file.copy(
system.file("extdata", "maxima-local-addition.Rmd", package = "rqti"),
example,
overwrite = TRUE
)
rstudioapi::navigateToFile(example)Click Knit. The RStudio Viewer should show the
addition exercise with generated numbers. The preview also works in an
external browser using the URL printed by start_server() or
render_qtijs().
qti.js sends the template calculation to the local R server, which
runs Maxima and returns typed outputs. Submitting an answer preserves
the current numbers; reload the preview page to generate another
variant. A failed preview shows the diagnostic and a
Retry button. To stop the server, use
rqti::stop_server().
Output types and authoring checks
Supported output types are integer, float,
and string. Rational numbers and real numeric constants can
be used as floating-point outputs. Inference observes one random
variant; specify types when they may vary between variants:
For example, replace the addition chunk above with this explicitly typed chunk:
```{maxima addition, variables = c(a = "integer", b = "integer", answer = "float", label = "string")}
block(
[a, b, answer, label],
a: random(100),
b: random(100),
answer: a + b,
label: "Addition",
string(['a = a, 'b = b, 'answer = answer, 'label = label])
);
```The named variables vector sets the QTI types for the
returned outputs. answer = "float" accepts both integer and
floating-point results. The extra text output can be displayed with
template_value("label"). Explicit types do not bypass the
local execution check.
Lists and other structured values need an explicit
string declaration when used for display.
Text answers
Use gap_text(solution_variable = "answer") when the
Maxima output is a string. The output supplies one correct
text answer for each attempt; submitting an answer preserves the
generated word. Matching ignores case by default; set
case_sensitive = TRUE to require matching capitalization.
The entire string must match, including spaces and punctuation. Dynamic
text answers do not support spelling tolerance or a list of alternative
answers. textGap(solution_variable = "answer") provides the
same binding in the S4 API.
This example can be previewed in qti.js and exported for ONYX/OPAL:
---
type: gap
identifier: maxima_text_answer
title: "Text answers from Maxima"
knit: rqti::render_qtijs
---
<!-- Run rqti::start_server() in the RStudio console before clicking Knit. -->
```{r setup, include=FALSE}
library(rqti)
```
```{maxima words}
block([answer],
answer: ["Blue", "Green", "Orange"][random(3) + 1],
string(['answer = answer])
);
```
# question
The generated word is **`r template_value("answer")`**.
Copy it here (capitalization does not matter):
`r gap_text(solution_variable = "answer", response_identifier = "insensitive")`
Copy it here again (capitalization must match):
`r gap_text(solution_variable = "answer", case_sensitive = TRUE, response_identifier = "sensitive")`To try it, copy the installed example to a writable location, start the preview server, and open the copy in RStudio:
example <- file.path(tempdir(), "maxima-text-answer.Rmd")
file.copy(
system.file("extdata", "maxima-text-answer.Rmd", package = "rqti"),
example,
overwrite = TRUE
)
rqti::start_server()
rstudioapi::navigateToFile(example)Click Knit. Copying the word in lowercase earns one point; copying its capitalization exactly into both gaps earns two. Wrong or empty answers earn zero. Submitting preserves the word; reloading generates another variant. Verify generated text-answer scoring in your target LMS before using it in an assessment.
Display LaTeX strings
Return LaTeX as a Maxima string and insert it with
template_value(). Double backslashes inside Maxima strings:
"\\mathbb{R}" returns \mathbb{R}.
For inline math, surround the reference with \\( and
\\) in the Rmd text. For display math, use $$.
Alternatively, include the delimiters in the returned Maxima string and
insert the reference directly.
The complete example below shows each form. Copy it to an Rmd file, start the preview server, and click Knit:
---
type: gap
identifier: maxima_latex
title: "LaTeX from Maxima"
knit: rqti::render_qtijs
---
<!-- Run rqti::start_server() in the RStudio console before clicking Knit. -->
```{r setup, include=FALSE}
library(rqti)
```
```{maxima latex}
block([],
string([
'number_set = "\\mathbb{R}",
'embedded = "\\(\\mathbb{R}\\)",
'dollar_embedded = "$$\\mathbb{R}$$"
])
);
```
# question
Inline math: \\(`r template_value("number_set")`\\).
Display math:
$$`r template_value("number_set")`$$
Inline delimiters included in the returned string:
`r template_value("embedded")`.
Dollar delimiters included in the returned string:
`r template_value("dollar_embedded")`.
What is $1 + 0$? `r gap_numeric(1, tolerance_type="exact")`Authoring checks
rqti executes the Maxima chunk before export, including when types
are declared explicitly. Errors stop export and identify the source
file, chunk, and numbered code. Use one evaluated, uncached Maxima chunk
per exercise and return all values needed by the question and answer in
its string([...]) list. Related random calculations then
share the same execution.
rqti also warns about global variables or functions left behind by
the chunk. On delivery servers that reuse Maxima instances, these can
require a restart and slow down large exams. Keep variables in the
block’s local-variable list and use local() for function
definitions:
Check Maxima code directly
maxima_check() takes one R character string containing
Maxima code, including its terminating semicolons or dollar signs. It
runs that code in a fresh local Maxima process and returns
TRUE invisibly on success:
rqti::maxima_check("1 + 2;")For a program returning the same string([...])
associations used in an Rmd chunk, set outputs = TRUE to
obtain a named vector of inferred types:
code <- "string(['a = 3, 'answer = 1/2, 'label = \"Addition\"]);"
types <- rqti::maxima_check(code, outputs = TRUE)
types
# c(a = "integer", answer = "float", label = "string")A syntax or runtime failure raises an R error containing the Maxima
diagnostic and numbered source code. Rmd conversion calls this function
automatically; you do not need to call it separately before knitting.
Execution is bounded by options(rqti.maxima_timeout = 120)
in seconds, including library startup. The statistics libraries
distrib, descriptive, and stats
load by default.
Export and validate
xml <- rqti::rmd2xml(example, path = tempdir())
result <- rqti::verify_qti(xml, schema = "extended", ignore_import = FALSE)
stopifnot(result$valid)
rqti::rmd2zip(example, path = tempdir())Choose schema = "extended" for ONYX Maxima
items. The standard QTI 2.1 schema rejects ONYX’s
customOperator/@value attribute and the
setCorrectResponse rule in response processing. The default
verify_qti(xml) therefore reports these items as invalid.
rqti’s extended schema accepts those extensions while still checking the
XML structure.
Schema validation does not execute the Maxima program or prove that every random variant works. Rmd authoring checks run one variant locally; preview scoring and an import into the target ONYX installation provide further checks.
Compiled library cache
The first calculation can take longer while Maxima compiles its libraries. Authoring checks and previews share compiled libraries in rqti’s managed user cache across R sessions. Each calculation still starts a fresh Maxima process; programs, variables, and answers remain independent and temporary.
rqti manages cache cleanup automatically. You can choose another cache directory or keep the cache within the current R session: