From ad5fe4a7c171ada558e9263e3f86588348c58800 Mon Sep 17 00:00:00 2001
From: michaellans <mlans@slac.stanford.edu>
Date: Thu, 22 Jan 2026 11:52:05 -0800
Subject: [PATCH] updated template documentation

---
 documentation/docs/guides/templates.md | 66 ++++++++++++++++----------
 1 file changed, 40 insertions(+), 26 deletions(-)

diff --git a/documentation/docs/guides/templates.md b/documentation/docs/guides/templates.md
index 4d1d9bb0..33020603 100644
--- a/documentation/docs/guides/templates.md
+++ b/documentation/docs/guides/templates.md
@@ -24,51 +24,65 @@ generator:
   name:             # generator name
   # params will depend on generator
 vocs:               # XOPT VOCS
-  constants: {}     # {constant_name: value}
-  constraints: {}   # {constraint_name: [GREATER_THAN or LESS_THAN, value]}
+  constants: {}     # {constant_name: value} # optional
+  constraints: {}   # {constraint_name: [GREATER_THAN or LESS_THAN, value]} # optional
   objectives: {}    # {objective_name: MINIMIZE or MAXIMIZE}
-  observables: []   # list of observable names
+  observables: []   # list of observable names # optional
   variables: {}     # {variable_name: [lower_bound, upper_bound]}
 
-                    # Note that the variable upper and lower bound should be
-                    # the absolute variable range limits, not the limit of the
-                    # optimization. The range of the optimization is set based
-                    # on vrange_limit_options for each variable, either as a
-                    # fraction of the full range or ± a fraction of the
-                    # current value.
+                    # Important note about variable bounds: the bounds set here will be used
+                    # if relative_to_current is set to false. If relative_to_current is true,
+                    # these bounds will not be used and the bounds for each variable will be
+                    # determined based on the vrange_limit_options below.
 
 vrange_limit_options: {}
 
                     # for each variable:
-                    #   variable: {limit_option_idx: 0 or 1, ratio_curr: 0.1, ratio_full: 0.1}
+                    #   variable: {limit_option_idx: 0 or 1 or 2, ratio_curr: ratio (float), ratio_full: ratio (float), delta: abs value (float)}
+                    #
                     # For example:
                     #   QUAD:LTUH:620:BCTRL:
-                    #   limit_option_idx: 0
-                    #   ratio_curr: 0.1
-                    #   ratio_full: 0.1
-                    # Note that ratio_curr is the ratio with respect to the current value
-                    # and ratio_full is the ratio with respect to the full variable range.
-                    # limit_option_idx 0 will use ratio_curr, 1 is ratio_full
+                    #     limit_option_idx: 2
+                    #     ratio_curr: 0.1
+                    #     ratio_full: 0.1
+                    #     delta: 1.2
+                    # Will set the variable range for QUAD:LTUH:620:BCTRL to a delta (option 2) of +- 1.2 from the current value of the variable.
+                    #
+                    # Note that ratio_curr is the ratio with respect to the current value,
+                    # ratio_full is the ratio with respect to the full variable range, and
+                    # delta is an absolute delta around the current value. Include values
+                    # for all three options even if you do not plan to use them.
+                    # limit_option_idx sets the desired option: 0 will use ratio_curr,
+                    # 1 is ratio_full, 2 is delta.
 
-relative_to_current: true  # true or false.
+relative_to_current: true  # (bool) true or false. If true, variable ranges will be set
+                    # for each variable based on vrange_limit_options. If False, variable
+                    # ranges will be set to the specified upper and lower bounds from the
+                    # variables dictionary in vocs.
 initial_point_actions: [{}]  # list of dictionaries
-
                     # Will be read sequentially.
-                    # For example, the two most common options would look like:
+                    # For example, a common option would look like:
                     #
-                    # - type: add_curr     # will add the current value of selected vars
+                    # - type: add_curr
+                    #         # will add the current value of selected vars
+                    #         # as the first initial point
                     # - config:
                     #     fraction: 0.1
                     #     method: 0
                     #     n_points: 3
                     #   type: add_rand
                     #
-                    # will add three random points for each variable, selected
-                    # from within 0.1*(the vrange limit ratio for that
-                    # variable) around the current value – i.e. sample n random
-                    # points from within a subset of the scan range
+                    #   will add three random points (type: add_rand) for each variable, selected
+                    #   from within 0.1*[the vrange limit ratio for that
+                    #   variable] around the current value - i.e. sample n random
+                    #   points from within a subset of the scan range
 
 critical_constraint_names: []  # list of constraints (from VOCS) to be marked as ‘critical’
-badger_version:     # optional but helpful
-xopt_version:       # optional but helpful
+additional_variables: [] # list of additional variables # optional
+formulas: {}        # optional
+constraint_formulas: {} # optional
+observable_formulas: {} # optional
+vrange_hard_limit: {} # optional
+badger_version:     # badger version
+xopt_version:       # xopt version
 ```