Fixed max order/param orders, docs updated, global variable getter/se…

…tter
bmad-sim · Mar 14, 2024 · 4897542 · 4897542
1 parent f0cbc77
commit 4897542
Show file tree

Hide file tree

Showing 22 changed files with 860 additions and 785 deletions.
diff --git a/LICENSE b/LICENSE
diff --git a/docs/make.jl b/docs/make.jl
@@ -9,20 +9,21 @@ makedocs(
  [
  "Home" => "index.md",
  "Quickstart Guide" => "quickstart.md",
- "Manual" => ["man/toc.md",
- "man/definitions.md", 
- "man/descriptor.md", 
- "man/tps.md",
- "man/complextps.md",
- "man/varsparams.md",
- "man/monoindex.md",
- "man/mono.md",
- "man/gjh.md",
- "man/slice.md",
- "man/methods.md",
- "man/fastgtpsa.md",
- "man/io.md",
- "man/all.md"],
+ "Manual" => ["man/a_toc.md",
+ "man/b_definitions.md", 
+ "man/c_descriptor.md", 
+ "man/d_tps.md",
+ "man/e_complextps.md",
+ "man/f_varsparams.md",
+ "man/g_monoindex.md",
+ "man/h_mono.md",
+ "man/i_gjh.md",
+ "man/j_slice.md",
+ "man/k_methods.md",
+ "man/l_fastgtpsa.md",
+ "man/m_io.md",
+ "man/n_global.md",
+ "man/o_all.md"],
  "For Developers" => "devel.md"
  ]
 )

