Complete documentation

    Complete documentation

    Almost everything in VisualPDE is customisable. Here, we describe the basic functionality of every option that can be found in the menus of VisualPDE.

    Equations ($f(x)$)

    VisualPDE is all about solving equations. In the Equations pane, you can view and define the problem that VisualPDE will solve for you in your browser, complete with initial and boundary conditions. More advanced settings, including variable renaming, can be found under Settings.

    Edit

    Customise all the terms in the PDEs that you would like to solve using natural syntax. See our discussion of valid expressions for helpful examples that will guide you in posing your own PDE system. Typing in any of the fields will highlight the corresponding term in the typeset PDE above.

    Parameters

    This menu contains a list of all the user-specified values that can be used throughout VisualPDE. New parameters can be defined using the empty input field at the bottom of the list of parameters. Parameters can depend on one another, but their definitions cannot be cyclic. JSON key: kineticParams, definitions, string. Default: "a=0.037 in [0,0.1];b=0.06 in [0.04,0.1];",

    Basics

    The basic syntax for defining a parameter is

    name = value

    which will make the quantity name available to the simulation. You can then freely change value, which will instantly propagate throughout VisualPDE. If you try to use a name that clashes with an internal variable (some of which are only found under the hood of VisualPDE), a warning will appear to inform you of this. Parameters can be removed by deleting the text that defines them. You can even choose a name that includes subscripts, such as k_1u. This will be interpreted as $k_{1u}$ automatically by VisualPDE.

    Sliders

    The more advanced syntax

    name = value in [start,step,stop]

    creates a slider for your variable, ranging between the start and stop values in increments of step. The step parameter can be omitted and VisualPDE will choose a step automatically. For example,

    a = 0.5 in [0,1]

    creates a slider that ranges between 0 and 1, with initial value 0.5 and an automatically determined step size. Parameters with sliders cannot be defined in terms of other parameters.

    The configuration of a slider (value, start, step, stop) can be updated by modifying the relevant parts of the expression that defines it. Sliders can be removed by deleting in ... from the parameter definition, and will be removed automatically when the associated parameter is removed.

    Boundary conditions

    Boundary conditions can be specified for any species in the simulation. The following boundary conditions are available:

    Boundary conditions that allow you to specify values can be functions of space ($x$, $y$), time ($t$), any of the unknowns ($u$, $v$, $w$, $q$), the size of the domain ($L$, $L_x$, $L_y$), the images ($I_S$, $I_T$) and any quantities defined in Parameters. Robin boundary conditions are the only type supported that allow you to use an unknown in the specification of its own boundary condition. See our discussion of valid expressions for valid syntax and a list of available in-built functions.

    An additional option, Mixed…, is also available, which allows you to specify different types of boundary condition on the Left, Right, Top and Bottom sides of rectangular domains.

    The easiest way to do this is using the graphical interface by clicking 🧊 beside the boundary condition selector (unavailable during surface plots). Click the various boundaries to set the desired condition on each. These conditions can also be specified directly as a string, e.g.

    Left: Dirichlet = 0; Right: Neumann = 1; Top: Robin = u; Bottom: Dirichlet = sin(x)

    for the species $u$ would specify $u = 0$ on the left boundary, $\frac{du}{dn} = 1$ on the right boundary, $\frac{du}{dn} = u$ on the top boundary and $u = \sin(x)$ on the bottom boundary. Sides can be specified in any order and are case sensitive. Omitting any side will default to periodic boundary conditions (beware, this may have unexpected results if the matching side is not also periodic; using the graphical interface prevents this).

    An additional type of condition, ‘Ghost’, can also be specified with Mixed boundary conditions. This advanced option pushes VisualPDE to its limits, overriding the value of the ghost nodes used in the spatial discretisation of the PDE, and should be used with caution. We make use of this option in our Visual Story on virus transmission to effectively double the size of the computational domain in one direction. This must be toggled on in Settings (🔧) → Misc. JSON key: boundaryConditions_i, one of (periodic, dirichlet, neumann, robin). Defaults: boundaryConditions_1: periodic, boundaryConditions_2: periodic. JSON key: dirichletStr_i, definition, string. JSON key: neumannStr_i, definition, string. JSON key: robinStr_i, definition, string.

    Initial conditions

    Initial conditions can be specified for any species in the simulation. They can be functions of space ($x$, $y$), the size of the domain ($L$, $L_x$, $L_y$), the images ($I_S$, $I_T$), the random quantity RAND, a uniformly random value in $[0,1]$, the random quantity RANDN, a normally-distributed random number with unit variance and zero mean, and any quantities defined in Parameters. See our discussion of valid expressions for valid syntax and a list of available in-built functions. JSON key: initCond_i, definition, string. Defaults: initCond_1: "0", initCond_2: "1".

    Advanced options

    Configure additional equation-related settings, including the number of species and the type of terms that will be included.

    Views (📚)

    There are often multiple ways to visualise a solution to a PDE. In the Views pane, you can select from and customise a range of example-specific display options, or create your own. Everything you customise will be saved in the current View. If you share your simulation via a link, your Views will be sent along too.

    New (+)

    Create a new view with a placeholder name from the current view configuration.

    Rename

    Edit the name of the current View, enclosing any mathematics in $ tags. You can even use emoji.

    Delete

    Delete the currently selected View. Only visible if there are at least two views.

    Expression

    Choose the expression that you want to be used to colour the domain, which can be any function of the species solved for, as well as space, time, and user-defined parameters. Often, this is either $u$, $v$, $w$ or $q$. Explicitly, this can be a function of space ($x$, $y$), time ($t$), any of the unknowns ($u$, $v$, $w$, $q$) and their gradients ($u_x$, $u_y$, etc.), the size of the domain ($L$, $L_x$, $L_y$) and the images ($I_S$, $I_T$). JSON key: whatToDraw, whatToPlot, definition, string. Defaults: whatToDraw: "u", whatToPlot: "u".

    Plot type

    Choose from three types of plot: line, plane or surface. Any simulation can be viewed as any plot type.

    Line plots are the default plot type for 1D domains. Cubic splines are used to interpolate between nodes of the computational domain for smooth plotting. This may lead to transient oscillations appearing near discontinuities in the solution.

    Surface plots are constructed by using the chosen Expression as a height map, the limits of the colour axis and the Height scale parameter. JSON key: plotType, one of (line, plane, surface).

    Colour

    Customise everything about the colours used to display the solution.

    Contours

    Toggle the rendering of contours on top of the simulation display. The number, colour, and sensitivity of these (equally spaced) contours can be configured in the Contours menu that appears when contours are enabled. JSON key: contours, boolean.

    Lighting

    Toggle lighting effects, which adds reflections and shadows to the solution. This often adds a fluid-like character to a simulation. We make use of the Phong reflection model. Details of the filter, including its strength and the orientation of the simulated light, can be specified in the Lighting menu that appears when lighting is enabled. Some lighting effects may appear slightly pixellated on some devices (typically Android tablets and iPadOS devices), though increasing the grid refinement will mitigate this. JSON key: emboss, boolean.

    Overlay

    Toggle the display of an overlay. The expression, colour, and threshold used in displaying the overlay can be specified in the Overlay menu that appears when the overlay is enabled. JSON key: overlay, boolean.

    3D options

    When viewing surface plots, this menu will appear to allow you to customise aspects of the display.

    Line options

    When viewing line plots, this menu will appear to allow you to customise aspects of the display.

    Vector field

    Toggle the rendering of a vector field on top of the simulation. The definition, colour, density, and size of the vectors can be fully customised. This option is often used to visualise flows or fluxes. JSON key: vectorField, boolean.

    Time series

    Toggle the display of a live time series graph of the simulation. This can show either the value of the Expression at a single (configurable) position, or the integral of the expression over the domain. JSON key: probing, boolean.

    Settings (🔧)

    Here you can edit a wide range of settings, from the size of the brush to the timestep of the simulation.

    Brush

    VisualPDE allows you to interact directly with simulations via a brush by simply clicking/pressing on the domain. The brush paints values onto the discrete representation of the domain, which act like initial conditions for the rest of the simulation. Using the alternate mouse button (often the right mouse button) will negate the value of the brush. The brush can be used to create complex initial conditions, perturbations, or even to (crudely) simulate the effect of a moving boundary.

    Domain

    Timestepping

    Images

    Checkpoints

    VisualPDE supports checkpoints, which allow you to save the state of a simulation at the touch of a button. This allows you to instantly return to a previous solution state - very handy if you’ve crafted the perfect initial condition by painting with the brush. Revert to a checkpoint by pressing Restart (🔄)

    Misc

    Writing valid expressions

    Standard syntax

    VisualPDE aims to support standard mathematical syntax for addition +, subtraction -, multiplication *, and division /, along with the caret notation ^ for exponentiation. Parentheses () are also supported for bracketing terms together, and must be used when calling any special functions.

    In general, whitespace around binary operators will be ignored, so that 2 * 2 is valid syntax for multiplication, for example. Quantities with subscripts, such as $L_x$ and $L_y$, are written with an underscore, e.g. L_x and L_y. Boolean expressions (e.g. x < 0) can be used as indicator functions by surrounding them with the function ind (e.g. ind(x < 0)).

    Examples of valid syntax include

    sin(x) * cos(3*y)
