diff --git a/docs/source/code.rst b/docs/source/code.rst index fde0ded5..de8a7a93 100644 --- a/docs/source/code.rst +++ b/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 \ No newline at end of file diff --git a/docs/source/documentation.rst b/docs/source/documentation.rst index 87a4fdc1..d2c961c5 100644 --- a/docs/source/documentation.rst +++ b/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. \ No newline at end of file +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. \ No newline at end of file