diff --git a/docs/src/man/toc.md → docs/src/man/a_toc.md b/docs/src/man/toc.md → docs/src/man/a_toc.md
diff --git a/docs/src/man/b_definitions.md b/docs/src/man/b_definitions.md
@@ -0,0 +1,37 @@
+# [Definitions](@id definitions)
+*This section is incomplete, and will be expanded in the near future*
+
+## [Custom Truncation Orders](@id cto)
+GTPSA allows for significant customization in the truncation of specific variables within a monomial of the truncated power series (TPS). One can specify individually the truncation orders for each variable in a truncated power series, as well as the maximum truncation order for an entire monomial in the TPS. This is best shown with an example:
+
+Suppose we'd like to express a function ``f(x_1,x_2)`` as a truncated power series, and keep only terms that are up to 1st-order in ``x_1`` but up to 2nd order in ``x_2``; basically, we should not have any monomials where ``x_1`` has an exponent > 1, nor any monomials where ``x_2`` has an exponent > 2. GTPSA allows one to select the **individual truncation orders** for variables in a monomial in this manner. The next question to consider is the **maximum truncation order** for the entire monomial; in the above example, note that the 3rd-order term ``x_1x_2^2`` follows the rules we layed out so far. But what if we'd also like to truncate all monomials with order 3 and above, and not allow this monomial? This can be achieved by setting the maximum truncation order equal to 2. When defining a GTPSA, the user must always specify the maximum truncation order, which when specifying individual truncation orders must lie within the range ``[\max{(\textrm{individual truncation orders})}, \sum{(\textrm{individual truncation orders})}]``. If individual truncation orders are not specified, then they are automatically set to the maximum truncation order.
+
+**Example: allowed monomials for ``f(x_1,x_2)`` with individual variable truncation orders [1,2] and different maximum truncation orders:**
+
+| Exponents | Max Order = 2 | Max Order = 3 |
+| :-------: | :-----------: | :-----------: |
+| ``1\quad 0`` | ✅ | ✅ |
+| ``0\quad 1`` | ✅ | ✅ |
+| ``2\quad 0`` | ❌ | ❌ |
+| ``1\quad 1`` | ✅ | ✅ |
+| ``0\quad 2`` | ✅ | ✅ |
+| ``3\quad 0`` | ❌ | ❌ |
+| ``2\quad 1`` | ❌ | ❌ |
+| ``1\quad 2`` | ❌ | ✅ |
+| ``0\quad 3`` | ❌ | ❌ |
+
+
+## Parameters
+GTPSA allows one to explicitly distinguish between *variables* and *parameters*. Generally, a variable would be a dependent variable in a differential equation, and a parameter would be a variation in something defining or influencing the system (for example, in a harmonic oscillator the restoring constant ``k`` would be a parameter). Individual truncation orders can be specified for the parameters in the same way as [described for the variables](@ref cto), however there is a special extra truncation order the can be specified for solely the parameters part of the monomial, referred to as the **parameter order**. The parameter order defines the truncation order for only the parameters part of a monomial. 
+
+**Example: allowed monomials for ``f(x_1,k_1,k_2)`` (one variable, two parameters) with individual variable truncation order [1], individual parameter truncation orders [1,1], maximum order = 3, and different parameter orders:**
+
+| Exponents | Parameter Order = 1 | Parameter Order = 2 |
+| :-------: | :-----------: | :-----------: |
+| ``0\quad \| \quad 1 \quad 0`` | ✅ | ✅ |
+| ``0\quad \| \quad 0 \quad 1`` | ✅ | ✅ |
+| ``0\quad \| \quad 1 \quad 1`` | ❌ | ✅ |
+| ``1\quad \| \quad 1 \quad 0`` | ✅ | ✅ |
+| ``1\quad \| \quad 0 \quad 1`` | ✅ | ✅ |
+| ``1\quad \| \quad 1 \quad 1`` | ❌ | ✅ |
+(Note: many monomials are excluded for brevity in the above table)
diff --git a/docs/src/man/c_descriptor.md b/docs/src/man/c_descriptor.md
@@ -0,0 +1,40 @@
+# [`Descriptor`](@id descriptor)
+*Defines the number of variables, number of parameters, and order(s) for each in the GTPSA*
+## Syntax
+```
+d = Descriptor(num_vars, max_order) 
+d = Descriptor(vars_orders, max_order)
+d = Descriptor(num_vars, max_order, num_params, param_order) 
+d = Descriptor(vars_orders, max_order, params_orders, param_order)
+
+GTPSA.desc_current = d
+```
+
+## Description
+`d = Descriptor(num_vars, max_order)` defines a GTPSA `Descriptor` with `num_vars` variables and a maximum truncation order `max_order`
+
+`d = Descriptor(vars_orders, max_order)` defines a GTPSA `Descriptor` with `length(var_orders)` variables each having individual truncation orders specified in the `var_orders` vector, and a maximum truncation order `max_order` for the entire monomial
+
+`d = Descriptor(num_vars, max_order, num_params, param_order)` defines a GTPSA `Descriptor` with `num_vars` variables and `num_params` parameters. The parameters part of a monomial is truncated at `param_order`, and the entire monomial is truncated at `max_order` (so `param_order <= max_order`)
+
+`d = Descriptor(vars_orders, max_order, params_orders, param_order)` defines a GTPSA `Descriptor` with `length(var_orders)` variables each having individual truncation orders specified in the `vars_orders` vector, and `length(param_orders)` parameters each having individual truncation orders specified in the `params_orders` vector. The parameters part of the monomial is truncated at `param_order`, and the entire monomial is truncated at `max_order` (so `param_order <= max_order`)
+
+-----
+
+`GTPSA.desc_current` is a global variable that is set each time a user creates a new `Descriptor`, and can also be set manually by a user. `GTPSA.desc_current` defines the `Descriptor` to use when that information is not explicitly (or implicitly in a TPS copy constructor) available, e.g. when calling `TPS(a)` where `a` is not a `TPS`. This also allows one to use general `Number` commands like `convert(TPS, a)` and `zeros(TPS, 6)`.
+
+
+## Examples
+```@repl desc
+using GTPSA #hide
+d1 = Descriptor(2, 10) 
+d2 = Descriptor([1, 2, 3], 5) 
+d3 = Descriptor(3, 4, 1, 2) 
+d4 = Descriptor([6, 5], 8, [4, 3], 7) 
+GTPSA.desc_current = d1
+```
+
+## Documentation
+```@docs
+Descriptor
+```
diff --git a/docs/src/man/tps.md → docs/src/man/d_tps.md b/docs/src/man/tps.md → docs/src/man/d_tps.md
diff --git a/docs/src/man/definitions.md b/docs/src/man/definitions.md
diff --git a/docs/src/man/descriptor.md b/docs/src/man/descriptor.md
diff --git a/docs/src/man/complextps.md → docs/src/man/e_complextps.md b/docs/src/man/complextps.md → docs/src/man/e_complextps.md
diff --git a/docs/src/man/varsparams.md → docs/src/man/f_varsparams.md b/docs/src/man/varsparams.md → docs/src/man/f_varsparams.md
diff --git a/docs/src/man/monoindex.md → docs/src/man/g_monoindex.md b/docs/src/man/monoindex.md → docs/src/man/g_monoindex.md
diff --git a/docs/src/man/mono.md → docs/src/man/h_mono.md b/docs/src/man/mono.md → docs/src/man/h_mono.md
diff --git a/docs/src/man/gjh.md → docs/src/man/i_gjh.md b/docs/src/man/gjh.md → docs/src/man/i_gjh.md
diff --git a/docs/src/man/slice.md → docs/src/man/j_slice.md b/docs/src/man/slice.md → docs/src/man/j_slice.md
diff --git a/docs/src/man/methods.md → docs/src/man/k_methods.md b/docs/src/man/methods.md → docs/src/man/k_methods.md
diff --git a/docs/src/man/fastgtpsa.md → docs/src/man/l_fastgtpsa.md b/docs/src/man/fastgtpsa.md → docs/src/man/l_fastgtpsa.md
diff --git a/docs/src/man/io.md → docs/src/man/m_io.md b/docs/src/man/io.md → docs/src/man/m_io.md
diff --git a/docs/src/man/n_global.md b/docs/src/man/n_global.md
@@ -0,0 +1,34 @@
+# [Global Variables] (@id global)
+The following non-constant global variables can be set:
+
+```julia
+desc_current::Descriptor # Current Descriptor to use
+show_eps::Float64 = 0.0 # Print epsilon
+show_sparse::Bool = false # Use sparse monomial print
+show_header::Bool = false # Print a header above each TPS
+```
+
+**`desc_current`** defines the `Descriptor` to use when that information is not explicitly (or implicitly in a TPS copy constructor) available, e.g. when calling `TPS(a)` where `a` is not a `TPS`. This also allows one to use general `Number` commands like `convert(TPS, a)` and `zeros(TPS, 6)` 
+
+**`show_eps`** defines the value below which the absolute value of a monomial coefficient is NOT printed
+
+**`show_sparse`** specifies whether the sparse monomial format is used for printing. This is useful for GTPSAs containing a large number of variables and parameters
+
+**`show_header`** specifies whether or not to print the GTPSA `Descriptor` information above each TPS output
+
+-----
+
+Global variables can be get/set using either the standard syntax (e.g. `GTPSA.show_header = true`), or using the helper functions `getGTPSA` and `setGTPSA!`.
+
+## Examples
+
+```@repl
+using GTPSA; GTPSA.show_sparse = false; GTPSA.show_header=false; #hide
+d1 = Descriptor(1, 6);
+x = vars()
+GTPSA.show_sparse = true;
+x
+setGTPSA!("show_sparse", false);
+getGTPSA("show_sparse")
+x
+```
diff --git a/docs/src/man/all.md → docs/src/man/o_all.md b/docs/src/man/all.md → docs/src/man/o_all.md
diff --git a/docs/src/quickstart.md b/docs/src/quickstart.md
@@ -4,21 +4,21 @@ A `Descriptor` defines all information about the GTPSA, including the number of
 
 ```@example desc
 using GTPSA #hide
-# Descriptor for 2 variables with max order 10 for each
+# 2 variables with max truncation order 10
 d1 = Descriptor(2, 10) 
 ```
 
 ```@example desc
-# Descriptor for 3 variables with orders 1, 2, 3 respectively
-d2 = Descriptor([1, 2, 3])
+# 3 variables with individual truncation orders 1, 2, 3 and max truncation order 6
+d2 = Descriptor([1, 2, 3], 6)
 ```
 
 ## Calculating a TPS
