{
 "cells": [
  {
   "cell_type": "markdown",
   "source": [
    "# 1.1: First steps in Trixi.jl: Getting started"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "**Note:** To improve responsiveness via caching, the notebooks are updated only once a week. They are only\n",
    "available for the latest stable release of Trixi.jl at the time of caching."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Trixi.jl is a numerical simulation framework for conservation laws and\n",
    "is written in the [Julia programming language](https://julialang.org/).\n",
    "This tutorial is intended for beginners in Julia and Trixi.jl.\n",
    "After reading it, you will know how to install Julia and Trixi.jl on your computer,\n",
    "and you will be able to download setup files from our GitHub repository, modify them,\n",
    "and run simulations."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "The contents of this tutorial:\n",
    "- Julia installation\n",
    "- Trixi.jl installation\n",
    "- Running a simulation\n",
    "- Getting an existing setup file\n",
    "- Modifying an existing setup"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Julia installation"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Trixi.jl is compatible with the latest stable release of Julia. Additional details regarding Julia\n",
    "support can be found in the [`README.md`](https://github.com/trixi-framework/Trixi.jl#installation)\n",
    "file. After installation, the current default Julia version can be managed through the command\n",
    "line tool `juliaup`. You may follow our concise installation guidelines for Windows, Linux, and\n",
    "MacOS provided below. In the event of any issues during the installation process, please consult\n",
    "the official [Julia installation instruction](https://julialang.org/downloads/)."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Windows"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "- Open a terminal by pressing `Win+r` and entering `cmd` in the opened window.\n",
    "- To install Julia, execute the following command in the terminal:\n",
    "  ```shell\n",
    "  winget install julia -s msstore\n",
    "  ```\n",
    "  Note: For this installation an MS Store account is necessary to proceed.\n",
    "- Verify the successful installation of Julia by executing the following command in the terminal:\n",
    "  ```shell\n",
    "  julia\n",
    "  ```\n",
    "  To exit Julia, execute `exit()` or press `Ctrl+d`."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Linux and MacOS"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "- To install Julia, run the following command in a terminal:\n",
    "  ```shell\n",
    "  curl -fsSL https://install.julialang.org | sh\n",
    "  ```\n",
    "  Follow the instructions displayed in the terminal during the installation process.\n",
    "- If an error occurs during the execution of the previous command, you may need to install\n",
    "  `curl`. On Ubuntu-type systems, you can use the following command:\n",
    "  ```shell\n",
    "  sudo apt install curl\n",
    "  ```\n",
    "  After installing `curl`, repeat the first step once more to proceed with Julia installation.\n",
    "- Verify the successful installation of Julia by executing the following command in the terminal:\n",
    "  ```shell\n",
    "  julia\n",
    "  ```\n",
    "  To exit Julia, execute `exit()` or press `Ctrl+d`."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Trixi.jl installation"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Trixi.jl and its related tools are registered Julia packages, thus their installation\n",
    "happens inside Julia.\n",
    "For a smooth workflow experience with Trixi.jl, you need to install\n",
    "[Trixi.jl](https://github.com/trixi-framework/Trixi.jl),\n",
    "[OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl), and\n",
    "[Plots.jl](https://github.com/JuliaPlots/Plots.jl)."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "- Open a terminal and start Julia.\n",
    "- Execute the following commands to install all mentioned packages. Please note that the\n",
    "  installation process involves downloading and precompiling the source code, which may take\n",
    "  some time depending on your machine.\n",
    "  ```julia\n",
    "  import Pkg\n",
    "  Pkg.add([\"OrdinaryDiffEq\", \"Plots\", \"Trixi\"])\n",
    "  ```\n",
    "- On Windows, the firewall may request permission to install packages."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Besides Trixi.jl you have now installed two additional\n",
    "packages: [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) provides time\n",
    "integration schemes used by Trixi.jl and [Plots.jl](https://github.com/JuliaPlots/Plots.jl)\n",
    "can be used to directly visualize Trixi.jl results from the Julia REPL."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "## Usage"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Running a simulation"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "To get you started, Trixi.jl has a large set\n",
    "of [example setups](https://github.com/trixi-framework/Trixi.jl/tree/main/examples), that can be\n",
    "taken as a basis for your future investigations. In Trixi.jl, we call these setup files\n",
    "\"elixirs\", since they contain Julia code that takes parts of Trixi.jl and combines them into\n",
    "something new."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Any of the examples can be executed using the `trixi_include`\n",
    "function. `trixi_include(...)` expects\n",
    "a single string argument with a path to a file containing Julia code.\n",
    "For convenience, the `examples_dir` function returns a path to the\n",
    "[`examples`](https://github.com/trixi-framework/Trixi.jl/tree/main/examples)\n",
    "folder, which has been locally downloaded while installing Trixi.jl.\n",
    "`joinpath(...)` can be used to join path components into a full path."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Let's execute a short two-dimensional problem setup. It approximates the solution of\n",
    "the compressible Euler equations in 2D for an ideal gas (`CompressibleEulerEquations2D`)\n",
    "with a weak blast wave as the initial condition and periodic boundary conditions."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "The compressible Euler equations in two spatial dimensions are given by\n",
    "$$\n",
    "\\frac{\\partial}{\\partial t}\n",
    "\\begin{pmatrix}\n",
    "\\rho \\\\ \\rho v_1 \\\\ \\rho v_2 \\\\ \\rho e\n",
    "\\end{pmatrix}\n",
    "+\n",
    "\\frac{\\partial}{\\partial x}\n",
    "\\begin{pmatrix}\n",
    "\\rho v_1 \\\\ \\rho v_1^2 + p \\\\ \\rho v_1 v_2 \\\\ (\\rho e + p) v_1\n",
    "\\end{pmatrix}\n",
    "+\n",
    "\\frac{\\partial}{\\partial y}\n",
    "\\begin{pmatrix}\n",
    "\\rho v_2 \\\\ \\rho v_1 v_2 \\\\ \\rho v_2^2 + p \\\\ (\\rho e + p) v_2\n",
    "\\end{pmatrix}\n",
    "=\n",
    "\\begin{pmatrix}\n",
    "0 \\\\ 0 \\\\ 0 \\\\ 0\n",
    "\\end{pmatrix},\n",
    "$$\n",
    "for an ideal gas with the specific heat ratio $\\gamma$.\n",
    "Here, $\\rho$ is the density, $v_1$ and $v_2$ are the velocities, $e$ is the specific\n",
    "total energy, and\n",
    "$$\n",
    "p = (\\gamma - 1) \\left( \\rho e - \\frac{1}{2} \\rho (v_1^2 + v_2^2) \\right)\n",
    "$$\n",
    "is the pressure."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "The `initial_condition_weak_blast_wave` is specified in\n",
    "[`compressible_euler_2d.jl`](https://github.com/trixi-framework/Trixi.jl/blob/main/src/equations/compressible_euler_2d.jl)"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Start Julia in a terminal and execute the following code:"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "```julia\n",
    "using Trixi, OrdinaryDiffEq\n",
    "trixi_include(joinpath(examples_dir(), \"tree_2d_dgsem\", \"elixir_euler_ec.jl\"))\n",
    "```"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "The output contains a recap of the setup and various information about the course of the simulation.\n",
    "For instance, the solution was approximated over the `TreeMesh` with 1024 effective cells using\n",
    "the `CarpenterKennedy2N54` ODE\n",
    "solver. Further details about the ODE solver can be found in the\n",
    "[documentation of OrdinaryDiffEq.jl](https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/#Low-Storage-Methods)"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "To analyze the result of the computation, we can use the Plots.jl package and the function\n",
    "`plot(...)`, which creates a graphical representation of the solution. `sol` is a variable\n",
    "defined in the executed example and it contains the solution after the simulation\n",
    "finishes. `sol.u` holds the vector of values at each saved timestep, while `sol.t` holds the\n",
    "corresponding times for each saved timestep. In this instance, only two timesteps were saved: the\n",
    "initial and final ones. The plot depicts the distribution of the weak blast wave at the final moment\n",
    "of time, showing the density, velocities, and pressure of the ideal gas across a 2D domain."
   ],
   "metadata": {}
  },