{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-input",
     "active-ipynb",
     "remove-output"
    ]
   },
   "outputs": [],
   "source": [
    "try:\n",
    "    from openmdao.utils.notebook_utils import notebook_mode  # noqa: F401\n",
    "except ImportError:\n",
    "    !python -m pip install openmdao[notebooks]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# What is Julia?\n",
    "\n",
    "[Julia](https://julialang.org/) is a new-ish programming language targeting scientific and high-performance computing applications.\n",
    "Like Python or MATLAB, it is a dynamic language—you don't need to declare the types of variables like you would in C, C++, Fortran, etc..\n",
    "Unlike Python, it is a compiled language, as every function is compiled to machine code the first time it is called.\n",
    "The aim of Julia is to provide users with a programming language that combines the convience of Python or MATLAB with the speed of C or Fortran.\n",
    "The [official Julia documentation](https://docs.julialang.org/en/v1/) has [a nice page comparing Julia to other popular languages](https://docs.julialang.org/en/v1/manual/noteworthy-differences/) if you'd like to know more.\n",
    "\n",
    "One of the most attractive features of Julia for OpenMDAO users is its good support for automatic differentiation (AD).\n",
    "There are many (perhaps too many!) AD libraries available for the language, all with particular strengths and weaknesses.\n",
    "Happily, an excellent library called [DifferentiationInterface.jl](https://github.com/JuliaDiff/DifferentiationInterface.jl) exists which allows us to use any of these numerious AD library via a uniform API, which makes switching from one to another a matter of changing just one or two lines of code.\n",
    "\n",
    "# What is OpenMDAO.jl?\n",
    "<div class=\"alert alert-block alert-info\"> \n",
    "<b>NOTE</b> This page is a brief, Python-centric introduction to using Julia within OpenMDAO and OpenMDAO.jl in particular.\n",
    "Please check out <a href=\"https://flow.byu.edu/OpenMDAO.jl/dev/\">the OpenMDAO.jl docs</a> for all the details.\n",
    "</div>\n",
    "\n",
    "[OpenMDAO.jl](https://github.com/byuflowlab/OpenMDAO.jl) is a Python+Julia software package that allows users to create OpenMDAO `Component`s out of Julia code, and optionally use a Julia AD package to differentiate the `Component`.\n",
    "There are currently two possible approaches to using AD with Julia:\n",
    "1. Manual Approach: Users can write the equivalent of a `compute_partials` or `linearize` method in Julia that calls the desired AD library manually. This is quite flexible and conceptually straightforward, but requires more work on the part of the user to manage the complexities of translating the `inputs` and `outputs` vectors OpenMDAO provides to something that the AD library can work with.\n",
    "2. Automatic Approach: Users can write a relatively simple \"callback function\" that implements the math behind the `Component` they wish to create, and allow OpenMDAO.jl to call the AD for them. This is much less work for the user, but does require learning a bit more about the Julia language. This approach is also currently limited to creating `ExplicitComponent`s (though the callback function can contain implicitness via the [ImplicitAD.jl](https://github.com/byuflowlab/ImplicitAD.jl) package).\n",
    "\n",
    "This documentation will focus on approach number 2, the Automatic Approach, which consists of essentially three steps:\n",
    "\n",
    "1. Create a user-defined callback function\n",
    "2. Create an OpenMDAO.jl `AbstractADExplicitComp` `struct` that will keep track the user-defined function, the desired AD library, and other optional features like units, tags, etc..\n",
    "3. Pass the `AbstractADExplicitComp` to omjlcomps (\"OpenMDAO Julia Components\"), a Python library that knows how to create OpenMDAO `Component`s from an OpenMDAO.jl `AbstractADExplicitComp`.\n",
    "\n",
    "After completing those three steps, you'll be left with an OpenMDAO `Component` that you can include anywhere in an OpenMDAO model.\n",
    "We'll go through each of the three steps below. \n",
    "For more details, have a look at the [OpenMDAO.jl docs](https://flow.byu.edu/OpenMDAO.jl/dev/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Guided Tutorial\n",
    "\n",
    "## Step 1: The User-Defined Function\n",
    "The user-defined function *must* follow one of two forms: either it can be an \"in-place\" function that writes its outputs to an output vector, or it can be an \"out-of-place\" function that returns a single output vector.\n",
    "The function must be written in Julia, of course, and anything that happens inside the function is up to you, of course.\n",
    "Both the in-place and out-of-place form must also have a `params` argument that will contain inputs that are needed for the calculation, but won't be differentiated (the equivalent of OpenMDAO `options`).\n",
    "So, an example of an in-place function would be\n",
    "\n",
    "```julia\n",
    "function f_in_place!(Y, X, params)\n",
    "   # calculate stuff with X and params, storing result in Y\n",
    "   return nothing\n",
    "end\n",
    "```\n",
    "\n",
    "where `X` is the input vector and `Y` is the output vector.\n",
    "(The function doesn't have to return `nothing`, but any returned value will be ignored, so I like to include `return nothing` to make it clear that the return value doesn't matter.)\n",
    "An out-of-place function would look like\n",
    "\n",
    "```julia\n",
    "function f_out_of_place(X, params)\n",
    "   # calculate stuff with X and params, returning Y\n",
    "   return Y\n",
    "end\n",
    "```\n",
    "\n",
    "where again `X` is the input vector and `Y` is the output vector.\n",
    "\n",
    "Now, the `X` and `Y` arguments of those functions must not be plain Julia `Vector`s, but `ComponentVectors` from the [ComponentArrays.jl](https://github.com/jonniedie/ComponentArrays.jl) package.\n",
    "What are those?\n",
    "They are objects provided by the [ComponentArrays.jl](https://github.com/SciML/ComponentArrays.jl) package that act like `Vector`s, but allow the user to define names for each part (\"component\") of the vector.\n",
    "For example, we can do this from the Julia REPL:\n",
    "\n",
    "```julia\n",
    "julia> using ComponentArrays: ComponentVector\n",
    "\n",
    "julia> x1 = ComponentVector(foo=-1.0, bar=-2.0, baz=-3.0)\n",
    "ComponentVector{Float64}(foo = -1.0, bar = -2.0, baz = -3.0)\n",
    "\n",
    "julia> @show x1 x1[3] x1.foo x1[:foo]\n",
    "x1 = (foo = -1.0, bar = -2.0, baz = -3.0)\n",
    "x1[3] = -3.0\n",
    "x1.foo = -1.0\n",
    "x1[:foo] = -1.0\n",
    "-1.0\n",
    "\n",
    "julia> \n",
    "```\n",
    "\n",
    "Notice that we can get, say, the third value of `x1` the usual way (`x1[3]`), but also by referring to the `foo` field value via `x1.foo` and by indexing the `ComponentVector` with the symbol `:foo` (`x1[:foo]`).\n",
    "\n",
    "Each of the components in `x1` are scalars, but they don't have to be:\n",
    "\n",
    "```julia\n",
    "julia> x2 = ComponentVector(foo=-1.0, bar=1:4, baz=reshape(5:10, 2, 3))\n",
    "ComponentVector{Float64}(foo = -1.0, bar = [1.0, 2.0, 3.0, 4.0], baz = [5.0 7.0 9.0; 6.0 8.0 10.0])\n",
    "\n",
    "julia> @show x2 x2[:foo] x2[:bar] x2[:baz]\n",
    "x2 = (foo = -1.0, bar = [1.0, 2.0, 3.0, 4.0], baz = [5.0 7.0 9.0; 6.0 8.0 10.0])\n",
    "x2[:foo] = -1.0\n",
    "x2[:bar] = [1.0, 2.0, 3.0, 4.0]\n",
    "x2[:baz] = [5.0 7.0 9.0; 6.0 8.0 10.0]\n",
    "2×3 Matrix{Float64}:\n",
    " 5.0  7.0   9.0\n",
    " 6.0  8.0  10.0\n",
    "\n",
    "julia> \n",
    "```\n",
    "\n",
    "In `x2`, the `foo` component is a scalar, `bar` refers to a `Vector` (aka a 1D `Array`) and `baz` refers to a `Matrix` (aka a 2D Array).\n",
    "But `x2` still \"looks like\" a `Vector`:\n",
    "\n",
    "```julia\n",
    "julia> @show x2[3]  # will give the third value of `x2`, which happens to be the second value of x2[:bar]\n",
    "x2[3] = 2.0\n",
    "2.0\n",
    "\n",
    "julia> @show ndims(x2)  # Should be 1, since a Vector is 1-dimensional\n",
    "ndims(x2) = 1\n",
    "1\n",
    "\n",
    "julia> @show length(x2)  # length(x2) gives the total number of entries in `x2`, aka 1 + 4 + 2*3 = 11\n",
    "length(x2) = 11\n",
    "11\n",
    "\n",
    "julia> @show size(x2)  # size is a length-1 tuple since a Vector has just one dimension\n",
    "size(x2) = (11,)\n",
    "(11,)\n",
    "\n",
    "julia> \n",
    "```\n",
    "\n",
    "Now, how will we use `ComponentVector`s here?\n",
    "We'll use them to define the names and sizes of all the inputs and outputs to our component.\n",
    "For example, if we wanted to implement [the Paraboloid Example](../../basic_user_guide/single_disciplinary_optimization/first_analysis), which minimizes the function\n",
    "\n",
    "$$\n",
    "f(x,y) = (x-3.0)^2 + x \\cdot y + (y+4.0)^2 - 3.0\n",
    "$$\n",
    "\n",
    "using OpenMDAO.jl, we could create an input vector called `X_ca` that looks like this:\n",
    "\n",
    "```julia\n",
    "julia> X_ca = ComponentVector(x=1.0, y=1.0)\n",
    "ComponentVector{Float64}(x = 1.0, y = 1.0)\n",
    "\n",
    "julia> \n",
    "```\n",
    "\n",
    "That has two scalar components, `x` and `y`, that correspond to the two inputs to the paraboloid function.\n",
    "We could similarly use an output vector `Y_ca` that looks like this:\n",
    "\n",
    "```julia\n",
    "julia> Y_ca = ComponentVector(f_xy=0.0)\n",
    "ComponentVector{Float64}(f_xy = 0.0)\n",
    "\n",
    "julia> \n",
    "```\n",
    "\n",
    "with the single output `f_xy`.\n",
    "\n",
    "We could type in a callback function that implements the paraboloid equation above into the REPL if we want:\n",
    "\n",
    "```julia\n",
    "julia> function f_paraboloid!(Y, X, params)\n",
    "           # Get the inputs:\n",
    "           x = @view(X[:x])\n",
    "           y = @view(X[:y])\n",
    "           # Could also do this:\n",
    "           # x = X.x\n",
    "           # y = X.y\n",
    "           # or even this\n",
    "           # (; x, y) = X\n",
    "\n",
    "           # Get the output:\n",
    "           f_xy = @view(Y[:f_xy])\n",
    "           # Again, could also do this:\n",
    "           # f_xy = Y.f_xy\n",
    "           # or\n",
    "           # (; f_xy) = Y\n",
    "\n",
    "           # Do the calculation:\n",
    "           @. f_xy = (x - 3.0)^2 + x*y + (y + 4.0)^2 - 3.0\n",
    "\n",
    "           # No return value for in-place callback function.\n",
    "           return nothing\n",
    "       end\n",
    "f_paraboloid! (generic function with 1 method)\n",
    "\n",
    "julia> \n",
    "```\n",
    "\n",
    "And then test it out with the `X_ca` and `Y_ca` `ComponentVector`s we created earlier:\n",
    "\n",
    "```julia\n",
    "julia> f_paraboloid!(Y_ca, X_ca, nothing)\n",
    "\n",
    "julia> X_ca\n",
    "ComponentVector{Float64}(x = 1.0, y = 1.0)\n",
    "\n",
    "julia> Y_ca\n",
    "ComponentVector{Float64}(f_xy = 27.0)\n",
    "\n",
    "julia> \n",
    "```\n",
    "\n",
    "Some remarks about the callback function:\n",
    "\n",
    "* The `@view` macro is used when extracting the inputs and outputs from the `X_ca` and `Y_ca` `ComponentVectors`. This creates a view into the original ComponentVector, instead of a new array with a copy of the original data, which avoids unnecessary allocations and (for the outputs) allows modifications to the view to be reflected in the `Y_ca` array. In this example everything is a scalar, so no allocations would have happened anyway. But it doesn't hurt to use `@view`: it's a good habit to get into, and it allows us to use the `@.` broadcasting macro with the scalar `f_xy` output.\n",
    "* The `params` argument is not used in this example, but it is still required, since the code in OpenMDAO.jl will expect it. We provided a `nothing` value for it, but we could have given it anything and not changed the result of the function, of course.\n",
    "\n",
    "An out-of-place version of `f_paraboloid!` would look like this:\n",
    "\n",
    "```julia\n",
    "julia> function f_paraboloid(X, params)\n",
    "           x = @view(X[:x])\n",
    "           y = @view(X[:y])\n",
    "           f_xy = @. (x - 3.0)^2 + x*y + (y + 4.0)^2 - 3.0\n",
    "           return ComponentVector(f_xy=f_xy)\n",
    "       end\n",
    "f_paraboloid (generic function with 1 method)\n",
    "\n",
    "julia> f_paraboloid(X_ca, nothing)\n",
    "ComponentVector{Float64}(f_xy = 27.0)\n",
    "\n",
    "julia> \n",
    "```\n",
    "\n",
    "But we only need one or the other."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: The OpenMDAO.jl `AbstractADExplicitComp`\n",
    "So far we've done a lot of typing in the Julia REPL, which is great for testing, but not great for writing code that you'll use more than once.\n",
    "Where should we store this Julia code that we're creating, and how will we call it from Python?\n",
    "This section will explain my favorite way to do that.\n",
    "Along the way we'll learn how to choose a Julia AD library, and create an `AbstractADExplicitComp` that will eventually be used to instantiate an `ExplicitComponent` that can be added to a OpenMDAO model.\n",
    "\n",
    "### A Julia Package for our Paraboloid\n",
    "We'll store our Julia code for the paraboloid component in a brand new Julia package called MyParaboloidPackage.\n",
    "Creating a new Julia package is very easy from the REPL: just type `]` to enter the [Pkg REPL](https://pkgdocs.julialang.org/v1/repl/) (look for the `pkg>` in the prompt to ensure you're in \"Pkg mode\"), then type `generate MyParaboloidPackage` to create the package:\n",
    "\n",
    "```julia\n",
    "(openmdao_jl_dev) pkg> generate MyParaboloidPackage\n",
    "  Generating  project MyParaboloidPackage:\n",
    "    MyParaboloidPackage/Project.toml\n",
    "    MyParaboloidPackage/src/MyParaboloidPackage.jl\n",
    "\n",
    "(openmdao_jl_dev) pkg> \n",
    "```\n",
    "\n",
    "(Keep this REPL open, as we'll be using it again later.)\n",
    "As the output suggests, running that command creates a directory called `MyParaboloidPackage` in the current working directory, along with two files.\n",
    "The `Project.toml` file contains metadata about the Julia project (name, version number, a UUID to distinguish it from other Julia packages, dependencies, etc.).\n",
    "The `src/MyParaboloidPackage.jl` contains the source code of the package, and at the moment looks like this:\n",
    "\n",
    "```julia\n",
    "module MyParaboloidPackage\n",
    "\n",
    "greet() = print(\"Hello World!\")\n",
    "\n",
    "end # module MyParaboloidPackage\n",
    "```\n",
    "\n",
    "We'll put our paraboloid code in `src/MyParaboloidPackage.jl` by copy-pasting the definition of `f_paraboloid!` into the file.\n",
    "Now it should look like this (with the `greet` function removed):\n",
    "\n",
    "```julia\n",
    "module MyParaboloidPackage\n",
    "\n",
    "function f_paraboloid!(Y, X, params)\n",
    "    x = @view(X[:x])\n",
    "    y = @view(X[:y])\n",
    "    f_xy = @view(Y[:f_xy])\n",
    "    @. f_xy = (x - 3.0)^2 + x*y + (y + 4.0)^2 - 3.0\n",
    "    return nothing\n",
    "end\n",
    "\n",
    "end # module MyParaboloidPackage\n",
    "```\n",
    "\n",
    "Now, let's see if we can create that `AbstractADExplicitComp` that we've been talking about.\n",
    "There are a few different flavors of `AbstractADExplicitComp` `struct`s that we could use, but for this example, we'll use `DenseADExplicitComp`, one that's designed for explicit components with a dense Jacobian.\n",
    "If we check out the [documentation for `DenseADExplicitComp` constructor](https://flow.byu.edu/OpenMDAO.jl/dev/reference/#OpenMDAOCore.DenseADExplicitComp-Union{Tuple{TAD},%20Tuple{TAD,%20Any,%20ComponentArrays.ComponentVector,%20ComponentArrays.ComponentVector}}%20where%20TAD%3C:ADTypes.AbstractADType), we'll see that we need four things to get this done:\n",
    "\n",
    "* An `ad_backend`, to be explained shortly\n",
    "* A callback function `f!`\n",
    "* `Y_ca`, a `ComponentVector` of outputs\n",
    "* `X_ca`, a `ComponentVector` of inputs\n",
    "\n",
    "In the previous section we learned how to create `X_ca` and `Y_ca`, and our callback function `f!` will be the `f_paraboloid!`.\n",
    "So the only missing ingrediant is the `ad_backend`.\n",
    "\n",
    "The `ad_backend` is a Julia object that will tell the `DenseADExplicitComp` which AD library we want to use to differentiate our component.\n",
    "The object must be a subtype of `AbstractADType`, an abstract type provided by the [ADTypes.jl](https://github.com/SciML/ADTypes.jl) package.\n",
    "That package is not part of the Julia Standard Library, so we'll need to install it.\n",
    "How do we do that?\n",
    "The easiest way is from the Julia Pkg REPL, aka the thing we used to generate the `MyParaboloidPackage` earlier.\n",
    "First, type `]` to ensure we're in the Pkg REPL (again, look for `pkg>` in the prompt), then do this:\n",
    "\n",
    "```\n",
    "(openmdao_jl_dev) pkg> activate ./MyParaboloidPackage\n",
    "  Activating project at `~/projects/openmdao_jl_dev/ved/OpenMDAO/openmdao/docs/openmdao_book/features/experimental/MyParaboloidPackage`\n",
    "\n",
    "(MyParaboloidPackage) pkg> \n",
    "```\n",
    "\n",
    "That \"activates\" the environment associated with MyParaboloidPackage, which tells the Julia Pkg package manager that we want to mess around with the dependencies of it and not some other environment or package.\n",
    "(The Pkg REPL reminds us which environment is \"active\" by changing the prompt to `(MyParaboloidPackage) pkg>`.) \n",
    "We can check the status of MyParaboloidPackage via the `status` command:\n",
    "\n",
    "```julia\n",
    "(MyParaboloidPackage) pkg> status\n",
    "Project MyParaboloidPackage v0.1.0\n",
    "Status `~/projects/openmdao_jl_dev/ved/OpenMDAO/openmdao/docs/openmdao_book/features/experimental/MyParaboloidPackage/Project.toml` (empty project)\n",
    "\n",
    "(MyParaboloidPackage) pkg> \n",
    "```\n",
    "\n",
    "Unsuprisingly there isn't much going on with it yet.\n",
    "\n",
    "The next step is to add the dependencies we need.\n",
    "We've already decided that we want ADTypes.jl, but we'll also need:\n",
    "\n",
    "* ComponentArrays.jl: for the `ComponentVector`s we'll provide to the `DenseADExplicitComp` constructor\n",
    "* OpenMDAOCore.jl: for the `DenseADExplicitComp` itself\n",
    "* ForwardDiff.jl: a forward-mode AD library that we'll use for this example\n",
    "\n",
    "So, let's install those using the `add` command from the Pkg REPL:\n",
    "\n",
    "```julia\n",
    "(MyParaboloidPackage) pkg> add ADTypes ComponentArrays OpenMDAOCore ForwardDiff\n",
    "   Resolving package versions...\n",
    "   Installed DifferentiationInterface ─ v0.7.14\n",
    "      Compat entries added for ADTypes, ComponentArrays, OpenMDAOCore, ForwardDiff\n",
    "    Updating `~/projects/openmdao_jl_dev/ved/OpenMDAO/openmdao/docs/openmdao_book/features/experimental/MyParaboloidPackage/Project.toml`\n",
    "  [47edcb42] + ADTypes v1.21.0\n",
    "  [b0b7db55] + ComponentArrays v0.15.31\n",
    "  [f6369f11] + ForwardDiff v1.3.1\n",
    "  [24d19c10] + OpenMDAOCore v0.3.3\n",
    "    Updating `~/projects/openmdao_jl_dev/ved/OpenMDAO/openmdao/docs/openmdao_book/features/experimental/MyParaboloidPackage/Manifest.toml`\n",
    "\n",
    "# Lots of output removed for clarity\n",
    "(MyParaboloidPackage) pkg> \n",
    "```\n",
    "\n",
    "Now if we try the `status` command again, we'll see this:\n",
    "\n",
    "```julia\n",
    "(MyParaboloidPackage) pkg> status\n",
    "Project MyParaboloidPackage v0.1.0\n",
    "Status `~/projects/openmdao_jl_dev/ved/OpenMDAO/openmdao/docs/openmdao_book/features/experimental/MyParaboloidPackage/Project.toml`\n",
    "  [47edcb42] ADTypes v1.21.0\n",
    "  [b0b7db55] ComponentArrays v0.15.31\n",
    "  [f6369f11] ForwardDiff v1.3.1\n",
    "  [24d19c10] OpenMDAOCore v0.3.3\n",
    "\n",
    "(MyParaboloidPackage) pkg> \n",
    "```\n",
    "\n",
    "That shows the dependencies of `MyParaboloidPackage`, and their version numbers.\n",
    "Excellent.\n",
    "\n",
    "Now we should have everything we need to create the `DenseADExplicitComp`.\n",
    "I think it's easiest to create a small \"helper function\" that we can call later that returns our `DenseADExplicitComp` that looks like this:\n",
    "\n",
    "```julia\n",
    "function get_paraboloid_comp()\n",
    "    ad_backend = ADTypes.AutoForwardDiff()\n",
    "    X_ca = ComponentVector(x=1.0, y=1.0)\n",
    "    Y_ca = ComponentVector(f_xy=0.0)\n",
    "    comp = OpenMDAOCore.DenseADExplicitComp(ad_backend, f_paraboloid!, Y_ca, X_ca)\n",
    "    return comp\n",
    "end\n",
    "```\n",
    "\n",
    "The `ADTypes.AutoForwardDiff()` means that we'll use [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl), a forward-mode AD package, to differentiate our paraboloid.\n",
    "\n",
    "We'll add that function to `src/MyParaboloidPackage.jl`, along with some import statements that give us access to the packages we just installed.\n",
    "So now it should look like this:\n",
    "\n",
    "```julia\n",
    "module MyParaboloidPackage\n",
    "\n",
    "using ADTypes: ADTypes\n",
    "using ComponentArrays: ComponentVector\n",
    "using ForwardDiff: ForwardDiff\n",
    "using OpenMDAOCore: OpenMDAOCore\n",
    "\n",
    "function f_paraboloid!(Y, X, params)\n",
    "    x = @view(X[:x])\n",
    "    y = @view(X[:y])\n",
    "    f_xy = @view(Y[:f_xy])\n",
    "    @. f_xy = (x - 3.0)^2 + x*y + (y + 4.0)^2 - 3.0\n",
    "    return nothing\n",
    "end\n",
    "\n",
    "function get_paraboloid_comp()\n",
    "    ad_backend = ADTypes.AutoForwardDiff()\n",
    "    X_ca = ComponentVector(x=1.0, y=1.0)\n",
    "    Y_ca = ComponentVector(f_xy=0.0)\n",
    "    comp = OpenMDAOCore.DenseADExplicitComp(ad_backend, f_paraboloid!, Y_ca, X_ca)\n",
    "    return comp\n",
    "end\n",
    "\n",
    "end # module MyParaboloidPackage\n",
    "```\n",
    "\n",
    "We can try out the `get_paraboloid_comp` function from the normal Julia REPL (not the Pkg REPL—just backspace until you get the `julia> ` prompt back):\n",
    "\n",
    "```julia\n",
    "julia> using MyParaboloidPackage\n",
    "\n",
    "julia> comp = MyParaboloidPackage.get_paraboloid_comp()\n",
    "```\n",
    "\n",
    "You'll probibly see a bunch of output describing in excruciating detail all the type information associated with the `DenseADExplicitComp` we just created.\n",
    "But as long as you see something that starts with `OpenMDAOCore.DenseADExplicitComp`, we should be good.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: The `omjlcomps.JuliaExplicitComp`\n",
    "So far we have created a Julia callback function and a `DenseADExplicitComp` for our paraboloid.\n",
    "The last step is to turn that `DenseADExplicitComp` into something we can actually incorporate into an OpenMDAO model.\n",
    "We'll do that using omjlcomps, a Python package that's part of OpenMDAO.jl.\n",
    "\n",
    "But first, we need to figure out a nice way of telling Python about our Julia code.\n",
    "The best way of doing that is using [juliapkg](https://github.com/JuliaPy/pyjuliapkg), a Python package that allows us to add Julia dependencies to a Python package.\n",
    "We could install it manually ourselves using `pip install juliapkg`, but if instead we install OpenMDAO with the \"julia\" extra, we'll get it automatically:\n",
    "\n",
    "```bash\n",
    "$ pip install openmdao[julia]\n",
    "```\n",
    "\n",
    "We'll do that from here in a Jupyter notebook using this command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install openmdao[julia]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we need to use juliapkg to tell our Python environment about MyParaboloidPackage.\n",
    "We do that by creating a file called `juliapkg.json` in our working directory that points to MyParaboloidPackage:\n",
    "\n",
    "```json\n",
    "{\"packages\": {\n",
    "    \"MyParaboloidPackage\": {\"uuid\": \"a013c6e3-dc76-40b3-894d-62618f778e16\", \"dev\": true, \"path\": \"./MyParaboloidPackage\"}\n",
    "    }\n",
    "}\n",
    "```\n",
    "\n",
    "(To get the correct value for the `\"uuid\"` field, copy what's in the `MyParaboloidPackage/Project.toml` file.\n",
    "It will be different from what is listed above if you're trying out these commands yourself.)\n",
    "\n",
    "That tells juliapkg about MyParaboloidPackage.\n",
    "The `\"dev\": true` means that the package will be installed in \"develop\" mode, meaning any changes in the package will be reflected in code that calls it—it's the equivalent of `pip install -e` or `pip install --editable` in Python.\n",
    "\n",
    "`juliapkg` searches for `juliapkg.json` files in, among other places, each entry in `sys.path`.\n",
    "This is great for adding Julia dependencies to Python packages: you can add a `juliapkg.json` to your Python source, and `juliapkg` will find it automatically if your Python package is installed in the current environment.\n",
    "It also works well for Python scripts run from the command line: since Python automatically adds the directory of the script to `sys.path`, we could place the `juliapkg.json` file in the same directory as the run script and it should also be found by `juliapkg`.\n",
    "But it's not-so-great for Jupyter notebooks like this one.\n",
    "So we'll have to manually add what we think is the current working directory to `sys.path` and cross our fingers.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import sys\n",
    "d = os.getcwd()\n",
    "sys.path.append(d)\n",
    "print(sys.path[-1])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we'll create a small julia file in the current working directory that will import the `get_paraboloid_comp` function that we just added to `MyParaboloidPackage` called `paraboloid.jl`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import display, Code\n",
    "display(Code(os.path.join(d, \"paraboloid.jl\")))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we'll create another small file, this time a Python one, called `paraboloid.py` that will include that `paraboloid.jl` julia file using JuliaCall, a Python package for calling Julia code that was automatically installed when we did `pip install openmdao[julia]`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "display(Code(os.path.join(d, \"paraboloid.py\")))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we should be able to use omjlcomps (another Python package that was installed as a side effect of `pip install openmdao[julia]`) to create a `JuliaExplicitComp`.\n",
    "We do this by first calling `get_paraboloid_comp` to get the `DenseADExplicitComp` `struct` we created, then pass it as the `jlcomp` argument to `JuliaExplicitComp`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import omjlcomps\n",
    "from paraboloid import get_paraboloid_comp\n",
    "jlcomp = get_paraboloid_comp()\n",
    "comp = omjlcomps.JuliaExplicitComp(jlcomp=jlcomp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we have a OpenMDAO `Component` that we can use.\n",
    "Let's try it out, following the [Paraboloid example](../../basic_user_guide/single_disciplinary_optimization/first_analysis) from the OpenMDAO docs:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import openmdao.api as om\n",
    "\n",
    "model = om.Group()\n",
    "model.add_subsystem('parab_comp', comp)\n",
    "\n",
    "prob = om.Problem(model)\n",
    "\n",
    "prob.model.add_design_var(\"parab_comp.x\")\n",
    "prob.model.add_design_var(\"parab_comp.y\")\n",
    "prob.model.add_objective(\"parab_comp.f_xy\")\n",
    "\n",
    "prob.driver = om.ScipyOptimizeDriver()\n",
    "prob.driver.options[\"optimizer\"] = \"SLSQP\"\n",
    "\n",
    "prob.setup(force_alloc_complex=True)\n",
    "\n",
    "prob.set_val(\"parab_comp.x\", 3.0)\n",
    "prob.set_val(\"parab_comp.y\", -4.0)\n",
    "\n",
    "prob.run_model()\n",
    "print(prob[\"parab_comp.f_xy\"])  # Should print `[-15.]`\n",
    "\n",
    "prob.set_val(\"parab_comp.x\", 5.0)\n",
    "prob.set_val(\"parab_comp.y\", -2.0)\n",
    "\n",
    "prob.run_model()\n",
    "print(prob.get_val(\"parab_comp.f_xy\"))  # Should print `[-5.]`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Looks good so far.\n",
    "A few things to note:\n",
    "* We added the `JuliaExplicitComp` to the `Group` in the normal way.\n",
    "* The variable names exposed to OpenMDAO match what was used in the input and output `ComponentVector`s passed to the `DenseADExplicitComp` constructor.\n",
    "* `prob.set_val` and `prob.get_val` worked just like usual.\n",
    "\n",
    "We can also check our derivatives using the usual OpenMDAO methods. We can do that with the finite difference method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(prob.check_partials(method=\"fd\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or we could use the complex-step method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(prob.check_partials(method=\"cs\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The derivatives look great, so let's try an optimization:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "prob.run_driver()\n",
    "print(f\"f_xy = {prob.get_val('parab_comp.f_xy')}\")  # Should print `[-27.333333]`\n",
    "print(f\"x = {prob.get_val('parab_comp.x')}\")  # Should print `[6.666666]`\n",
    "print(f\"y = {prob.get_val('parab_comp.y')}\")  # Should print `[-7.333333]`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Victory!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Next Steps\n",
    "We've shown how to put together a simple OpenMDAO `Component` using Julia and OpenMDAO.jl.\n",
    "OpenMDAO.jl has more features that you can [explore in docs](https://flow.byu.edu/OpenMDAO.jl/dev/).\n",
    "Some things we haven't covered:\n",
    "* We didn't define any units or tags for our Paraboloid example, but OpenMDAO.jl does support those features. Check out the [Brachistochrone example](https://flow.byu.edu/OpenMDAO.jl/dev/auto_sparse_ad/#The-Brachistochrone-with-SparseADExplicitComp) to see how that is done.\n",
    "* OpenMDAO.jl also supports determining variable shapes at runtime (aka the `copy_shape` and `shape_by_conn` arguments to `add_input` and `add_output`). Currently an example of using those features doesn't exist for the various AD methods, but the [docstring for `DenseADExplicitComp` and friends](https://flow.byu.edu/OpenMDAO.jl/dev/reference/#OpenMDAOCore.DenseADExplicitComp-Union{Tuple{TAD},%20Tuple{TAD,%20Any,%20ComponentArrays.ComponentVector,%20ComponentArrays.ComponentVector}}%20where%20TAD%3C:ADTypes.AbstractADType) should show you how to do it. \n",
    "* We just used one AD package in the example above (ForwardDiff.jl), but there are many more. Check out the [ADTypes.jl documentation](https://docs.sciml.ai/ADTypes/stable/) for all the possible options.\n",
    "* We used the `DenseADExplicitComp` `struct` to create our Paraboloid component, which is the most appropriate for a component with a dense Jacobian. But OpenMDAO.jl can also create components that evaluate the derivatives using the [matrix-free approach](https://flow.byu.edu/OpenMDAO.jl/dev/matrix_free_ad/), or [accelerate the calculation of sparse Jacobians using coloring algorithms](https://flow.byu.edu/OpenMDAO.jl/dev/auto_sparse_ad/).\n",
    "* The OpenMDAO.jl docs also have [recommendations on how to create Python packages that contain Julia OpenMDAO components](https://flow.byu.edu/OpenMDAO.jl/dev/creating_python_packages/) that you should definitely check out if you plan on using OpenMDAO.jl for \"real work.\" There is also an example Python package that follows these guidelines in the GitHub repository.\n",
    "* In the aformentioned example Python package in the OpenMDAO.jl GitHub repository there is an example of using OpenMDAO.jl and [ImplicitAD.jl](https://github.com/byuflowlab/ImplicitAD.jl) to solve [the nonlinear circuit example from the OpenMDAO docs](../../advanced_user_guide/models_implicit_components/models_with_solvers_implicit). This shows how we can use OpenMDAO.jl to efficiently differentiate through an implicit calculation with a little help from ImplicitAD.jl."
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.7"
  },
  "orphan": true
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
