Examp Widgets#

Attention

UNDER CONSTRUCTION!

This page is a work in progress.

Please check back again soon!

“Examp widget” is an umbrella term, referring to either of the two widget types,

  • Parameter widgets

  • Display widgets

involved in building example explorers.

An example explorer is a collection of widgets and surrounding text in an annotation or Sphinx page, designed to help the user rapidly explore numerical examples of mathematical objects and relations. It can be used to illustrate what is happening at a step in a proof.

The two widget types provide for parameters and displays.

A parameter is like an input to a function. It is a number or other mathematical object that the user is free to choose, in order to customize the example case being explored.

A display is a place to show the results of calculations, using arbitrary HTML and TeX. Behind the scenes, the SymPy computer algebra system performs calculations to help generate the displays.

Parameter Widgets#

Each parameter widget generates an HTML “chooser” in the page: a set of buttons, dropdowns, or other interactive elements with which the user can select a value.

The final value of a parameter widget, internally, is always an instance of some SymPy class. These values can be used by other parameter widgets, as inputs in computing their own sets of possible values, as well as by display widgets, in order to generate displays.

Format#

  • TYPE: param

  • LABEL: No.

Fields#

Field

Req

Type

Description

ptype

Y

enum

Parameter type. Specifies which type of parameter you want.

The list of available types is ever expanding, but at time of writing consists of:

  • Integer

  • Prime

  • PrimRes

  • Divisor

  • NumberField

  • PrimeIdeal

name

Y

string

A name for the parameter. Should be a valid Python variable name, so that it can be used in calculations in other parameters and in displays.

default

Y

any

Some specification of a default value for this parameter. May be of various types; it is up to the specific parameter type to interpret.

tex

N

string

String to be used in TeX representations. If unspecified, name will be used.

descrip

N

string

Optional description of the parameter, for the benefit of users. Usually best to let the description be generated automatically.

import

N

object

Mapping from local names to libpaths of other parameters. The names appearing here may then occur within mathematical expressions appearing as values in the args dict (see below). The value of such expressions will then be obtained by substituting the values of these parameters.

Note: As a convenience, if you import a param under the same name as one of the args (see below) this will set the value of the parameter as the value of the arg, unless you override it by defining the arg to have some other value.

args

object

A place to define any arguments, required and/or optional, for this parameter. Keys are argument names prescribed by the particular parameter type; values are any JSON type that in some way specifies a value (again, to be interpreted by the particular parameter type).

Shortcut option: you may omit an arg definition if you have imported a parameter under the exact same name. By doing so, you imply that you want the value of that parameter as the value of this arg.

Parameter types#

At present there is only a small set of available parameter types, but the list can be expected to grow in future versions of Proofscape.

It is important to understand that, when you are choosing a parameter type, you are choosing more than the final SymPy value type; you are also choosing what kind of HTML interface you are going to generate in the page, to help the user select a value.

For example, each of the “Divisor”, “Prime”, and “Integer” parameter types produce a SymPy Integer. But the “Divisor” parameter is customized to help the user choose a divisor of another integer, and the “Prime” parameter is customized to help the user choose a prime.

Table 11 Parameter types#

ptype

SymPy value type

JSON for default

args

Divisor

Integer

int

 
Required:
    dividing: int
        The number of which this is a divisor.
Optional:
    sign: {-1, 0, 1}, default=1
        1 if you want only positive divisors
        -1 if you want only negative divisors
        0 if you allow both positive and negative divisors

Integer

Integer

int

 
Required: None.

Optional:
    coprime_to: int
        Must be coprime to this.
    dividing: int
        Must divide this.
    gt: int
        Must be greater than this.
    lt: int
        Must be less than this.

NumberField

AlgebraicField

 
str
    accepts EITHER:
    - `cyc(n)` or `cyclotomic_poly(n)` for the nth cyclotomic field, OR
    - a string giving any irreducible univariate polynomial over Z

