Merge pull request #15 from chrislupp/feature/documentation

Feature/documentation

README.md

@@ -1,6 +1,7 @@
 ![Philote](doc/graphics/philote-python.svg)
 
 [![Unit and Regression Tests](https://github.com/chrislupp/Philote-Python/actions/workflows/tests.yaml/badge.svg)](https://github.com/chrislupp/Philote-Python/actions/workflows/tests.yaml)
+[![Deploy Documentation](https://github.com/chrislupp/Philote-Python/actions/workflows/documentation.yaml/badge.svg)](https://github.com/chrislupp/Philote-Python/actions/workflows/documentation.yaml)
 # Philote-Python
 
 Python library for using and creating Philote analysis servers.
@@ -19,15 +20,15 @@ The installation process requires the following tools to be installed:
 - importlib.resources
 
 Additionally, the following dependencies are required by Philote MDO and will be
-installed automatically during the installation process (if not process):
+installed automatically during the installation process:
 
 - numpy
 - grpcio
 
 
 ## Installation
 
-The Philote MDO Python bindings require a two step installation process. First,
+The Philote MDO Python library requires a two step installation process. First,
 make sure that `grpcio-tools` and `protoletariat` are installed. If not, they
 can be installed using pip. Note, that the first step of the installation
 process will not complete without these tools. Unlike the other dependencies,
@@ -59,7 +60,7 @@ version of gRPC that you have installed) and make it discoverable on your PATH.
 
 This package is licensed under the Apache 2 license:
 
-   Copyright 2022-2023 Christopher A. Lupp
+   Copyright 2022-2024 Christopher A. Lupp
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

doc/_config.yml

@@ -4,7 +4,7 @@
 title: Philote-Python
 author: Christopher A. Lupp
 logo: graphics/philote-python.svg
-copyright: 2022-2023
+copyright: 2022-2024
 
 # Force re-execution of notebooks on each build.
 # See https://jupyterbook.org/content/execute.html
@@ -53,3 +53,7 @@ html:
 sphinx:
   extra_extensions:
   - 'sphinx.ext.autodoc'
+  - 'sphinx.ext.napoleon'
+  - 'sphinx.ext.viewcode'
+  config:
+      add_module_names: False

doc/_toc.yml

@@ -3,9 +3,27 @@
 
 format: jb-book
 root: intro
-chapters:
-- file: tutorials/quickstart
-- file: tutorials/explicit_disciplines
-- file: tutorials/openmdao
-- file: tutorials/csdl
+parts:
+- caption: Getting Started
+  chapters:
+    - file: installation
+    - file: tutorials/quickstart
+
+- caption: Tutorials
+  chapters:
+  - file: tutorials/explicit_disciplines
+  - file: tutorials/implicit_disciplines
+  - file: tutorials/units
+
+- caption: Working with OpenMDAO
+  chapters:
+  - file: tutorials/openmdao
+
+- caption: Working with CSDL
+  chapters:
+  - file: tutorials/csdl
+
+#- caption: API Reference
+#  chapters:
+#  - file: api/explicit
 

doc/api/explicit.md

@@ -0,0 +1,2 @@
+# Explicit Discipline
+

doc/installation.md

@@ -0,0 +1,42 @@
+# Installation
+
+Philote-Python is a pure Python library. However, the installation process requires a few extra steps,
+as the gRPC/protobuf definitions must first be compiled into 
+
+
+## Requirements
+
+The installation process requires the following tools to be installed:
+
+- grpcio-tools
+- protoletariat
+- importlib.resources
+
+Additionally, the following dependencies are required by Philote MDO and will be
+installed automatically during the installation process:
+
+- numpy
+- grpcio
+
+
+## Compiling Definitions and Installation
+
+The Philote MDO Python library requires a two step installation process. First,
+make sure that `grpcio-tools` and `protoletariat` are installed. If not, they
+can be installed using pip. Note, that the first step of the installation
+process will not complete without these tools. Unlike the other dependencies,
+pip will not automatically install them during the package build. The first step
+is to compile the protobuf/gRPC files into python files. This is done by running
+(from the repository directory):
+
+    python setup.py compile_proto
+
+Once this step completes successfully, the package can be installed using pip:
+
+    pip install .
+
+or
+
+    pip install -e .
+
+for a development install.

doc/intro.md

@@ -1,11 +1,6 @@
 # Philote-Python
 
-This is a small sample book to give you a feel for how book content is
-structured.
-It shows off a few of the major file types, as well as some sample content.
-It does not go in-depth into any particular topic - check out [the Jupyter Book documentation](https://jupyterbook.org) for more information.
 
-Check out the content pages bundled with this sample book to see more.
 
 :::{tableofcontents}
 :::

doc/tutorials/csdl.md

@@ -1,2 +1,4 @@
 (tutorials:csdl)=
-# Calling Philote Disciplines from CSDL
+# Calling Philote Disciplines from CSDL
+
+This feature is a work in progress and not yet complete.

doc/tutorials/explicit_disciplines.md

@@ -1,15 +1,138 @@
 (tutorials:explicit)=
-# Working with Explicit Disciplines
+# Creating Explicit Disciplines
+
+The {ref}`tutorials:quick_start` guide introduces explicit disciplines without elaborating
+on how they work or how to create them. In this section, we will cover the basics
+of creating explicit disciplines.
+
+Philote-Python implements disciplines in a similar way to OpenMDAO. We create a
+class, inheriting from a base class and then specialize some methods to run the
+calculations we want.
+
+To illustrate this, let us take a look at a simple paraboloid problem (the same
+problem as in the OpenMDAO documentation, and the same one used in the quick
+start guide):
+
+\begin{align}
+f(x,y) &= (x-3)^2 + x y + (y+4)^2 - 3
+\end{align}
+
+To create a discipline that executes this equation, we create a class and
+inherit from the ExplicitDiscipline class Philote-Python provides. Member
+functions of the inherited class are overloaded to implement the desired
+functionality. The most common function that will need to be overloaded are
+**setup**, **setup_partials**, **compute**, and in the case of a discipline that offers
+derivatives, **compute_partials**.
+
+## Setup Functions
+
+First, let us look at the setup member function:
+
+:::{code-block} python
+import philote.general as pm
+
+class Paraboloid(pmdo.ExplicitDiscipline):
+
+    def setup(self):
+        self.add_input("x", shape=(1,), units="m")
+        self.add_input("y", shape=(1,), units="m")
+
+        self.add_output("f_xy", shape=(1,), units="m**2")
+:::
+
+The **setup** function exists to define the inputs and outputs of a discipline
+(this purpose is borrowed from the OpenMDAO workflow, which operates the same
+way). The **add_input** and **add_output** member functions are provided by the
+**ExplicitDiscipline** to define both inputs and outputs. Here, two inputs (*x*
+and *y*) are defined, each with the shape of 1 (scalar) and with a unit of
+meters (no physical meaning, purely for demonstration). Furthermore, a scalar
+output (*f_xy*) was defined with the units of square meters.
 
 While the discipline gradients (or partials) can be defined within the **setup**
 function, it usually is good practice to separate these definitions into the
 **setup_partials** functions. Behind the scenes, both functions (setup and
 setup_partials) are called back-to-back, so there is no actual difference where
-the gradients are defined. To define the gradient of an output with respect to
-an input, the **declare_partials** function is invoked:
+the gradients are defined. However, using both functions to define the variables
+and partials may have organizational benefits.
+
+To define the gradient of an output with respect to an input, the
+**declare_partials** function is invoked:
+
+:::{code-block} python
+    def setup_partials(self):
+        self.declare_partials("f_xy", "x")
+        self.declare_partials("f_xy", "y")
+:::
+
+
+## Compute Function
+
+To implement the paraboloid function, the **compute** member function must be
+defined:
 
 :::{code-block} python
+    def compute(self, inputs, outputs):
+        x = inputs["x"]
+        y = inputs["y"]
+
+        outputs["f_xy"] = (x - 3.0) ** 2 + x * y + (y + 4.0) ** 2 - 3.0
+:::
+
+The *inputs* and *outputs* variables for this function are later passed in by
+the server as dictionaries with the variable names as the keys.
+
+
+## Gradient Function
+
+To implement the paraboloid function derivatives, the **compute_partials**
+member function must be defined:
+
+:::{code-block} python
+    def compute_partials(self, inputs, partials):
+        x = inputs["x"]
+        y = inputs["y"]
+
+        partials["f_xy", "x"] = 2.0 * x - 6.0 + y
+        partials["f_xy", "y"] = 2.0 * y + 8.0 + x
+:::
+
+The *inputs* and *partials* variables for this function are later passed in by
+the server as dictionaries with the variable names as the keys.
+
+
+## Summary
+
+In this section we covered the basics of creating an explicit discipline.
+The entire code for the paraboloid discipline is listed here for completeness:
+
+:::{code-block} python
+import philote_mdo.general as pmdo
+
+class Paraboloid(pmdo.ExplicitDiscipline):
+    """
+    Basic two-dimensional paraboloid example (explicit) discipline.
+    """
+
+    def setup(self):
+        self.add_input("x", shape=(1,), units="m")
+        self.add_input("y", shape=(1,), units="m")
+
+        self.add_output("f_xy", shape=(1,), units="m**2")
+
     def setup_partials(self):
         self.declare_partials("f_xy", "x")
         self.declare_partials("f_xy", "y")
-:::
+
+    def compute(self, inputs, outputs):
+        x = inputs["x"]
+        y = inputs["y"]
+
+        outputs["f_xy"] = (x - 3.0) ** 2 + x * y + (y + 4.0) ** 2 - 3.0
+
+    def compute_partials(self, inputs, partials):
+        x = inputs["x"]
+        y = inputs["y"]
+
+        partials["f_xy", "x"] = 2.0 * x - 6.0 + y
+        partials["f_xy", "y"] = 2.0 * y + 8.0 + x
+:::

doc/tutorials/implicit_disciplines.md

@@ -0,0 +1,2 @@
+
+# Creating Implicit Disciplines

doc/tutorials/openmdao.md

@@ -1,2 +1,4 @@
 (tutorials:openmdao)=
-# Calling Philote Disciplines from OpenMDAO
+# Calling Philote Disciplines from OpenMDAO
+
+This documentation is currently a work in progress.