Add Machine and Operating Point Sections to Code and Documentation Files

docs/source/code.rst

@@ -58,3 +58,49 @@ The purpose of the Results class is to encapsulate the results of the analysis o
 3. Code comments 
     a. Provide short description of each argument (for a function) and return value (or attribute)
     b. Specify argument / return value / attribute units
+
+Machines
+++++++++++++++++++++++++++++++++++++++++++++
+
+Machine modules should be located within ``mach_eval/machines`` and then placed within the appropriate subdirectory.
+
+Each machine module must consist of only **one** of each of the following classes:
+
+1. Machine Class
+2. Machine Operating Point Class
+
+Machine Class
+*******************************************
+
+The Machine class is where the machine definition is expected to occur, and it should also specify any machine variable desired in processing or post-processing. Aspects to consider:
+
+1. Requirements to fully define machine
+    a. Each machine must contain parameters (such as rotor, stator, winding, etc.) defined in the ``machine`` and ``radial_machine`` classes located in the  ``mach_eval/machines`` directory.
+    b. Initialize dictionaries for ``dimensions``, ``parameters``, ``materials``, and ``winding`` to fully define a ``machine`` or ``radial_machine``.
+    c. Check defined dictonaries against machine requirements, and throw error if machine is not fully defined.
+        * Required to validate if machine is fully defined
+        * Check defined dictonaries against machine requirements
+        * Throws error if machine is not fully defined
+    d. Machine properties are required for any machine variable desired in processing or post-processing
+2. Code comments on user input
+    a. Provide short description of each argument for each dictionary 
+    b. Specify argument units if applicable
+
+Machine Operating Point Class
+*******************************************
+
+The purpose of the Machine Operating Point class is to define an operating point for the machine defined in the previous step. Aspects to consider:
+
+1. Requirements to fully define operating point
+    a. Operating point definitions will differ with applications
+    b. All necessary information about the operating state of the machine must be defined here
+2. Code comments on user input
+    a. Provide short description of each operating point argument 
+    b. Specify argument units if applicable
+
+Recommended practices
+*******************************************
+1. Provide machine specific definitions in machine class 
+2. Profide only operating point specific definitions in operating point class
+    a. Provide machine specific definitions in machine class 
+    b. Profide only operating point specific definitions in operating point class

docs/source/documentation.rst

@@ -48,4 +48,72 @@ The ``Units`` column is intended to describe the units of the function's return
 Results classes that have properties/functions that return more complicated objects can make use of multiple tables to effectively describe their functionality.
 
 A copy-paste example code block must be included that completes the example code block provided in ``Input from User`` by calling the ``analyze()`` 
-function and rendering the return values. It is recommended to include post-processing code (such as creating a plot) to further illustrate the use of the output data.
+function and rendering the return values. It is recommended to include post-processing code (such as creating a plot) to further illustrate the use of the output data.
+
+Machine Documentation
+++++++++++++++++++++++++++++++++++++++++++++
+
+Each machine within the ``eMach`` codebase must be summarized such that someone with a basic understanding of electric machines can understand the
+purpose and structure of the machine. The documentation files devoted to each machine must contain the following sections:
+
+1. Machine Background
+2. Machine Input from User
+    a. Machine Dimensions
+    b. Machine Parameters
+    c. Machine Materials
+    d. Machine Winding
+3. Creating a Machine Object
+4. Operating Point Input from User
+5. Creating an Operating Point Object
+
+Machine Background
+*******************************************
+
+Provide information to explain the motivation, application, and any other knowledge required to understand where and how the machine can be applied. This can be in the 
+form of equations, images, tables, and references to publications or other machines. Any assumptions that are made must be explained.
+
+Machine Input from User
+*******************************************
+
+Detail the required inputs to the ``machine`` class. This must include the aforementioned four inputs, with each requiring its own information:
+
+1. Machine Dimensions
+    a. Dimension information
+    b. Parameterized cross-section
+    c. Table including variables, descriptions, and units
+2. Machine Parameters
+    a. Parameter information
+    b. Table including variables, descriptions, and units
+3. Machine Materials
+    a. Material information
+    b. Material definitions
+    c. Table including material definitions and descriptions
+4. Machine Winding
+    a. Winding information
+    b. Table including variables, descriptions, and units
+    c. Winding diagram of example Winding
+
+A copy-paste example code block must be included after the each section table that illustrates the each section, which together define the overall machine object. 
+
+Creating a Machine Object
+*******************************************
+
+Define a machine object through an example copy-paste code block. A short explanation of the machine object should be included for understanding of how the machine is
+put together and what it is being used for. This code block must call the ``XX_Machine()`` class with the user-defined inputs described previously.
+
+Operating Point Input from User
+*******************************************
+
+Detail the required inputs to the ``operating_point`` class. This must include a table with the following three columns:
+
+1. Argument
+2. Description
+3. Units
+
+This table must show all required and optional inputs for the user to create a fully-defined operating point.
+
+Creating an Operating Point Object
+*******************************************
+
+Define an operating point object through an example copy-paste code block. A short explanation of the operating point object should be included for understanding of how the 
+machine condition is defined and applied to the machine itself. This code block must call the ``XX_Machine_Oper_Pt()`` class with the user-defined inputs described previously.