-After defining a `Descriptor` for the TPSA, the variables (which themselves are represented as `TPS`s) can be obtained using `vars` or `complexvars`. For example, to calculate the Taylor series for ``f(x_1,x_2) = \cos{(x_1)} + \sqrt{1+x_2}`` to 4th order in ``x_1`` and but only 1st order in ``x_2``:
+After defining a `Descriptor` for the TPSA, the variables (which themselves are represented as `TPS`s) can be obtained using `vars` or `complexvars`. For example, to calculate the Taylor series for ``f(x_1,x_2) = \cos{(x_1)} + \sqrt{1+x_2}`` to 4th order in ``x_1`` and but only 1st order in ``x_2`` (up to maximally 1 + 4 = 5th order):
 
 ```@example 1
-using GTPSA #hide
-d = Descriptor([4, 1]);
+using GTPSA; GTPSA.show_header=false; GTPSA.show_sparse=false;#hide
+d = Descriptor([4, 1], 5);
 
 # Returns a Vector of each variable as a TPS
 x = vars(d) 
@@ -35,7 +35,7 @@ A blank `TPS` or `ComplexTPS`, with all coefficients equal to zero, can be creat
 When a TPS contains a lot of variables, the default output showing each variable exponent can be larger than the screen can show. A global variable `GTPSA.show_sparse`, which is by default set to `false`, can be set to `true` to instead show each specific monomial instead of the exponents for each variable:
 
 ```@example
