From 394298bcf9e1ec65a1a7fcf5a97c79b710d51428 Mon Sep 17 00:00:00 2001 From: Dante Newman Date: Mon, 20 May 2024 14:06:46 -0500 Subject: [PATCH 1/6] add machine and operating point sections to code and documentation .rst files --- docs/source/code.rst | 45 ++++++++++++++++++++++ docs/source/documentation.rst | 70 ++++++++++++++++++++++++++++++++++- 2 files changed, 114 insertions(+), 1 deletion(-) diff --git a/docs/source/code.rst b/docs/source/code.rst index fde0ded5..1c658038 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -58,3 +58,48 @@ 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. Aspects to consider: + +1. Required parameters + 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. +2. Machine characteristic dictionaries + a. Dictionaries must be initialized such that a ``machine`` or ``radial_machine`` is fully defined + b. Required dictionaries are ``dimensions``, ``parameters``, ``materials``, and ``winding`` +3. Checks + a. Required to validate if machine is fully defined + b. Check defined dictonaries against machine requirements + c. Throws error if machine is not fully defined +4. Machine properties + a. Required for any machine variable desired in processing or post-processing +5. 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 a the 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 +3. Recommended practices + 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 From b57311dcf5358b3e1d698fef055af9aadcec15ea Mon Sep 17 00:00:00 2001 From: Dante Newman <112111913+dmnewman3@users.noreply.github.com> Date: Sun, 23 Jun 2024 18:52:44 -0500 Subject: [PATCH 2/6] Update docs/source/code.rst Co-authored-by: Takahiro <114006024+noguchi-takahiro@users.noreply.github.com> --- docs/source/code.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/code.rst b/docs/source/code.rst index 1c658038..39525215 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -72,7 +72,7 @@ Each machine module must consist of only **one** of each of the following classe Machine Class ******************************************* -The Machine class is where the machine definition is expected to occur. Aspects to consider: +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. Required parameters 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. From d50ac760a6d7755fceb7dd861b4f5fce11578fd4 Mon Sep 17 00:00:00 2001 From: Dante Newman <112111913+dmnewman3@users.noreply.github.com> Date: Sun, 23 Jun 2024 18:53:05 -0500 Subject: [PATCH 3/6] Update docs/source/code.rst Co-authored-by: Takahiro <114006024+noguchi-takahiro@users.noreply.github.com> --- docs/source/code.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/code.rst b/docs/source/code.rst index 39525215..7e62ec28 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -74,7 +74,7 @@ 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. Required parameters +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. 2. Machine characteristic dictionaries a. Dictionaries must be initialized such that a ``machine`` or ``radial_machine`` is fully defined From 9075d27462ff3ed84702d66477b8d0702b2e8ed8 Mon Sep 17 00:00:00 2001 From: Dante Newman <112111913+dmnewman3@users.noreply.github.com> Date: Sun, 23 Jun 2024 18:54:26 -0500 Subject: [PATCH 4/6] Update docs/source/code.rst Co-authored-by: Takahiro <114006024+noguchi-takahiro@users.noreply.github.com> --- docs/source/code.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/code.rst b/docs/source/code.rst index 7e62ec28..ee45698b 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -76,6 +76,8 @@ The Machine class is where the machine definition is expected to occur, and it s 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. 2. Machine characteristic dictionaries a. Dictionaries must be initialized such that a ``machine`` or ``radial_machine`` is fully defined b. Required dictionaries are ``dimensions``, ``parameters``, ``materials``, and ``winding`` From e67a0cfe6a53fd4cca74558b4f5cc18afd7ad122 Mon Sep 17 00:00:00 2001 From: Dante Newman <112111913+dmnewman3@users.noreply.github.com> Date: Sun, 23 Jun 2024 18:54:56 -0500 Subject: [PATCH 5/6] Update docs/source/code.rst Co-authored-by: Takahiro <114006024+noguchi-takahiro@users.noreply.github.com> --- docs/source/code.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/source/code.rst b/docs/source/code.rst index ee45698b..8186943c 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -102,6 +102,9 @@ The purpose of the Machine Operating Point class is to define a the operating po 2. Code comments on user input a. Provide short description of each operating point argument b. Specify argument units if applicable -3. Recommended practices +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 From 87dfb5811799968f6c67ca495444b667ca03d145 Mon Sep 17 00:00:00 2001 From: Dante Newman Date: Sun, 23 Jun 2024 20:30:40 -0500 Subject: [PATCH 6/6] make changes based on Takahiro's feedback --- docs/source/code.rst | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/source/code.rst b/docs/source/code.rst index 8186943c..de8a7a93 100644 --- a/docs/source/code.rst +++ b/docs/source/code.rst @@ -78,23 +78,18 @@ The Machine class is where the machine definition is expected to occur, and it s 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. -2. Machine characteristic dictionaries - a. Dictionaries must be initialized such that a ``machine`` or ``radial_machine`` is fully defined - b. Required dictionaries are ``dimensions``, ``parameters``, ``materials``, and ``winding`` -3. Checks - a. Required to validate if machine is fully defined - b. Check defined dictonaries against machine requirements - c. Throws error if machine is not fully defined -4. Machine properties - a. Required for any machine variable desired in processing or post-processing -5. Code comments on user input + * 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 a the operating point for the machine defined in the previous step. Aspects to consider: +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 @@ -102,6 +97,7 @@ The purpose of the Machine Operating Point class is to define a the operating po 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