Merge remote-tracking branch 'origin/main' into Docs_Update_12_23

# Conflicts:
#	doc/source/methods/geometry_functions.rst
#	doc/source/methods/index.rst

.github/CODEOWNERS

@@ -1,4 +1,4 @@
-* @jgsdavies @ravi-ansys @JackB-Ansys
+* @jgsdavies @ravi-ansys @JackB-Ansys @MatthewAnsys
 
 # Geometry
 /doc/source/methods/geometry_functions.rst @MatthewAnsys @jgsdavies

.github/workflows/ci_cd.yml

@@ -72,7 +72,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python ${{ env.MAIN_PYTHON_VERSION }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
 
@@ -84,7 +84,7 @@ jobs:
         # Only the tox environment specified in the tox.ini gh-actions is run
         run: tox -e py310-coverage  
 
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v4
         name: 'Upload coverage to Codecov'
 
 
@@ -101,7 +101,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python ${{ env.MAIN_PYTHON_VERSION }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
 
@@ -175,7 +175,7 @@ jobs:
         run: ls -R
 
       - name: "Release to GitHub"
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
         with:
           files: |
             ./**/*.whl

.github/workflows/label.yml

@@ -71,7 +71,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Suggest to add labels
-      uses: peter-evans/create-or-update-comment@v3
+      uses: peter-evans/create-or-update-comment@v4
       # Execute only when no labels have been applied to the pull request
       if: toJSON(github.event.pull_request.labels.*.name) == '{}'
       with:

.github/workflows/nightly-motorcad-check.yml

@@ -34,7 +34,7 @@ jobs:
           taskkill /IM MotorLABruntime.exe /F /FI "STATUS eq RUNNING"
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 

.gitignore

@@ -159,4 +159,31 @@ _autosummary/
 #vscode
 .vscode
 
+#docs
 doc/source/examples/gallery_examples/*
+/doc/source/methods/_autogen_*
+**/sg_execution_times.rst
+/doc/source/methods/_autosummary_*
+/doc/source/examples/
+
+# examples
+/examples/basics/ActiveX_Scripting_EMagnetic/*
+/examples/basics/e8_mobility/*
+/examples/ActiveX_Scripting_EMagnetic.mot
+/examples/basics/e8_mobility.mot
+/examples/links/e8_mobility.mot
+/examples/links/e8_mobility/*
+/examples/Export_EMag_Results.csv
+/examples/basics/MotorCAD_Thermal_Python/*
+/examples/Maximum Torque VS Speed Curve.png
+/examples/MotorCAD_Thermal_Python.mot
+/examples/internal_scripting/temp_example_file.py
+
+# tests
+/tests/test_files/SRM_test_file/*
+/tests/test_files/IM_test_file/*
+/tests/test_files/temp_files/*
+/tests/test_files/external_circuit.ecf
+/tests/test_files/base_test_file/*
+/tests/test_files/SaveLoadFiles/*
+/tests/test_files/SaveLoadFiles.mot

doc/source/conf.py

@@ -70,7 +70,7 @@
     # Modules for which function level galleries are created.  In
     "doc_module": "ansys-motorcad-core",
     "image_scrapers": "matplotlib",
-    "ignore_pattern": "flycheck*",
+    "ignore_pattern": "flycheck*|temp_example_file.*",
 }
 
 # Intersphinx mapping

doc/source/contributing.rst

@@ -54,7 +54,7 @@ Adhere to code style
 
 PyMotorCAD is compliant with the `PyAnsys code style
 <https://dev.docs.pyansys.com/coding-style/index.html>`_. it
-uses the tool `pre-commit <pre-commit_>`_ to check the code style.
+uses the tool `pre-commit <pre-commit_>`_ to enforce the code style.
 You can install and activate this tool with this code::
 
     pip install pre-commit

doc/source/methods/geometry_functions.rst

@@ -1,10 +1,11 @@
 .. _ref_geometry_functions:
-Adaptive geometry
-=================
-
 .. currentmodule:: ansys.motorcad.core.geometry
-
-Add some info here about adaptive geometry
+Geometry objects and functions
+==============================
+Geometry functions are used to define and modify
+the Motor-CAD Adaptive Templates geometry using PyMotorCAD.
+More information on Adaptive Templates is available
+in the :ref:`ref_user_guide` under :ref:`ref_adaptive_templates_UG`.
 
 
 Geometry objects

doc/source/methods/geometry_shapes.rst

@@ -0,0 +1,18 @@
+.. _ref_geometry_shapes:
+.. currentmodule:: ansys.motorcad.core.geometry_shapes
+Geometry shapes
+==============================
+Geometry shape functions are used to define and modify
+the Motor-CAD Adaptive Templates geometry using PyMotorCAD.
+More information on Adaptive Templates is available
+in the :ref:`ref_user_guide` under :ref:`ref_adaptive_templates_UG`.
+
+.. autosummary::
+   :toctree: _autosummary_geometry_shapes
+
+   square
+   eq_triangle_h
+   eq_triangle_w
+   triangular_notch
+
+

doc/source/methods/index.rst

@@ -1,3 +1,4 @@
+.. _ref_API_Reference:
 .. currentmodule:: ansys.motorcad
 
 API reference
@@ -23,12 +24,21 @@ object, its single class, and its many methods, see
    In addition to giving the available methods, their replacement functions
    have been commented.
 
-Adaptive geometry
-------------------
+Geometry objects and functions
+------------------------------
+The ``ansys.motorcad.core.geometry`` library contains geometry objects and functions
+that provide geometry capability in Python.
+Geometry objects and functions are used for
+defining and modifying Adaptive Templates geometries in Python.
+For descriptions of the objects and functions, see :ref:`ref_geometry_functions`.
 
-Adaptive geometry can be used to set up custom geometries in Motor-CAD.
-For descriptions of adaptive geometry objects and functions, see
-:ref:`ref_geometry_functions`.
+Geometry shapes
+------------------------------
+The ``ansys.motorcad.core.geometry_shapes`` library contains geometry functions
+that provide geometry calculations in Python.
+Geometry shapes functions are used for
+defining and modifying Adaptive Templates geometries in Python.
+For descriptions of the functions, see :ref:`ref_geometry_shapes`.
 
 Utility functions
 ------------------
@@ -53,3 +63,4 @@ For descriptions, see
    geometry_functions
    utility_functions
    MotorCAD_errors
+   geometry_shapes

doc/source/methods/template.rst_template

@@ -1,3 +1,4 @@
+.. _ref_Category_API:
 Category
 ==============================
 

doc/source/user_guide/Motor-CAD_setup.rst

@@ -0,0 +1,125 @@
+.. _ref_Motor-CAD_setup:
+
+Motor-CAD setup
+===============
+
+This section covers PyMotor-CAD options which are accessed from the Motor-CAD UI.
+
+Registering Motor-CAD for automation
+------------------------------------
+
+Before you can run any scripts to interact with Motor-CAD, you must first verify the current version of Motor-CAD is
+registered for automation.
+
+To do this, select Defaults -> Automation to open the registration window and click Update to current version.
+If the current version is already registered, this is greyed out as in the image below. Click OK.
+
+.. image:: /_static/Motor-CAD_setup_update_to_current_version.png
+    :width: 400
+
+.. note::
+   PyMotorCAD creates and runs from a new instance of Motor-CAD unless otherwise specified in the creation of the
+   Motor-CAD object. If the Motor-CAD object is set to not open a new instance, then it connects with any open
+   Motor-CAD window regardless of version number and without preference for any particular one.
+
+
+Automation parameter names
+--------------------------
+
+Scripting in Motor-CAD usually involves setting parameters (for example: geometry, operating point definition, cooling,
+calculation options), running calculations, and then retrieving results (for example: torque, efficiency, losses).
+To do this, the correct Motor-CAD parameter name must be known.
+
+A list of all Motor-CAD parameters available via automation can be found under Help -> automation Parameter Names.
+
+.. image:: /_static/Motor-CAD_setup_automation_parameter_names_dropdown.png
+    :width: 600
+
+.. image:: /_static/Motor-CAD_setup_automation_parameter_names.png
+    :width: 600
+
+.. note::
+   The list can be filtered to find the required parameter. Typically, the automation parameter names are the same as
+   the displayed name in the Motor-CAD interface, with spaces replaced by underscores for example: for Pole Number the
+   automation name is ``Pole_Number``.
+
+For most parameters, the automation name can also be found by hovering the mouse over the input control or the parameter
+row in the output data sheet. The status bar shows a description of the parameter, followed by its automation name
+in curly brackets.
+
+For example, here the mouse is hovered over the magnetization radio group in the calculation tab,
+showing that the parameter name is ``Magnetization``.
+
+.. image:: /_static/Motor-CAD_setup_automation_parameter_hover.png
+    :width: 600
+
+You can also press ``F2`` with the control in focus and the automation parameter list is shown with
+the correct parameter name automatically entered in the search box.
+
+``Ctrl + F2`` copies the automation name of the control which is currently selected.
+
+.. note::
+   If a parameter cannot be found in this way, an alternative method is to set the parameter to a distinctive value
+   through the user interface, for example: 1234. You can then find the parameter by filtering the Automation Parameters
+   list by this value.
+
+
+GUI in automation
+-----------------
+
+If Motor-CAD is launched by an external script then by default the GUI is not shown. This improves the speed of startup
+and decrease the memory usage while scripting. If the GUI is required during scripting, for example for troubleshooting
+or to script UI commands (for example: taking screenshots from Motor-CAD), this option can be enabled.
+This setting applies to all instances of this Motor-CAD version.
+
+.. image:: /_static/Motor-CAD_setup_set_visible.png
+    :width: 400
+
+.. currentmodule:: ansys.motorcad.core.motorcad_methods.MotorCAD
+
+Regardless of this option, during a script the Motor-CAD GUI can be shown or hidden at any time using the
+command :meth:`set_visible`.
+
+
+Some scripting commands require the GUI to be shown, for example :meth:`display_screen`, :meth:`save_screen_to_file`
+When changing model parameters via automation with the GUI visible, Motor-CAD does not update the user interface
+with the new parameter value at every step, to speed up the scripting. However, this means that you should
+never change a parameter which is shown on the currently displayed tab. It is best practice to run all scripts with
+the Scripting tab visible. This should be set before changing any parameters with the command
+
+.. code:: python
+
+   mcApp.display_screen("scripting")
+
+This needS to be called after loading any files or setting context, before any calls to :meth:`set_variable`.
+
+
+Units
+-----
+
+In Motor-CAD, the units can be changed under Defaults -> Units, this displays values in the interface in the
+selected units.
+
+However, variables are not be converted for use in automation and so values are always given in the Motor-CAD default
+units. This applies both when setting input variables and retrieving output results. To see what these default values
+are, navigate to Help -> Automation Parameter Names (or press F2) where the parameters are displayed with their
+default units.
+
+As an example, go the thermal context and navigate to Input Data -> Cooling
+
+.. image:: /_static/Motor-CAD_setup_cooling_page.png
+    :width: 600
+
+Change the default temperature units in the interface to Fahrenheit:
+
+.. image:: /_static/Motor-CAD_setup_change_temp_unit.png
+    :width: 400
+
+Search for ``T_ambient`` in the Automation Parameters list and change the value to 100:
+
+.. image:: /_static/Motor-CAD_setup_check_temp.png
+    :width: 600
+
+It can be seen that the current value is given in the units specified in the automation parameters list and not the
+default units selected in the GUI. The displayed interface value is in ℉ and the set value in the list is in ℃.
+