-using GTPSA #hide
+using GTPSA; GTPSA.show_header=false; GTPSA.show_sparse=false;#hide
 d = Descriptor(10, 10);
 x = vars(d);
 
@@ -60,7 +60,7 @@ Individual monomial coefficients in a TPS `t` can be get/set with two methods of
 These two methods of indexing are best shown with an example:
 
 ```@example
-using GTPSA; GTPSA.show_sparse=false; #hide
+using GTPSA; GTPSA.show_header=false; GTPSA.show_sparse=false;#hide
 # Example of indexing by order -----------
 d = Descriptor(3, 10);
 t = TPS(use=d); # Create zero TPS based on d
@@ -75,7 +75,7 @@ print(t)
 ```
 
 ```@example 
-using GTPSA #hide
+using GTPSA; GTPSA.show_header=false; GTPSA.show_sparse=false; #hide
 # Example of indexing by sparse monomial -----------
 d = Descriptor(3, 10);
 t = TPS(use=d); # Create zero TPS based on d
@@ -92,7 +92,7 @@ print(t)
 The convenience getters `gradient`, `jacobian`, and `hessian` (as well as their corresponding in-place methods `gradient!`, `jacobian!`, and `hessian!`) are also provided for extracting partial derivatives from a TPS/Vector of TPSs. Note that these functions are not actually calculating anything - at this point the TPS should already have been propagated through the system, and these functions are just extracting the corresponding partial derivatives.
 
 ```@example
-using GTPSA #hide
+using GTPSA; GTPSA.show_header=false; GTPSA.show_sparse=false; #hide
 # 2nd Order TPSA with 100 variables
 d = Descriptor(100, 2);
 x = vars(d);
@@ -114,7 +114,7 @@ hessian!(h1, out[1]);
 Parts of a TPS with certain variable orders can be extracted by slicing the TPS. When indexing by order, a colon (`:`) can be used in place for a variable order to include all orders of that variable. If the last specified index is a colon, then the rest of the variable indices are assumed to be colons:
 
 ```@example slice
-using GTPSA; #hide
+using GTPSA; GTPSA.show_header=false; GTPSA.show_sparse=false; #hide
 d = Descriptor(5, 10);
 x = vars(d);