diff --git a/book/src/introduction.md b/book/src/introduction.md index 6bc44ff..1aadcd5 100644 --- a/book/src/introduction.md +++ b/book/src/introduction.md @@ -41,4 +41,6 @@ out_i { } ``` -Here, we define the input parameters for our model as a vector `in` with the growth rate `r` and the carrying capacity `k`. We then define the state vector `u_i` with the population `N` initialized to `0.0`. Next, we define the RHS function `F_i` as the logistic growth equation. Finally, we define the output vector `out_i` with the population `N`. \ No newline at end of file +Here, we define the input parameters for our model as a vector `in` with the growth rate `r` and the carrying capacity `k`. We then define the state vector `u_i` with the population `N` initialized to `0.0`. Next, we define the RHS function `F_i` as the logistic growth equation. Finally, we define the output vector `out_i` with the population `N`. + +*For an LLM-oriented summary and index of this documentation, see [llms.txt](./llms.txt).* \ No newline at end of file diff --git a/book/src/llms.txt b/book/src/llms.txt new file mode 100644 index 0000000..ae45ca3 --- /dev/null +++ b/book/src/llms.txt @@ -0,0 +1,84 @@ +DiffSL Language Documentation (LLMs) + +Site: https://martinjrobins.github.io/diffsl/ +Source Book: mdBook in book/src + +Summary +DiffSL is a domain-specific language for defining systems of ordinary differential equations (ODEs), including differential-algebraic systems via a mass-matrix form. A DiffSL model describes state variables, right-hand side equations, parameters, optional mass-matrix terms, and optional stop/reset tensors for hybrid behavior. + +Conceptually, models are written in the form: +M(t) * du/dt = F(u, p, t) +u(0) = u0 + +Core language ideas: +- A model is a sequence of tensor definitions, optionally preceded by an input name list. +- Variables are tensors (scalar, vector, matrix, higher-rank) identified by a name with optional index suffix (example: u_i, A_ij). +- Tensor elements can be direct expressions or named assignments (example: x = 1.0). +- Expressions support arithmetic, function calls, broadcasting-by-index, and selected contractions. +- Ranges and sparse/diagonal element patterns are used to define tensor structure concisely. + +Grammar +The grammar below summarizes the currently implemented DiffSL parser (based on ds_grammar.pest): + +main = SOI model EOI +model = inputs? tensor* +inputs = "in" "=" "[" name? ("," name)* ","? "]" + +tensor = name_ij "{" tensor_elmt? ("," tensor_elmt)* ","? "}" +tensor_elmt = indices? (assignment | expression) +assignment = name "=" expression + +indices = "(" indice ("," indice)* ")" ":" +indice = integer (range_sep integer)? +range_sep = ".." | ":" + +expression = term (("+" | "-") term)* +term = factor (("*" | "/") factor)* +factor = sign? (call | real | integer | name_ij_index | name_ij | "(" expression ")") +sign = "+" | "-" + +call = name "(" expression ("," expression)* ")" +name_ij = name ("_" name)? +name_ij_index = name_ij "[" index_indice "]" +index_indice = integer_expression (range_sep integer_expression)? + +integer_expression = integer_term (("+" | "-") integer_term)* +integer_term = integer_factor ((("*" | "/" | "%") integer_factor))* +integer_factor = sign? (integer | integer_name | "(" integer_expression ")") +integer_name = "N" + +name = letter (letter | digit)* +integer = digit+ +real = digit+ ("." digit*)? ("e" sign? integer)? + +Notes: +- The special integer symbol N is available for model-indexed expressions. +- name_ij supports an optional suffix after '_' (for example i, ij, abc). +- name_ij_index supports single index and slice-like forms via index_indice. + +mdBook Index +Each page in the public docs with a one-line description: + +1) DiffSL Language + URL: https://martinjrobins.github.io/diffsl/introduction.html + Description: High-level introduction to DiffSL with a minimal working example. + +2) Tensor Variables + URL: https://martinjrobins.github.io/diffsl/tensors.html + Description: Tensor definitions, indices, ranges, labels, and sparse/diagonal structure. + +3) Tensor Operations + URL: https://martinjrobins.github.io/diffsl/operations.html + Description: Arithmetic on tensors, index-aware broadcasting, contractions, and vector indexing. + +4) Defining ODEs + URL: https://martinjrobins.github.io/diffsl/odes.html + Description: ODE/DAE model construction with u, F, optional dudt and M, and hybrid stop/reset behavior. + +5) Inputs and Outputs + URL: https://martinjrobins.github.io/diffsl/inputs_outputs.html + Description: Declaring overridable input parameters and selecting model outputs. + +6) Predefined functions + URL: https://martinjrobins.github.io/diffsl/functions.html + Description: Built-in math functions and the predefined time variable t.