CalculusWithJuliaNotes.jl/quarto/precalc/julia_overview.qmd

# Overview of Julia commands


```{julia}
#| echo: false

import Logging
Logging.disable_logging(Logging.Info) # or e.g. Logging.Info
Logging.disable_logging(Logging.Warn)

import SymPy
function Base.show(io::IO, ::MIME"text/html", x::T) where {T <: SymPy.SymbolicObject}
    println(io, "<span class=\"math-left-align\" style=\"padding-left: 4px; width:0; float:left;\"> ")
    println(io, "\\[")
    println(io, sympy.latex(x))
    println(io, "\\]")
    println(io, "</span>")
end

# hack to work around issue
import Markdown
import CalculusWithJulia
function CalculusWithJulia.WeaveSupport.ImageFile(d::Symbol, f::AbstractString, caption; kwargs...)
    nm = joinpath("..", string(d), f)
    u = "![$caption]($nm)"
    Markdown.parse(u)
end

nothing
```

```{julia}
#| echo: false
#| results: "hidden"
using CalculusWithJulia
using CalculusWithJulia.WeaveSupport
const frontmatter = (
        title = "Overview of Julia commands",
        description = "Calculus with Julia: Overview of Julia commands",
        tags = ["CalculusWithJulia", "precalc", "overview of julia commands"],
);

nothing
```

