Docs/usage (#131)

* added draft for usage page

* Create paper.rst

Added a draft for the ``usage`` page in documentation

* up usade docs page

* temp commit to save changes to sphinx conf, need to fix path for animations

* pulling changes to docs on master (#124)

* First draft of lorenz 96 docs

* started ascher DAE doc writeup

* docs for Ascher linear DAE

* up Ascher docs, added presets

* fixes based on past conversations

* constructor for lorenz 63 presets

* fixes

* changed variable names to unicode

* Sort presents alphabetically

* Feature/oregonator docs (#119)

* Start Oregonator docs

* Add Canonical constructor docs

* Fix Jacobian

* Fix sphinx warning

* Update python packages

* up Ascher docs re code review

* up Ascher docs, line width and unicode characters fixed

* Make superclass for params (#118)

* Make superclass for params

* Fix param capitalization

* Add docs

* Update Ascher Linear DAE

* Update CUSP

* Update L'96

* Update Oregonator

* Update PR

* Update Robertson

* Typo fixes

* Fix Greek letters

* Doc consistency fixes

* Fix capitalization

* fixes for the project file (#123)

* Bumb version

* Update DESCRIPTION

---------

Co-authored-by: Andrey A Popov <apopov@vt.edu>
Co-authored-by: Andrey A Popov <54905478+AndreyAPopov@users.noreply.github.com>
Co-authored-by: Steven Roberts <sroberts994@gmail.com>

* updated conf.py to copy webms from /images/animations dir to the /docs/_static dir

* Update usage.rst

---------

Co-authored-by: Andrey A Popov <apopov@vt.edu>
Co-authored-by: Andrey A Popov <54905478+AndreyAPopov@users.noreply.github.com>
Co-authored-by: Steven Roberts <sroberts994@gmail.com>

Author: 3 people

docs/conf.py

@@ -1,6 +1,34 @@
 from datetime import datetime
 from yaml import safe_load
 
+import os
+import shutil
+
+def copy_webm_files(source_dir, destination_dir):
+    # Get a list of all files in the source directory
+    files = os.listdir(source_dir)
+
+    if not os.path.exists(destination_directory):
+        os.makedirs(destination_directory)
+
+    # Iterate over each file
+    for file in files:
+        # Check if the file is a .webm file
+        if file.endswith(".webm"):
+            # Create the full path of the source file
+            source_file = os.path.join(source_dir, file)
+
+            # Create the full path of the destination file
+            destination_file = os.path.join(destination_dir, file)
+
+            # Copy the file to the destination directory
+            shutil.copy2(source_file, destination_file)
+
+
+source_directory = "../images/animations/"
+destination_directory = "../docs/build/_static"
+copy_webm_files(source_directory, destination_directory)
+
 with open('../DESCRIPTION') as stream:
     otp = safe_load(stream)
 
@@ -18,6 +46,7 @@
     'sphinx_math_dollar',
     'sphinxcontrib.bibtex',
     'sphinx_rtd_theme',
+    'sphinxcontrib.video',
     'myst_parser'
 ]
 
@@ -49,3 +78,5 @@
 html_theme_options = {
     'logo_only': True
 }
+
+

docs/requirements.txt

@@ -5,6 +5,7 @@ sphinxcontrib-matlabdomain==0.21.4
 sphinxcontrib-napoleon==0.7
 sphinx-math-dollar==1.2.1
 sphinxcontrib-bibtex==2.6.2
+sphinxcontrib-video==0.2.0
 setuptools==70.0.0 # Now required in python 3.12+
 myst-parser==2.0.0
 pyyaml==6.0.1

docs/usage.rst

@@ -1,4 +1,144 @@
-Usage
+Getting Started
 ================================================================================
+This guide shows you how to create, solve and visualize different problems in ODE Test Problems (``OTP``).
 
-TODO
+Mathematical formulation
+-----------------------------
+
+All test problems in ``OTP`` are considered as a first-order
+differential-algebraic equation of the form
+
+.. math::
+
+
+     M(t, y)\;y'(t) = f(t, y), \qquad
+     y(t_0) = y_0,
+
+where :math:`y(t)` is the time-dependent solution to the problem,
+:math:`f(t, y)` is the right-hand-side function corresponding to the
+time-derivative of the system, and :math:`t` is the independent variable. :math:`M(t,y)` is
+the mass-matrix for the differential-algebraic system. When the test
+problem is an ordinary differential equation, :math:`M` is the Identity
+matrix. The initial condition :math:`y_0` specifies the value of
+:math:`y` at the initial time :math:`t = t_0`.
+
+
+Creating problems
+---------------------
+
+Any problem in ``OTP`` can be initialized using a *problem name* and a
+*preset* that defines a set of specific parameters and initial
+conditions. The ``Canonical`` preset is available for all problems.
+
+
+
+   >>> problem = otp.lorenz63.presets.Canonical
+   <BLANKLINE>
+   Canonical with properties:
+   <BLANKLINE>
+         Name: 'Lorenz Equations'
+         RHS: [1×1 otp.RHS]
+         TimeSpan: [0 60]
+         Y0: [3×1 double]
+         Parameters: [1×1 otp.lorenz63.Lorenz63Parameters]
+         NumVars: 3
+
+The ``problem`` object contains a number of useful properties including:
+
+-  ``Name``: The name of the problem.
+-  ``NumVars``: Number of variables in the state vector.
+-  ``Parameters``: Vector of problem-specific parameters that can be
+   modified.
+-  ``RHS`` : A Right-hand-side structure that includes the ODE
+   right-hand-side function and possibly Jacobians, splittings, etc.
+   (depending on the test problem)
+-  ``TimeSpan``: Time span of the integration.
+-  ``Y0``: Initial condition of the problem.
+
+Solving problems
+---------------------
+
+Problems can be solved by calling the ``solve()`` method. 
+
+ 
+   >>> sol = problem.solve()
+   <BLANKLINE>
+   sol = 
+   <BLANKLINE>
+   struct with fields:
+      solver: 'ode45'
+      extdata: [1×1 struct]
+            x: [0 2.0095e-05 1.2057e-04 6.2295e-04 0.0031 0.0157 0.0401 0.0752 0.1224 0.1830 0.2582 0.3382 0.3853 0.4325 0.4758 0.5125 0.5552 0.6130 0.6764 … ] (1×820 double)
+            y: [3×820 double]
+         stats: [1×1 struct]
+         idata: [1×1 struct]
+
+``sol.x`` contains the time points at which the solver has calculated the solution and ``sol.y`` contains the solution at these times. 
+Optional parameters can be passed to the ``solve()`` method to control the behaviour of the solver. For example:
+
+   >>> sol = problem.solve('MaxStep', 1e-6, 'RelTol', 1e-3 , 'AbsTol', 1e-6);
+
+Visualizing solutions
+---------------------
+
+OTP has built-in plotting capabilities for visualizing the computed
+solution. The ``plot()`` method can be used to plot the solution
+trajectory. The ``plotPhaseSpace()`` method creates a phase-space
+diagram by visualizing all spatial-components of the state vector. OTP
+also supports animations for the computed solution.
+
+.. code:: matlab
+
+   % Plot the solution trajectory
+   problem.plot(sol);
+
+   % Plot the Phase-Space solution 
+   problem.plotPhaseSpace(sol);
+
+   % Create a movie of the solution 
+   problem.movie(sol);
+
+.. video:: ../_static/Lorenz-Original-Canonical.webm
+      :loop: 
+      :width: 200
+
+
+
+Changing the parameters
+------------------------
+You can change the parameters of the problem by modifying the
+``Parameters`` property of the problem object. The solution should be recalculated after updating a parameter.
+For example, changing the parameter :math:`\rho` in the Lorenz system leads to a different solution:
+
+.. code:: matlab
+
+   % Change a parameter in the Lorenz system 
+   problem.Parameters.Rho = 10
+
+   % Solve the problem again
+   sol = problem.solve('MaxStep' , 1e-4);
+   problem.movie(sol);
+
+.. video:: ../_static/Lorenz-Alternate-Canonical.webm
+      :loop: 
+      :width: 200
+Changing the solver
+-------------------
+
+OTP uses appropriate internal solvers to integrate each problem.
+However, you can plug-in your specific solvers to integrate any test problem by passing the right-hand-side
+function, time span, initial condition and other parameters to
+the solver. As an example, to use the *Implicit* ``ode23s`` time-stepping method for the Lorenz system, you can use the 
+following code:
+
+.. code:: matlab
+
+   sol = ode23s(problem.RHS.F, problem.TimeSpan, problem.Y0, ...
+                odeset('Jacobian', problem.RHS.Jacobian));
+This is particularly useful when you want to compare the performance of different solvers on the same problem.
+
+Next Steps
+------------------------
+Explore different problems available in OTP by browsing the Problems Gallery in the sidebar. You can define your custom 
+problems by creating a new class that inherits from the ``otp.Problem`` class. 
+See the `Contributing Guide <../contributing>`_  for more details.