
  {
   "outputs": [],
   "cell_type": "code",
   "source": [
    "using Plots\n",
    "plot(sol)"
   ],
   "metadata": {},
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Getting an existing setup file"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "To obtain a list of all Trixi.jl elixirs execute\n",
    "`get_examples`. It returns the paths to all example setups."
   ],
   "metadata": {}
  },
  {
   "outputs": [],
   "cell_type": "code",
   "source": [
    "get_examples()"
   ],
   "metadata": {},
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "source": [
    "Editing an existing elixir is the best way to start your first own investigation using Trixi.jl."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "To edit an existing elixir, you first have to find a suitable one and then copy it to a local\n",
    "folder. Let's have a look at how to download the `elixir_euler_ec.jl` elixir used in the previous\n",
    "section from the [Trixi.jl GitHub repository](https://github.com/trixi-framework/Trixi.jl)."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "- All examples are located inside\n",
    "  the [`examples`](https://github.com/trixi-framework/Trixi.jl/tree/main/examples) folder.\n",
    "- Navigate to the\n",
    "  file [`elixir_euler_ec.jl`](https://github.com/trixi-framework/Trixi.jl/blob/main/examples/tree_2d_dgsem/elixir_euler_ec.jl).\n",
    "- Right-click the `Raw` button on the right side of the webpage and choose `Save as...`\n",
    "  (or `Save Link As...`).\n",
    "- Choose a folder and save the file."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "### Modifying an existing setup"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "As an example, we will change the initial condition for calculations that occur in\n",
    "`elixir_euler_ec.jl`. Initial conditions for `CompressibleEulerEquations2D` consist of\n",
    "initial values for $\\rho$, $\\rho v_1$, $\\rho v_2$ and $\\rho e$. One of the common initial\n",
    "conditions for the compressible Euler equations is a simple density wave. Let's implement it."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "- Open the downloaded file `elixir_euler_ec.jl` with a text editor.\n",
    "- Go to the line with the following code:\n",
    "  ```julia\n",
    "  initial_condition = initial_condition_weak_blast_wave\n",
    "  ```\n",
    "  Here, `initial_condition_weak_blast_wave` is used as the initial condition.\n",
    "- Comment out the line using the `#` symbol:\n",
    "  ```julia\n",
    "  # initial_condition = initial_condition_weak_blast_wave\n",
    "  ```\n",
    "- Now you can create your own initial conditions. Add the following code after the\n",
    "  commented line:"
   ],
   "metadata": {}
  },