Required: None.
Optional:
    gen: str
        Symbol name to use for a generator of the field.
        For example, 'theta'.
        If supplied, it will be included in the description of the
        field; otherwise, we only describe the field as a quotient
        mod a polynomial.
    var: str
        Symbol name to use for the variable in the field's defining,
        irreducible polynomial.
        If not supplied, we use `x` for `cyc(n)`, or the
        given variable for polynomials given explicitly.
    root_idx: int
        Root index, indicating which root of the minimal polynomial to
        use as primitive element for the field. This is passed to
        SymPy's `CRootOf`. Real roots come first, in increasing order,
        followed by complex roots, which are sorted first by real part
        (increasing) and then by imaginary part (increasing).
        If not supplied, we use -1.

Prime

Integer

int

 
Required: None.
Optional:
    odd: boolean, default=False
        True if you require that it be an odd prime
    chooser_upper_bound: int
        If positive, do not display primes larger than this in
        the chooser HTML. Note: This is not a *mathematical* constraint;
        you are not saying that the prime actually needs to be bounded
        for any mathematical reason. You are only saying that you want
        to limit the set of primes offered in the HTML chooser.
        So the reasons for the limit are practical ones, relating to
        computation time, or surveyability of displays.

PrimeIdeal

PrimeIdeal

 
int
    Zero-based index into the list of PrimeIdeals computed by SymPy.

Required:
    k: Libpath
        Must point to a param widget of `NumberField` type.
    p: int
        The rational prime whose ideal divisors we are to represent.
Optional: None

PrimRes

Integer

int

 
Required:
    m: int
        The modulus for which this is a primitive residue.
Optional: None.

Display Widgets#

The purpose of a display widget is to generate arbitrary HTML (including TeX to be typeset by MathJax), to produce a display of mathematics.

Your main job when defining a display widget is to write Python code, making use of SymPy as needed, which returns a string. That string is the HTML that will be displayed.

The Python code that you write will run in the user’s browser, using Pyodide, but the user has to first formally trust your Proofscape repo before it will execute.

Naturally, your code will often want to make use of the current values of parameter widgets, as starting points. Accordingly, display widgets are able to import parameter values.

Conversely, in the course of your code you may compute useful intermediate values, which your display widget can export. Any values you export can be imported by other display widgets.

Before we can give the table of DATA fields for display widgets, we have to define special import strings that are used to import values exported by other displays.

Import strings#

When importing values exported by another display widget, you need to use an import string.

An import string is a comma-delimited list of “imports,” each of which at least gives the name of a variable as exported from the display widget in question, and may also give a local name you wish to use for it after importing, separated by keyword as.

In other words, an import string matches this grammar:

import_string := import ("," import)*
import := CNAME ("as" CNAME)?
%skip whitespace

Thus, imports can be as simple as,

import: {
    'f': some_disp_widget
}

importing f as 'f' from some_disp_widget, or as complex as,

import: {
    'f as g, a, b, alpha as zeta': some_disp_widget
}

importing f as 'g', a as 'a', b as 'b', and alpha as 'zeta'.

Note that there is no risk of key collision in an import dictionary, because it does not make sense to import more than one thing under the same local name.

Format#

  • TYPE: disp

  • LABEL: No.

Fields#

Field

Req

Type

Description

import

N

object

Import the values of parameters, and/or values exported (see below) by other displays.

To import the value of a parameter, use a key-value pair in which the value is the (relative) libpath of the desired param widget, and the key is the local name you want to use for that parameter.

To import values exported by another display, use a key-value pair in which the value is the (relative) libpath of the desired display widget, and the key is an import string.

build

Y

string

This is the (usually multi-line) string of Python code in which you build the desired display HTML.

The code you write should define (the internal code of) a Python function that returns the desired HTML as a string, and whose arguments are precisely the local variables defined in import.

To be clear, you do not write the def function_name(args): line that starts off a function definition in Python; you write just the indented block that comes under that, and that ends with a return statement.

export

N

array of strings

You can list here the names of any Python variables defined in the course of the build code. These variables will then be available for other display widgets to import.