From 1e68f4bbe086dba814abb04daca20dc1537e6281 Mon Sep 17 00:00:00 2001 From: "Igor T. Ghisi" Date: Fri, 24 May 2024 18:32:40 -0300 Subject: [PATCH] Update docs considering changes on Rocky 24R2 - Explicit list PyRocky differences on GetTimeSet and GetCurves methods - Use "PrePost Scripting" instead of "PrePost API" to refers to the Rocky scripting feature (changed on 24R2) - Fix the docstring content of launcher.py - CONTRIBUTING.md now points to the PyRock Contributing section of PyRocky Developer's Guide - Adds a small intro to the Developer's guide index page and remove the "How to Contribute" card (not something we want to highlight for the casual user) --- CONTRIBUTING.md | 4 ++-- README.rst | 9 ++++----- doc/source/getting_started/index.rst | 9 ++------- doc/source/index.rst | 13 ++++++------- doc/source/user_guide/index.rst | 25 +++++++++++++++++-------- src/ansys/rocky/core/client.py | 5 ++++- src/ansys/rocky/core/launcher.py | 2 +- 7 files changed, 36 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c1b3a0f7..e365b7bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,5 @@ # Contributing -For contributing to this project, please refer to the [PyAnsys Developer's Guide]. +For contributing to this project, please refer to the [PyRocky Developer's Guide]. -[PyAnsys Developer's Guide]: https://dev.docs.pyansys.com/how-to/contributing.html \ No newline at end of file +[PyRocky Developer's Guide]: https://rocky.docs.pyansys.com/version/dev/contributing.html \ No newline at end of file diff --git a/README.rst b/README.rst index d6792a22..8e6e78b2 100644 --- a/README.rst +++ b/README.rst @@ -3,10 +3,9 @@ PyRocky |pyansys| |MIT| |python| |pypi| |codecov| |MIT| |black| |pre-commit| -PyRocky is a Python client library for remotely controlling -`Ansys Rocky `_, -which is the most powerful software in the market for performing -DEM (discrete element method) simulations. +PyRocky is a Python client library to create, run and post-processing +particle dynamics simulations using `Ansys Rocky `_, +the most powerful DEM (discrete element method) software in the market. Documentation and issues ------------------------ @@ -19,7 +18,7 @@ The documentation has five sections: - `Getting started `_: Learn how to install PyRocky in user mode and then launch it. - `User guide `_: Understand how to - use the Rocky PrePost API with PyRocky. + use the Rocky PrePost Scripting with PyRocky. - `API reference `_: Understand PyRocky API endpoints, their capabilities, and how to interact with them programmatically. - `Examples `_: Explore end-to-end diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 78e7667b..e5a5dbae 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -4,11 +4,6 @@ Getting started =============== -PyRocky is a Python client library for remotely controlling -`Ansys Rocky `_, -which is the most powerful software in the market for performing -DEM (discrete element method) simulations. - Install PyRocky --------------- @@ -51,9 +46,9 @@ Connect to an existing session Assume that a Rocky session is started with the ``--pyrocky`` option: -.. code:: bat +.. code:: - C:\Program Files\Ansys Inc\v241\Rocky> bin\Rocky.exe --pyrocky + C:\Program Files\Ansys Inc\v242\Rocky\bin\Rocky.exe --pyrocky When the Rocky session is started in this way, you can connect to it with PyRocky: diff --git a/doc/source/index.rst b/doc/source/index.rst index 5d82cda0..b4388bd7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,5 +1,11 @@ PyRocky ####### + +PyRocky is a Python client library to create, run and post-processing +particle dynamics simulations using `Ansys Rocky `_, +the most powerful DEM (discrete element method) software in the market. + + .. grid:: 2 :gutter: 2 3 3 4 @@ -36,13 +42,6 @@ PyRocky Explore end-to-end examples that show how to use PyRocky. - .. grid-item-card:: Contribute :fa:`people-group` - :padding: 2 2 2 2 - :link: contributing - :link-type: doc - - Learn how to contribute to the PyRocky codebase or documentation. - .. toctree:: :hidden: :maxdepth: 3 diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst index 1b1ac6f9..72adc985 100644 --- a/doc/source/user_guide/index.rst +++ b/doc/source/user_guide/index.rst @@ -4,24 +4,34 @@ User guide ========== +Use the Rocky PrePost Scripting +------------------------------- -Use the Rocky PrePost API -------------------------- - -Most of the Rocky PrePost API is available through the ``api`` object. For example, -the following code creates a project and saves it to disk: +In its current shape, PyRocky is a thin layer that enables remote calls to Rocky using the +PrePost Scripting API. This API is available through the ``RockyClient.api`` object. For +example, the following code creates a project and saves it to disk: .. code:: python + rocky = pyrocky.launch_rocky() api = rocky.api + project = api.CreateProject() study = project.GetStudy() study.SetName("My Study") api.SaveProject("my-project.rocky")) -To view comprehensive PrePost API documentation, in the Rocky app, select -**Help > Manuals > API PrePost**. +To view comprehensive PrePost Scripting documentation, in the Rocky app, select +**Help > Manuals > PrePost Scripting**. + +Most methods of the PrePost Scripting, when called through PyRocky, works in the exact same way +they work in the Rocky built-in Python Shell. However, there are differences worth noting: + +- ``KAStudy.GetTimeSet``: on PyRocky this method will return a ``numpy.array`` of simulation time + steps in seconds (instead of a ``TimeSet`` object). +- ``KAElementItem.GetCurve``: this method is not supported by PyRocky. Use ``GetNumpyCurve`` to + get resulting curves from study entities. Known issues @@ -29,4 +39,3 @@ Known issues - When opened with the Rocky UI visible (non-headless mode), PyRocky cannot deal with confirmation or error dialogs. For example, a call to the ``CloseProject()`` method asks for confirmation, causing PyRocky to freeze until **OK** or **Cancel** is clicked in the Rocky UI. -- Some API methods may not work. diff --git a/src/ansys/rocky/core/client.py b/src/ansys/rocky/core/client.py index d428e206..66932300 100644 --- a/src/ansys/rocky/core/client.py +++ b/src/ansys/rocky/core/client.py @@ -19,7 +19,10 @@ # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -"""Module with the client operations of Rocky.""" +""" +Module that defines the RockyClient class, which act as a proxy for a Rocky application +session. +""" from collections.abc import Callable, Generator import pickle from typing import Any, Final diff --git a/src/ansys/rocky/core/launcher.py b/src/ansys/rocky/core/launcher.py index a0020aa3..58b4858d 100644 --- a/src/ansys/rocky/core/launcher.py +++ b/src/ansys/rocky/core/launcher.py @@ -19,7 +19,7 @@ # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -"""Module for launching operations of the Rocky backend.""" +"""Module that exposes functions to launch Rocky application.""" import contextlib import os from pathlib import Path