The [`Julia`](http://www.julialang.org) programming language is well suited as a computer accompaniment while learning the concepts of calculus. The following overview covers the language-specific aspects of the pre-calculus part of the [Calculus with Julia](calculuswithjulia.github.io) notes.


## Installing `Julia`


`Julia` is an *open source* project which allows anyone with a supported  computer to use it. To install locally, the [downloads](https://julialang.org/downloads/) page has several different binaries for installation. Additionally, the downloads page contains a link to a docker image.  For Microsoft Windows, the new [juilaup](https://github.com/JuliaLang/juliaup) installer may be of interest; it is available from the Windows Store. `Julia` can also be compiled from source.


`Julia` can also be run through the web. The [https://mybinder.org/](https://mybinder.org/) service in particular allows free access, though limited in terms of allotted memory and with a relatively short timeout for inactivity.


[Launch Binder](https://mybinder.org/v2/gh/CalculusWithJulia/CwJScratchPad.git/master)


## Interacting with `Julia`


At a basic level, `Julia` provides a means to read commands or instructions, evaluate those commands, and then print or return those commands. At a user level, there are many different ways to interact with the reading and printing. For example:


  * The REPL. The `Julia` terminal is the built-in means to interact with `Julia`. A `Julia` Terminal has a command prompt, after which commands are typed and then sent to be evaluated by the `enter` key. The terminal may look something like the following where `2+2` is evaluated:


---


```{verbatim}
$ julia
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.7.0 (2021-11-30)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

julia> 2 + 2
4
```

---


  * An IDE. For programmers, an integrated development environment is often used to manage bigger projects. `Julia` has `Juno` and `VSCode`.
  * A notebook. The [Project Juptyer](https://jupyter.org/) provides a notebook interface for interacting with `Julia` and a more `IDE` style `jupyterlab` interface. A jupyter notebook has cells where commands are typed and immediately following is the printed output returned by `Julia`. The output of a cell depends on the state of the kernel when the cell is computed, not the order of the cells in the notebook. Cells have a number attached, showing the execution order. The `Juypter` notebook is used by `binder` and can be used locally through the `IJulia` package. This notebook has the ability to display many different types of outputs in addition to plain text, such as images, marked up math text, etc.
  * The [Pluto](https://github.com/fonsp/Pluto.jl) package provides a *reactive* notebook interface. Reactive means when one "cell" is modified and executed, the new values cascade to all other dependent cells which in turn are updated. This is very useful for exploring a parameter space, say. Pluto notebooks can be exported as HTML files which make them easy to read online and – by clever design – embed the `.jl` file that can run through `Pluto` if it is downloaded.


The `Pluto` interface has some idiosyncracies that need explanation:


  * Cells can only have one command within them. Multiple-command cells must be contained in a `begin` block or a `let` block.
  * By default, the cells are *reactive*. This means when a variable in one cell is changed, then any references to that variable are also updated – like a spreadsheet. This is fantastic for updating several computations at once. However it means variable names can not be repeated within a page. Pedagogically, it is convenient to use variable names and function names (e.g., `x` and `f`) repeatedly, but this is only possible *if* they are within a `let` block or a function body.
  * To not repeat names, but to be able to reference a value from cell-to-cell,  some Unicode variants are used within a page. Visually these look familiar, but typing the names requires some understanding of Unicode input. The primary usages is *bold italic* (e.g., `\bix[tab]` or `\bif[tab]`) or *bold face* (e.g. `\bfx[tab]` or `bff[tab]`).
  * The notebooks snapshot the packages they depend on, which is great for reproducability, but may mean older versions are silently used.


## Augmenting base `Julia`


The base `Julia` installation has many features, but leaves many others to `Julia`'s package ecosystem. These notes use packages to provide plotting, symbolic math, access to special functions, numeric routines, and more.


Within `Pluto`, using add-on packages is very simple, as `Pluto` downloads and installs packages when they are requested through a `using` or `import` directive.


---


For other interfaces to `Julia` some more detail is needed.


The `Julia` package manager makes add-on packages very easy to install.


Julia comes with just a few built-in packages, one being `Pkg` which manages subsequent package installation. To add more packages, we first must *load* the `Pkg` package. This is done by issuing the following command:


```{julia}
using Pkg
```

The `using` command loads the specified package and makes all its *exported* values available for direct use. There is also the `import` command which allows the user to select which values should be imported from the package, if any, and otherwise gives access to the new functionality through the dot syntax.


Packages need to be loaded just once per session.


To use `Pkg` to "add" another package, we would have a command like:


```{julia}
#| eval: false
Pkg.add("CalculusWithJulia")
```

This command instructs `Julia` to look at its *general registry* for the `CalculusWithJulia.jl` package, download it, then install it. Once installed, a package only  needs to be brought into play with the `using` or `import` commands.


:::{.callout-note}
## Note
In a terminal setting, there is a package mode, entered by typing `]` as the leading character and exited by entering `<delete>` at a blank line. This mode allows direct access to `Pkg` with a simpler syntax. The command above would be just `add CalculusWithJulia`.)

:::

Packages can be updated through the command `Pkg.up()`, and removed with `Pkg.rm(pkgname)`.


By default packages are installed in a common area. It may be desirable to keep packages for projects isolated. For this the `Pkg.activate` command can be used. This feature allows a means to have reproducible environments even if `Julia` or the packages used are upgraded, possibly introducing incompatabilities.


For these notes, the following packages, among others, are used:


```{julia}
#| eval: false
Pkg.add("CalculusWithJulia") # for some simplifying functions and a few packages (SpecialFunctions, ForwardDiff)
Pkg.add("Plots")  # for basic plotting
Pkg.add("SymPy")  # for symbolic math
Pkg.add("Roots")  # for solving  `f(x)=0`
Pkg.add("QuadGk") # for integration
Pkg.add("HQuadrature") # for higher-dimensional integration
```

## `Julia` commands


In a `Jupyter` notebook or `Pluto` notebook, commands are typed into a notebook cell:


```{julia}
2 + 2   # use shift-enter to evaluate
```

Commands are executed by using `shift-enter` or a run button near the cell.


In `Jupyter` multiple commands per cell are allowed. In `Pluto`, a `begin` or `let` block is used to  collect multiple commmands into a single call. Commands may be separated by new lines or semicolons.


On a given line, anything **after** a `#` is a *comment* and is not processed.


The results of the last command executed will be displayed in an output area. Separating values by commas allows more than one value to be displayed.  Plots are displayed when the plot object is returned by the  last executed command.


In `Jupyter`, the state of the notebook is a determined by the cells executed along with their order.  The state of a `Pluto` notebook is a result of all the cells in the notebook being executed. The cell order does not impact this and can be rearranged by the user.


## Numbers, variable types


`Julia` has many different number types beyond the floating point type employed by most calculators. These include


  * Floating point numbers: `0.5`
  * Integers: `2`
  * Rational numbers: `1//2`
  * Complex numbers `2 + 0im`


`Julia`'s parser finds the appropriate type for the value, when read in. The following all create the number $1$ first as an integer, then a rational, then a floating point number, again as floating point number, and finally as a complex number:


```{julia}
1, 1//1, 1.0, 1e0, 1 + 0im
```

As much as possible, operations involving  certain types of numbers will produce output of a given type. For example, both of these divisions produce a floating point answer, even though  mathematically, they need not:


```{julia}
2/1, 1/2
```

Some powers with negative bases, like `(-3.0)^(1/3)`, are not defined. However, `Julia` provides the special-case function `cbrt` (and `sqrt`) for handling these.


Integer operations may silently overflow, producing odd answers, at first glance:


```{julia}
2^64
```

(Though the output is predictable, if overflow is taken into consideration appropriately.)


When different types of numbers are mixed, `Julia` will usually promote the values to a common type before the operation:


```{julia}
(2 + 1//2) + 0.5
```

`Julia` will first add `2` and `1//2` promoting `2` to rational before doing so. Then add the result, `5//2` to `0.5` by promoting `5//2` to the floating point number `2.5` before proceeding.


`Julia` uses a special type to store a handful of irrational constants such as `pi`. The special type allows these constants to be treated without round off, until they mix with other floating point numbers. There are some functions that require these be explicitly promoted to floating point. This can be done by calling `float`.


The standard mathematical operations are implemented by `+`, `-`, `*`, `/`, `^`. Parentheses are used for grouping.


### Vectors


A vector is an indexed collection of similarly typed values. Vectors can be constructed with square brackets (syntax for concatenation):


```{julia}
[1, 1, 2, 3, 5, 8]
```

Values will be promoted to a common type (or type `Any` if none exists). For example, this vector will have type `Float64` due to the `1/3` computation:


```{julia}
[1, 1//2, 1/3]
```

(Vectors are used as a return type from some functions, as such, some familiarity is needed.)


Regular arithmetic sequences can be defined by either:


  * Range operations:  `a:h:b` or `a:b` which produces a generator of values starting at `a` separated by `h` (`h` is `1` in the last form) until they reach `b`.
  * The `range` function: `range(a, b, length=n)` which produces a generator of `n` values between `a` and `b`;


These constructs return range objects. A range object *compactly* stores the values it references. To see all the values, they can be collected with the `collect` function, though this is rarely needed in practice.


Random sequences are formed by `rand`, among others:


```{julia}
rand(3)
```

The call `rand()` returns a single random number (in $[0,1)$.)


## Variables


Values can be assigned variable names, with `=`. There are some variants


```{julia}
u = 2
a_really_long_name = 3
a0, b0 = 1, 2    # multiple assignment
a1 = a2 = 0      # chained assignment, sets a2 and a1 to 0
```

The names can be short, as above, or more verbose. Variable names can't start with a number, but can include numbers. Variables can also include [Unicode](../misc/unicode.html) or even be an emoji.


```{julia}
α, β = π/3, π/4
```

We can then use the variables to reference the values:


```{julia}
u + a_really_long_name + a0 - b0 + α
```

Within `Pluto`, names are idiosyncratic: within the global scope, only a single usage is possible per notebook; functions and variables can be freely renamed; structures can be redefined or renamed; ...


Outside of `Pluto`, names may be repurposed, even with values of different types (`Julia` is a dynamic language), save for (generic) function names, which have some special rules and can only be redefined as another function. Generic functions are central to `Julia`'s design. Generic functions use a method table to dispatch on, so once a name is assigned to a generic function, it can not be used as a variable name; the reverse is also true.


## Functions


Functions in `Julia` are first-class objects. In these notes, we often pass them as arguments to other functions. There are many built-in functions and it is easy to define new functions.


We "call" a function by passing argument(s) to it, grouped by parentheses:


```{julia}
sqrt(10)
sin(pi/3)
log(5, 100)   # log base 5 of 100
```

With out parentheses, the name (usually) refers to a generic name and the output lists the number of available implementations (methods).


```{julia}
log
```

### Built-in functions


`Julia` has numerous built-in [mathematical](http://julia.readthedocs.io/) functions, we review a few here:


#### Powers logs and roots


Besides `^`, there are `sqrt` and `cbrt` for powers. In addition basic functions for exponential and  logarithmic functions:


```{verbatim}
sqrt, cbrt
exp
log          # base e
log10, log2, # also log(b, x)
```

#### Trigonometric functions


The `6` standard trig functions are implemented; their implementation for degree arguments; their inverse functions; and the hyperbolic analogs.


```{verbatim}
sin, cos, tan, csc, sec, cot
asin, acos, atan, acsc, asec, acot
sinh, cosh, tanh, csch, sech, coth
asinh, acosh, atanh, acsch, asech, acoth
```

If degrees are preferred, the following are defined to work with arguments in degrees:


```{verbatim}
sind, cosd, tand, cscd, secd, cotd
```

#### Useful functions


Other useful and familiar functions are defined:


  * `abs`: absolute value
  * `sign`: is $\lvert x \rvert/x$ except at $x=0$, where it is $0$.
  * `floor`, `ceil`: greatest integer less or least integer greater
  * `max(a,b)`, `min(a,b)`: larger (or smaller) of `a` or `b`
  * `maximum(xs)`, `minimum(xs)`: largest or smallest of the collection referred to by `xs`


---


In a Pluto session, the "Live docs" area shows inline documentation for the current object.


For other uses of `Julia`, the built-in documentation for an object is accessible through a leading `?`, say, `?sign`. There is also the `@doc` macro, for example:


```{julia}
#| eval: false
@doc sign
```

---


### User-defined functions


Simple mathematical functions can be defined using standard mathematical notation:


```{julia}
f(x) = -16x^2 + 100x + 2
```

The argument `x` is passed into the body of function.


Other values are found from  the environment where defined:


```{julia}
#| hold: true
a = 1
f(x) = 2*a + x
f(3)   # 2 * 1 + 3
a = 4
f(3)  # now 2 * 4 + 3
```

User-defined functions can have $0$, $1$ or more arguments:


```{julia}
area(w, h) = w*h
```

Julia makes different *methods* for *generic* function names, so function definitions whose argument specification is different are for different uses, even if the name is the same. This is *polymorphism*. The practical use is that it means users need only remember a much smaller set of function names, as attempts are made to give common expectations to the same name. (That is, `+` should be used only for "add" ing objects, however defined.)


Functions can be defined with *keyword* arguments that may have defaults specified:


```{julia}
#| hold: true
f(x; m=1, b=0) = m*x + b     # note ";"
f(1)                         # uses m=1, b=0   -> 1 * 1 + 0
f(1, m=10)                   # uses m=10, b=0  -> 10 * 1 + 0
f(1, m=10, b=5)              # uses m=10, b=5  -> 10 * 1 + 5
```

Longer functions can be defined using the `function` keyword, the last command executed is returned:


```{julia}
function 𝒇(x)
  y = x^2
  z = y - 3
  z
end
```

Functions without names, *anonymous functions*, are made with the `->` syntax as in:


```{julia}
x -> cos(x)^2 - cos(2x)
```

These are useful when passing a function to another function or when writing a function that *returns* a function.


## Conditional statements


`Julia` provides the traditional `if-else-end` statements, but more conveniently has a `ternary` operator for the simplest case:


```{julia}
our_abs(x) = (x < 0) ? -x : x
```

## Looping


Iterating over a collection can be done with the traditional `for` loop. However, there are list comprehensions to mimic the definition of a set:


```{julia}
[x^2 for x in 1:10]
```

Comprehensions can be filtered through the `if` keyword


```{julia}
[x^2 for x in 1:10 if iseven(x)]
```

This is more efficient than creating the collection then filtering, as is done with:


```{julia}
filter(iseven, [x^2 for x in 1:10])
```

## Broadcasting, mapping


A function can be applied to each element of a vector through mapping or broadcasting. The latter is implemented in a succinct notation. Calling a function with a "." before its opening "(` will apply the function to each individual value in the argument:


```{julia}
xs = [1,2,3,4,5]
sin.(xs)     # gives back [sin(1), sin(2), sin(3), sin(4), sin(5)]
```

For "infix" operators, the dot precedes the operator, as in this example instructing pointwise multiplication of each element in `xs`:


```{juila}
xs .* xs
```

Alternatively, the more traditional `map` can be used:


```{julia}
map(sin, xs)
```

## Plotting


Plotting is *not* built-in to `Julia`, rather added through add-on packages.  `Julia`'s `Plots` package is an interface to several plotting packages. We mention `plotly` (built-in) for web based graphics, `pyplot`, and `gr` (also built into `Plots`) for other graphics.


We must load `Plots` before we can plot (and it must be installed before we can load it):


```{julia}
using Plots
```

With `Plots` loaded, we can plot a function by passing the function object by name to `plot`, specifying the range of `x` values to show, as follows:


```{julia}
plot(sin, 0, 2pi) # plot a function - by name - over an interval [a,b]
```

!!1 note 	This is in the form of **the** basic pattern employed: `verb(function_object, arguments...)`. The verb in this example is `plot`, the object `sin`, the arguments `0, 2pi` to specify `[a,b]` domain to plot over.


Plotting more than one function over `[a,b]` is achieved through the `plot!` function, which modifies the existing plot (`plot` creates a new one) by adding a new layer:


```{julia}
plot(sin, 0, 2pi)
plot!(cos, 0, 2pi)
plot!(zero, 0, 2pi) # add the line y=0
```

Individual points are added with `scatter` or `scatter!`:


```{julia}
plot(sin, 0, 2pi, legend=false)
plot!(cos, 0, 2pi)
scatter!([pi/4, pi+pi/4], [sin(pi/4), sin(pi + pi/4)])
```

(The extra argument `legend=false` suppresses the automatic legend drawing. There are many other useful arguments to adjust a graphic. For example, passing `markersize=10` to the `scatter!` command would draw the points larger than the default.)


Plotting an *anonymous* function is a bit more immediate than the two-step approach of defining a named function then calling `plot` with this as an argument:


```{julia}
plot( x -> exp(-x/pi) * sin(x), 0, 2pi)
```

The `scatter!` function used above takes two vectors of values to describe the points to plot, one for the $x$ values and one for the matching $y$ values. The `plot` function can also produce plots with this interface. For example, here we use a comprehension to produce `y` values from the specified `x` values:


```{julia}
#| hold: true
xs = range(0, 2pi, length=251)
ys = [sin(2x) + sin(3x) + sin(4x) for x in xs]
plot(xs, ys)
```

## Equations


Notation for `Julia` and math is *similar* for functions - but not for equations. In math, an equation  might look like:


$$
x^2 + y^2 = 3
$$

In `Julia` the equals sign is **only** for *assignment* and *mutation*. The *left-hand* side of an equals sign in `Julia` is reserved for a) variable assignment; b) function definition (via `f(x) = ...`); c) indexed mutation of a vector or array; d) mutation of fields in a structure. (Vectors are indexed by a number allowing retrieval and mutation of the stored value in the container. The notation mentioned here would be `xs[2] = 3` to mutate the 2nd element of `xs` to the value `3`.


## Symbolic math


Symbolic math is available through an add-on package `SymPy` (among others).  Once loaded, symbolic variables are created with the macro `@syms`:


```{julia}
using SymPy
```

```{julia}
@syms x a b c
```

(A macro rewrites values into other commands before they are interpreted. Macros are prefixed with the `@` sign. In this use, the "macro" `@syms` translates `x a b c` into a command involving `SymPy`s `symbols` function.)


Symbolic expressions - unlike numeric expressions - are not immediately evaluated, though they may be  simplified:


```{julia}
p = a*x^2 + b*x + c
```

To substitute a value, we can use `Julia`'s `pair` notation (`variable=>value`):


```{julia}
p(x=>2), p(x=>2, a=>3, b=>4, c=>1)
```

This is convenient notation for calling the `subs` function for `SymPy`.


SymPy expressions of a single free variable can be plotted directly:


```{julia}
plot(64 - (1/2)*32 * x^2, 0, 2)
```

  * SymPy has functions for manipulating expressions: `simplify`, `expand`, `together`, `factor`, `cancel`, `apart`,  $...$
  * SymPy has functions for basic math: `factor`, `roots`, `solve`, `solveset`, $\dots$
  * SymPy has functions for calculus: `limit`, `diff`, `integrate`, $\dots$