
  {
   "outputs": [],
   "cell_type": "code",
   "source": [
    "function initial_condition_density_waves(x, t, equations::CompressibleEulerEquations2D)\n",
    "    v1 = 0.1 # velocity along x-axis\n",
    "    v2 = 0.2 # velocity along y-axis\n",
    "    rho = 1.0 + 0.98 * sinpi(sum(x) - t * (v1 + v2)) # density wave profile\n",
    "    p = 20 # pressure\n",
    "    rho_e = p / (equations.gamma - 1) + 1/2 * rho * (v1^2 + v2^2)\n",
    "    return SVector(rho, rho*v1, rho*v2, rho_e)\n",
    "end\n",
    "initial_condition = initial_condition_density_waves"
   ],
   "metadata": {},
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "source": [
    "- Execute the following code one more time, but instead of `path/to/file` paste the path to the\n",
    "  `elixir_euler_ec.jl` file that you just edited.\n",
    "  ```julia\n",
    "  using Trixi\n",
    "  trixi_include(path/to/file)\n",
    "  using Plots\n",
    "  plot(sol)\n",
    "  ```\n",
    "Then you will obtain a new solution from running the simulation with a different initial\n",
    "condition."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "To get exactly the same picture execute the following.\n",
    "```julia\n",
    "pd = PlotData2D(sol)\n",
    "p1 = plot(pd[\"rho\"])\n",
    "p2 = plot(pd[\"v1\"], clim=(0.05, 0.15))\n",
    "p3 = plot(pd[\"v2\"], clim=(0.15, 0.25))\n",
    "p4 = plot(pd[\"p\"], clim=(10, 30))\n",
    "plot(p1, p2, p3, p4)\n",
    "```"
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Feel free to make further changes to the initial condition to observe different solutions."
   ],
   "metadata": {}
  },
  {
   "cell_type": "markdown",
   "source": [
    "Now you are able to download, modify and execute simulation setups for Trixi.jl. To explore\n",
    "further details on setting up a new simulation with Trixi.jl, refer to the second part of\n",
    "the introduction titled Create your first setup."
   ],
   "metadata": {}
  }
 ],
 "nbformat_minor": 3,
 "metadata": {
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.10.3"
  },
  "kernelspec": {
   "name": "julia-1.10",
   "display_name": "Julia 1.10.3",
   "language": "julia"
  }
 },
 "nbformat": 4
}