{ "cells": [ { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "# Intelligent Agents and Active Inference" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Preliminaries\n", "\n", "- Goal \n", " - Introduction to Active Inference and application to the design of synthetic intelligent agents \n", "- Materials \n", " - Mandatory\n", " - These lecture notes\n", " - Karl Friston - 2016 - [The Free Energy Principle](https://www.youtube.com/watch?v=NIu_dJGyIQI) (video)\n", " - Optional\n", " - Raviv (2018), [The Genius Neuroscientist Who Might Hold the Key to True AI](https://www.wired.com/story/karl-friston-free-energy-principle-artificial-intelligence/).\n", " - Interesting article on Karl Friston, who is a leading theoretical neuroscientist working on a theory that relates life and intelligent behavior to physics (and Free Energy minimization). (**highly recommended**) \n", " - Kirsch (2019), [Theories of Intelligence: Active Inference](http://louiskirsch.com/ai/active-inference) \n", " - A nice tutural blog on active inference.\n", " - Van de Laar and De Vries (2019), [Simulating Active Inference Processes by Message Passing](https://www.frontiersin.org/articles/10.3389/frobt.2019.00020/full)\n", " - How to implement active inference by message passing in a Forney-style factor graph.\n", "\n", " - References\n", " - Friston (2013), [Life as we know it](https://royalsocietypublishing.org/doi/full/10.1098/rsif.2013.0475) \n", " - Conant and Ashby (1970), [Every good regulator of a system must be a model of that system](https://www.tandfonline.com/doi/abs/10.1080/00207727008920220)" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Agents\n", "\n", "- In the previous lessons we assumed that a data set was given. \n", "- In this lesson we consider _agents_. An agent is a system that _interacts_ with its environment through both sensors and actuators.\n", "- Crucially, by acting onto the environment, the agent is able to affect the data that it will sense in the future.\n", " - As an example, by changing the direction where I look, I can affect the sensory data that will be sensed by my retina.\n", "- With this definition of an agent, (biological) organisms are agents, and so are robots, self-driving cars, etc.\n", "- In an engineering context, we are particularly interesting in agents that behave with a *purpose* (with a goal in mind), e.g., to drive a car or to design a speech recognition algorithm.\n", "- In this lesson, we will describe how __goal-directed behavior__ by biological (and synthetic) agents can also be interpreted as minimization of a free energy functional $F[q]$. " ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Illustrative Example: Steering a cart to a parking spot\n", "\n", "- In this example, we consider a cart that can move in a 1D space. At each time step the cart can be steered a bit to the left or right by a controller (the \"agent\"). The agent's knowledge about the cart's process dynamics (equations of motion) are known up to some additive Gaussian process noise. The agent also makes noisy observations of the position and velocity of the cart. Your challenge is to design an agent that steers the car to the zero position. (The agent should be specified as a probabilistic model and the control signal should be formulated as a Bayesian inference task). \n" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "fragment" } }, "source": [ "

\n", "\n", "- Solution at the end of this lesson." ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Karl Friston and the Free Energy Principle\n", "\n", "- We begin with a motivating example that requires \"intelligent\" goal-directed decision making: assume that you are an owl and that you're hungry. What are you going to do?\n", "\n", "- Have a look at [Prof. Karl Friston](https://www.wired.com/story/karl-friston-free-energy-principle-artificial-intelligence/)'s answer in this [video segment by on the cost function for intelligent behavior](https://www.vibby.com/watch?vib=71iPtUJxd). (**Do watch the video!**)\n", "\n", "- Friston argues that intelligent decision making (behavior, action making) by an agent requires *minimization of a functional of beliefs*. \n", "\n", "- Friston further argues (later in the lecture and his papers) that this functional is a (variational) free energy (to be defined below), thus linking decision making to Bayesian inference. \n", "\n", "- In fact, Friston's **Free Energy Principle** (FEP) claims that all [biological self-organizing processes (including brain processes) can be described as Free Energy minimization in a probabilistic model](https://royalsocietypublishing.org/doi/full/10.1098/rsif.2013.0475).\n", " - This includes perception, learning, attention mechanisms, recall, action and decision making, etc.\n", " \n", "- Taking inspiration from FEP, if we want to develop synthetic \"intelligent\" agents, we have (only) two issues to consider:\n", " 1. The specification of the FE functional (includes specification of generative model and constraints on the approximate posterior, a.k.a. the \"recognition\" model).\n", " 2. *How* to minimize the FE functional? \n" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### What Makes a Good Agent?\n", "\n", "- What should the agent's model be modeling? This question was (already) answered by [Conant and Ashby (1970)](https://www.tandfonline.com/doi/abs/10.1080/00207727008920220) as the [*good regulator theorem*](https://en.wikipedia.org/wiki/Good_regulator ): **every good regulator of a system must be a model of that system**. \n", " \n", "- From Conant and Ashby's paper (this statement was later finessed by [Friston (2013)](https://royalsocietypublishing.org/doi/full/10.1098/rsif.2013.0475)): \n", "> The theory has the interesting corollary that the living brain, insofar as it is successful and efficient as a regulator for survival, *must* proceed, in learning, by the formation of a model (or models) of its environment.\"\n", "\n", "

" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Active Inference Agents \n", "\n", "- We will follow the idea that an agent needs to hold a generative model for its environment, which is observed through sensory channels. The environmental dynamics can be affected through actions onto the environment.\n", "\n", "- Agents that follow the FEP and infer actions by inference in a generative model of the environment are engaged in a process called **active inference**. " ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "- Technically, an active inference-based agent comprises:\n", "\n", " 1. A free energy functional $F[q] = \\mathbb{E}_q\\left[ \\log\\frac{q(z)}{p(x,z)}\\right]$, where \n", " - $p(x,z) = \\prod_k p(x_k,z_k|z_{k-1})$ is a _generative_ model with observations $\\{x_k\\}$, latent variables $\\{z_k\\} = \\left\\{ \\{s_k\\}, \\{u_k\\}, \\{\\theta_k\\}\\right\\}$ and $k$ is a time index.\n", " - $q(z)$ is a _recognition_ model. \n", " 2. A recipe to minimize the free energy $F[q]$ \n", "\n", "\n", "- Let's draw a diagram to show the interactions between an active inference agent and its environment. \n", "\n", "

\n", "\n", "- In the model above, the hidden variables $\\{z_k\\}$ of the agent comprise *internal* states $\\{s_k\\}$, *control* variables $\\{u_k\\}$ (which are \"observed\" by the environment as actions $\\{a_k\\}$), and *parameters* $\\{\\theta_k\\}$. \n", "\n", "- In neuroscience/psychology parlance, \n", " - _behavior_ (movement) is inference for the control signals ($u$)\n", " - _perception_ is inference for the internal states ($s$). \n", " - _learning_ is inference for the parameters ($\\theta$)\n", " \n", "- We also assume that the agent interacts with an environment, which we represent by a dynamic model\n", "$$\n", "(y_t,\\tilde{s}_t) = R_t\\left( a_t,\\tilde{s}_{t-1}\\right)\n", "$$\n", "where $a_t$ are _actions_ , $y_t$ are _outcomes_ and $\\tilde{s}_t$ holds the environmental _states_. \n", "\n", "- In the above equations, $u_t$ and $x_t$ are owned by the agent model, whereas $a_t$ and $y_t$ are variables in the environment model.\n", "\n", "- The agent can push actions $a_t$ onto the environment and measure responses $y_t$, but has no access to the environmental states $\\tilde{s}_t$.\n", "\n", "- Interactions between the agent and environment are described by \n", "$$\\begin{align*}\n", "a_t &\\sim q(u_t) \\\\\n", "x_t &= y_t \n", "\\end{align*}$$\n", "iow, actions are drawn from the posterior over control signals. \n", "\n", "\n", "\n", "- Note that this system implies a recursive dependency since the agent's future observations depend on the agent's current (and past) actions: $$x_{t+1} = x_{t+1} \\left( a_{t+1} \\right) = x_{t+1} \\left( a_{t+1} \\left( u_{t+1}\\left( x_t \\left( a_t \\left( \\cdots \\right) \\right) \\right)\\right) \\right)$$\n", " - $\\Rightarrow$ As a result, **the agent actively engages in selecting its own data set!**" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Goal-directed Behavior\n", "\n", "\n", "\n", "\n", "- Biological agents select their observations by controling their environment. Perception (and learning) serve to improve this data selection process by updating beliefs about the state of the world. \n", "\n", "- This process begs the question: if a (biological) agent seeks out observations, then which observations is the agent interested in? I.o.w., does the agent have a **goal** \"in mind\" when it engages in active data selection?\n", "\n", "- Yes! Agents set preferences for future observations by setting **prior distributions on future observations**! \n", " - E.g., a self-driving agent in a car expects to observe no collisions.\n", " \n", "- Thus, the generative model for an active inference agent at time $t$ includes variables at future time steps and can be run forward to make predictions (beliefs) about future observations $x_{t+1:T}$. \n" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Active Inference Agent Model specification\n", "\n", "- We assume that agents live in a dynamic environment and consider the following generative model for the agent (omitting parameters $\\theta$), and assuming the current time is $t$:\n", "$$\\begin{align*}\n", "p^\\prime(x,s,u) &= p(s_{t-1}) \\prod_{k=t}^{t+T} \\underbrace{p(x_k|s_k) \\cdot p(s_k | s_{k-1}, u_k)}_{\\text{internal dynamics}} \\cdot\\underbrace{p(u_k)}_{\\substack{\\text{control}\\\\ \\text{prior}}}\n", "\\end{align*}$$\n", " - Note that the generative model includes future time steps.\n", "\n", "\n", "\n", "- In order to infer **goal-driven** (i.e., purposeful) behavior, we now add prior beliefs $\\tilde{p}(x)$ about desired future observations, leading to an *extended* agent model:\n", "$$\\begin{align*}\n", "p(x,s,u) &= \\frac{p^\\prime(x,s,u) \\tilde{p}(x)}{\\int_x p^\\prime(x,s,u) \\tilde{p}(x) \\mathrm{d}x} \\\\\n", " &\\propto \\underbrace{p(s_{t-1}) \\prod_{k=t}^{t+T} p(x_k|s_k) p(s_k | s_{k-1}, u_k) p(u_k)}_{\\text{original generative model}} \\underbrace{\\tilde{p}(x_k)}_{\\substack{\\text{extension}\\\\\\text{\"goal prior\"}}}\n", "\\end{align*}$$\n", " - $\\tilde{p}(x)$ encodes priors beliefs by the agent about future observations. \n", "\n", "- Goal-directed behavior follows from inference for controls (actions) at $t$, based on expectations (encoded by priors) about future ($>t$) observations.\n", "\n", "- $\\Rightarrow$ Actions fulfill expectations about the future!\n" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### FFG for Active Inference Agent Model\n", "\n", "- After selecting an action $a_t$ and making an observation $y_t$, the FFG for the extended generative model is given by the following FFG:\n", "\n", "

\n", "\n", "- The (brown) dashed box is the agent's Markov blanket. Given the states on the Markov blanket, the internal states of the agent are independent of the state of the world. \n" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### How to minimize FE: Online Active Inference\n", "\n", "- Online active inference proceeds by iteratively executing three stages: (1) act-execute-observe, (2) infer the next control/action, (3) slide forward\n", "\n", "

" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "using Pkg;Pkg.activate(\"probprog/workspace\");Pkg.instantiate()\n", "IJulia.clear_output();" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### The Cart Park Problem Revisited\n", "\n", "Here we solve the cart parking problem as stated at the beginning of this lesson. We first specify a generative model for the agent's environment (which is the observed noisy position of the cart) and then constrain future observations by a prior distribution that is located on the target parking spot. Next, we schedule a message passing-based inference algorithm for the next action. This is followed by executing the \"Act-execute-observe --> infer --> slide\" procedure to infer a sequence of consecutive actions. Finally, the position of the cart over time is plotted. Note that the cart convergees onto the target spot. \n", "\n", "\n" ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "slideshow": { "slide_type": "slide" } }, "outputs": [ { "data": { "image/png": "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", "text/plain": [ "Figure(PyObject
)" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "using PyPlot, LinearAlgebra, ForneyLab\n", "# Load helper functions. Feel free to explore these\n", "include(\"ai_agent/environment_1d.jl\")\n", "include(\"ai_agent/helpers_1d.jl\")\n", "include(\"ai_agent/agent_1d.jl\")\n", "\n", "# Internal model perameters\n", "gamma = 100.0 # Transition precision\n", "phi = 10.0 # Observation precision\n", "upsilon = 1.0 # Control prior variance\n", "sigma = 1.0 # Goal prior variance\n", "\n", "T = 10 # Lookahead\n", "\n", "# Build internal model\n", "fg = FactorGraph()\n", "\n", "o = Vector{Variable}(undef, T) # Observed states\n", "s = Vector{Variable}(undef, T) # internal states\n", "u = Vector{Variable}(undef, T) # Control states\n", "\n", "@RV s_t_min ~ GaussianMeanVariance(placeholder(:m_s_t_min),\n", " placeholder(:v_s_t_min)) # Prior state\n", "u_t = placeholder(:u_t)\n", "@RV u[1] ~ GaussianMeanVariance(u_t, tiny)\n", "@RV s[1] ~ GaussianMeanPrecision(s_t_min + u[1], gamma) \n", "@RV o[1] ~ GaussianMeanPrecision(s[1], phi)\n", "placeholder(o[1], :o_t)\n", "\n", "s_k_min = s[1]\n", "for k=2:T\n", " @RV u[k] ~ GaussianMeanVariance(0.0, upsilon) # Control prior\n", " @RV s[k] ~ GaussianMeanPrecision(s_k_min + u[k], gamma) # State transition model\n", " @RV o[k] ~ GaussianMeanPrecision(s[k], phi) # Observation model\n", " GaussianMeanVariance(o[k], \n", " placeholder(:m_o, var_id=:m_o_*k, index=k-1),\n", " placeholder(:v_o, var_id=:v_o_*k, index=k-1)) # Goal prior\n", " s_k_min = s[k]\n", "end\n", "\n", "# Schedule message passing algorithm\n", "algo = messagePassingAlgorithm(u[2]) # Infer internal states\n", "source_code = algorithmSourceCode(algo)\n", "eval(Meta.parse(source_code)) # Loads the step!() function for inference\n", "\n", "s_0 = 2.0 # Initial State\n", "\n", "N = 20 # Total simulation time\n", "\n", "(execute, observe) = initializeWorld() # Let there be a world\n", "(infer, act, slide) = initializeAgent() # Let there be an agent\n", "\n", "# Step through action-perception loop\n", "u_hat = Vector{Float64}(undef, N) # Actions\n", "o_hat = Vector{Float64}(undef, N) # Observations\n", "for t=1:N\n", " u_hat[t] = act() # Evoke an action from the agent\n", " execute(u_hat[t]) # The action influences hidden external states\n", " o_hat[t] = observe() # Observe the current environmental outcome (update p)\n", " infer(u_hat[t], o_hat[t]) # Infer beliefs from current model state (update q)\n", " slide() # Prepare for next iteration\n", "end\n", "\n", "# Plot active inference results\n", "plotTrajectory(u_hat, o_hat)\n", ";" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Video\n", "\n", "- See [this video to verfiy that the robot will be steered to the correct parking spot even after an \"adversarial\" intervention](https://youtu.be/0ABZJJ9r4Dw) :). (This project was completed by [Burak Ergul](https://biaslab.github.io/member/burak/) as part of this MSc graduation project). \n" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Extensions\n", "\n", "- If interested, here is a link to [a more detailed version of the 1D parking problem](ai_agent/robot_car_1d.ipynb). \n", "\n", "- We also have a [2D version of this cart parking problem implemented on Raspberry Pi-based robot](ai_agent/robot_car_2d.ipynb). (Credits for this implemention to [Thijs van de Laar](https://biaslab.github.io/member/thijs) and [Burak Ergul](https://biaslab.github.io/member/burak)). \n", "\n" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "##
OPTIONAL SLIDES
" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Specification of Free Energy \n", "\n", "- Consider the agent's inference task at time step $t$, right after having selected an action $a_t$ and having made an observation $y_t$.\n", "\n", "- As usual, we record actions and observations by substituting the values into the generative model(in the Act-Execute-Observe phase):\n", "$$\\begin{align*}\n", "p(x,s,u) &\\propto \\underbrace{p(x_t=y_t|s_t)}_{\\text{observation}} p(s_t|s_{t-1},u_t) p(s_{t-1}) \\underbrace{p(u_t=a_t)}_{\\text{action}} \\\\ & \\quad \\cdot \\underbrace{\\prod_{k=t+1}^{t+T} p(x_k|s_k) p(s_k | s_{k-1}, u_k) p(u_k) p^+(x_k)}_{\\text{future}}\n", "\\end{align*}$$\n", "\n", "\n", "- Note that (future) $x$ is also a latent variable and hence we include $x$ in the recognition model. \n", "\n", "- This leads to the following free energy functional\n", "$$\\begin{align*}\n", "F[q] &\\propto \\sum_{x,s,u} q(x,s,u) \\log \\frac{q(x,s,u)}{p(x,s,u)} \n", "\\end{align*}$$" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### FE Decompositions \n", "\n", "- Lots of interesting FE decompositions are possible again. For instance\n", "$$\\begin{align*}\n", "F[q] &\\propto \\sum_{x,s,u} q(x,s,u) \\log \\frac{q(x,s,u)}{p(x,s,u)} \\\\\n", "&= \\sum_{u} q(u) \\underbrace{\\sum_{x,s} q(x,s|u)\\log \\frac{q(x,s|u)}{p(x,s|u)}}_{F_u[q]} + \\underbrace{\\sum_{u} q(u) \\log \\frac{q(u)}{p(u)}}_{\\text{complexity}}\n", "\\end{align*}$$\n", "breaks the FE into a complexity term and a term $F_u[q]$ that is conditioned on the policy $u$. \n", "\n", "- It can be shown (exercise) that the optimal posterior for the policy is now given by\n", "$$\n", "q^*(u) \\propto p(u) \\exp \\left( -F^*_u \\right)\n", "$$\n", "\n", "- Let's consider a break-up $x=(x_t,x_{>t})$ with $x_{>t} = (x_{t+1},\\ldots,x_{t+T})$ that recognizes the distinction between already observed and future data. Then\n", "$$\\begin{align*}\n", "F_u[q] &= \\underbrace{-\\log p(x_t)}_{\\substack{-\\log(\\text{evidence}) \\\\ \\text{(surprise)}}} + \\underbrace{\\sum_{x,s} q(x_{>t},s|u)\\log \\frac{q(x_{>t},s|u)}{p(x_{>t},s|u)}}_{\\substack{\\text{divergence}\\\\ \\text{(inference costs)}}}\\,.\n", "\\end{align*}$$\n", "\n", "- The inference costs (divergence term) can be further decomposed to \n", "$$\\begin{align*} \\underbrace{-\\sum_{x} q(x_{>t}) \\log p(x_{>t})}_{\\substack{\\text{expected surprise} \\\\ \\text{(goal-directed, pragmatic costs)}}} + \\underbrace{\\sum_{x,s} q(x_{>t},s|u) \\log \\frac{q(x_{>t},s|u)}{p(s|x_{>t},u)}}_{\\text{epistemic costs}}\n", "\\end{align*}$$\n", "\n", "- Minimizing goal-directed costs selects actions that (expect to) fullfil the priors over future observations. Minimization of epistemic (\"knowledge seeking\") costs leads to actions that maximize information gain about the environmental dynamics. This can be seen by further decomposition of the epistemic costs into\n", "$$\\begin{align*}\n", "&\\sum_{x,s} q(x_>t,s|u) \\log \\frac{q(s|u)}{p(s|x_{>t},u)} + \\sum_{x,s} q(x_{>t},s|u) \\log q(x_{>t}|s,u) \\\\\n", "\\approx &\\underbrace{\\sum_{x,s} q(x_>t,s|u) \\log \\frac{q(s|u)}{q(s|x_{>t},u)}}_{-\\text{mutual information}} - \\underbrace{\\mathbb{E}_{q(s|u)}\\left[ H\\left[ q(x_{>t}|s,u)\\right]\\right]}_{\\text{ambiguity}} \n", "\\end{align*}$$\n", "where we used the approximation $q(s|x_{>t},u) \\approx p(s|x_{>t},u)$ to illuminate the link to the mutual information. \n", "\n", "- Minimizing FE leads (approximately) to mutual information maximization between internal states $s$ and observations $x$. In other words, FEM leads to actions that aim to seek out observations that are maximally informative about the hidden causes of these observations. \n", "\n", "- Ambiguous states have uncertain mappings to observations. Minimizing FE leads to actions that try to avoid ambiguous states. \n", "\n", "- In short, if the generative model includes variables that represent (yet) unobserved future observations, then action selection by FEM leads to a very sophisticated behavioral strategy that is maximally consistent with \n", " - Bayesian notions of model complexity\n", " - evidence from past observations\n", " - goal-directed imperatives by priors on future observations\n", " - epistemic (knowledge seeking) value maximization, both in terms of MI maximization and avoidance of ambiguous states\n", " \n", "- All these imperatives are simultaneously represented and automatically balanced against each other in a single time-varying cost function (Free Energy) that needs no tuning parameters. \n", "\n", "- (Just to be sure, you don't need to memorize these derivations nor are you expected to derive them on-the-spot. We present these decompositions only to provide insight into the multitude of forces that underlie FEM-based action selection.)\n", "\n" ] }, { "cell_type": "markdown", "metadata": { "slideshow": { "slide_type": "slide" } }, "source": [ "### Free energy distribution in FFG \n", "\n", "\n", "

\n" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "slideshow": { "slide_type": "skip" } }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "open(\"../../styles/aipstyle.html\") do f\n", " display(\"text/html\", read(f,String))\n", "end" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "@webio": { "lastCommId": null, "lastKernelId": null }, "anaconda-cloud": {}, "celltoolbar": "Slideshow", "kernelspec": { "display_name": "Julia 1.5.2", "language": "julia", "name": "julia-1.5" }, "language_info": { "file_extension": ".jl", "mimetype": "application/julia", "name": "julia", "version": "1.5.2" } }, "nbformat": 4, "nbformat_minor": 4 }