exp( -(x-L_x)^2 / 10)
1 + (x^2 + x + 1) / (y^2 + 2*y + 1)
sin(cosh(tan(2*x+1)))

    Advanced syntax

    Some terms in VisualPDE have additional functionality when written with special syntax.

    Images

    By default, images are accessed using I_T and I_S, with individual channels available by appending R,G,B or A. When a channel is specified, you can access images using coordinates using the syntax I_TR(x,y). Examples include

    I_TR(2*x, y)
I_SB(x-t, y-t)
I_TG(x, y + sin(u))

    First derivatives

    First derivatives in space, accessed with u_x, u_y, …, are computed using a central finite difference discretisation by default. By appending f or b to the subscript, such as u_xf, you can tell VisualPDE to use a forward or a backward difference, respectively. Forward differences sample the solution at increased $x$ (or $y$), whilst backward differences sample at decreased $x$ (or $y$). These specialised schemes can be used in upwind schemes and often reduce numerical artefacts, but at the expense of typically larger numerical error.

    Forward and backward differences can also be computed with second-order numerical schemes by appending 2 to the subscript, though in general this will only respect Periodic boundary conditions in the direction of the derivative. This syntax can only be used in the Edit section of Equations.

    Special functions

    Throughout VisualPDE, you can make use of the special functions sin, cos, tan, exp, log, sqrt, sinh, cosh, tanh and H, where the latter is a Heaviside function smoothed over the interval $[-1,1]$ (see the GLSL reference for details). All function arguments should be surrounded by parentheses, e.g. sin(x). You can also use min and max as functions with two arguments, which return the minimum or maximum of their arguments, e.g. min(u,1) returns the minimum of $u$ and 1. If you wish to raise the output of a function to a power, you must enclose the function in parentheses, e.g. write (cos(x))^2, not cos(x)^2. You can also use mod(a,b) to compute the remainder of $a$ upon division by $b$ (see the GLSL reference for details).

    A bump function with compact support can be used via the syntax Bump(X, Y, radius) (or Bump(X, radius) in 1D, with Y implicitly set to L_y/2), which localises a bump of unit maximum of the given radius at the point $(X, Y)$.

    A bivariate Gaussian function can be used with similar syntax to the bump function: Gauss(X, Y, s) is a correctly normalised Gaussian function centred at $(X,Y)$ with standard deviation s. The extended syntax Gauss(X, Y, s_x, s_y) produces a potentially asymmetric Gaussian with standard deviations s_x and s_y in the $x$ and $y$ directions, with zero correlation. Correlation can be specified via Gauss(X, Y, s_x, s_y, r), where r is the correlation between the two directions.

    Non-local evaluation

    Sometimes, you might want direct access to the values of a species at points other than (x,y), such as if you wanted to implement a higher order derivative or a lattice dynamical system. You can access a species (e.g. u) at an arbitrary position via the syntax u[x,y], where x and y can be any valid expression that points to somewhere in the domain. For instance, writing u[x+dx,y+dy] - u[x-dx,y-dy] will lookup nearby values of u, offset by the step sizes dx and dy.

    The behaviour of non-local evaluations using these expressions is undefined at boundaries (so that Neumann boundary conditions may not behave as expected, for instance), unless periodic boundary conditions are used.

    Interaction via query strings

    The simulation can be modified directly using query strings.

    For example https://visualpde.com/sim/?boundaryConditions_1=dirichlet replaces the default simulation preset first variable’s boundary condition to Dirichlet.

    This can be chained using standard query string notation using &. For instance, https://visualpde.com/sim/?boundaryConditions_1=dirichlet&timesteppingScheme=RK4 replaces the default simulation preset first variable’s boundary condition to Dirichlet and the timestepping scheme to Runge-Kutta 4.

    Other parameters

    The following parameters are only accessible via query strings.

    Known quirks

    There are special characters that are reserved in query strings that often overlap with mathematical expressions, these are,

    Example

    The following gives a 3-species system:

    https://visualpde.com/sim/?numSpecies=3&speciesNames=u+v+w&crossDiffusion=true&reactionStr_1=u*(1-u)-u*v&reactionStr_2=u*v-0.5*v-v*w&reactionStr_3=v*w-0.5*w&diffusionStr_1_1=0.1&diffusionStr_2_2=0.1&diffusionStr_3_3=0.1&diffusionStr_1_2=0.5&initCond_1=RAND&initCond_2=0.1&initCond_3=0.01&boundaryConditions_1=dirichlet&dirichletStr_1=0&boundaryConditions_2=neumann&neumannStr_2=0&boundaryConditions_3=periodic&dt=0.001&simTitle=3-species%20example

    Explaination,

    All other options remain to default values as they are unmodified.