diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 704df8fa5d..30f1396175 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -40,9 +40,9 @@ env: # You should go up in number, if you go down (or repeat a previous value) # you might end up reusing a previous cache if it haven't been deleted already. # It applies 7 days retention policy by default. - RESET_EXAMPLES_CACHE: 2 - RESET_DOC_BUILD_CACHE: 2 - RESET_AUTOSUMMARY_CACHE: 2 + RESET_EXAMPLES_CACHE: 0 + RESET_DOC_BUILD_CACHE: 0 + RESET_AUTOSUMMARY_CACHE: 0 concurrency: group: ${{ github.workflow }}-${{ github.ref }} @@ -263,11 +263,28 @@ jobs: - name: "Install docs build requirements" run: | + pip uninstall ansys-sphinx-theme pip install .[doc] - name: "Waiting for the services to be up" run: | .ci/waiting_services.sh + + - name: Install Quarto + uses: quarto-dev/quarto-actions/setup@v2 + with: + tinytex: true + + - name: Check Quarto Version + shell: bash + run: | + quarto --version + + - name: "Install Poppler for PDF to PNG conversion" + shell: bash + run: | + sudo apt-get update + sudo apt-get install -y poppler-utils - name: "Build documentation" run: | diff --git a/README.md b/README.md index 0ad935a6b7..4f121d8fbe 100644 --- a/README.md +++ b/README.md @@ -50,8 +50,7 @@ In the upper right corner of the documentation's title bar, there is an option f viewing the documentation for the latest stable release to viewing the documentation for the development version or previously released versions. -You can also [view](https://cheatsheets.docs.pyansys.com/pymapdl_cheat_sheet.png) or -[download](https://cheatsheets.docs.pyansys.com/pymapdl_cheat_sheet.pdf) the +You can also [download](https://mapdl.docs.pyansys.com/version/stable/_static/cheat_sheet.pdf) the PyMAPDL cheat sheet. This one-page reference provides syntax rules and commands for using PyMAPDL. diff --git a/doc/changelog.d/3422.documentation.md b/doc/changelog.d/3422.documentation.md new file mode 100644 index 0000000000..f59fe58c14 --- /dev/null +++ b/doc/changelog.d/3422.documentation.md @@ -0,0 +1 @@ +docs: adding cheat sheet on documentation \ No newline at end of file diff --git a/doc/source/cheat_sheet/.gitignore b/doc/source/cheat_sheet/.gitignore new file mode 100644 index 0000000000..075b2542af --- /dev/null +++ b/doc/source/cheat_sheet/.gitignore @@ -0,0 +1 @@ +/.quarto/ diff --git a/doc/source/cheat_sheet/_static/README.md b/doc/source/cheat_sheet/_static/README.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/doc/source/cheat_sheet/cheat_sheet.qmd b/doc/source/cheat_sheet/cheat_sheet.qmd new file mode 100644 index 0000000000..f77a8e257c --- /dev/null +++ b/doc/source/cheat_sheet/cheat_sheet.qmd @@ -0,0 +1,278 @@ +--- +title: PyMAPDL cheat sheet +format: cheat_sheet-pdf +params: + version: main +footer: PyMAPDL +footerlinks: + - urls: 'https://mapdl.docs.pyansys.com/version/stable/' + text: Documentation + - urls: 'https://mapdl.docs.pyansys.com/version/stable/getting_started/index.html' + text: Getting started + - urls: 'https://mapdl.docs.pyansys.com/version/stable/examples.html' + text: Examples + - urls: 'https://mapdl.docs.pyansys.com/version/stable/api/index.html' + text: API reference + - urls: 'https://github.com/ansys/pymapdl/discussions' + text: Discussions + - urls: 'https://github.com/ansys/pmapdl/issues' + text: 'Issues' +execute: + output: false + eval: true + +latex-clean: true +latex-auto-install: true +jupyter: + jupytext: + text_representation: + extension: .qmd + format_name: quarto + format_version: '1.0' + jupytext_version: 1.16.1 + kernelspec: + display_name: Python 3 (ipykernel) + language: python + name: python3 +--- + +# Connect to MAPDL remote session + +Launch and connect to MAPDL. You can specify the version you want to use with +``version`` argument. +```{python} +#| eval: false +from ansys.mapdl.core import launch_mapdl +mapdl = launch_mapdl(version=242) +``` + +Exit a session +```{python} +#| eval: false +mapdl.exit() +``` + +Connect to an existing instance at IP address ``192.168.1.30`` and port ``50001``: +```{python} +#| eval: false +mapdl = launch_mapdl(start_instance=False, ip='192.168.1.30', port=50001) +``` + +```{python} +#| echo: false +from ansys.mapdl.core import launch_mapdl +mapdl = launch_mapdl() +``` + +Create and exit a pool of instances: +```{python} +#| eval: false +# Create a pool of 10 instances +from ansys.mapdl.core import pool +mapdl_pool = pool.MapdlPool(10) +# Exit the pool +mapdl_pool.exit() +``` + +# PyMAPDL CLI + +Access MAPDL instances through CLI +```{console} +#| eval: false +# Start an MAPDL instance at port ``50051`` +pymapdl start --port 50051 +# List the current MAPDL instances and processes +pymapdl list +# Stop all the MAPDL instances +pymapdl stop --all +``` + +# PyMAPDL commands + +PyMAPDL commands are Python statements that act as a +wrapper for APDL commands. For example: ``ESEL,s,type,1`` +is translated as +```{python} +#| echo: false +mapdl.clear() +``` +```{python} +mapdl.esel('s', 'type', vmin=1) +``` + +Help for the MAPDL class functions is accessible with: +```{python} +help(mapdl.esel) +``` + +Most of the time, commands that start with \* or \/ have these characters +removed: +```{python} +#| eval: false +mapdl.prep7() # /PREP7 +mapdl.get() # *GET +``` + +Load arrays from Python to MAPDL: +```{python} +#| echo: false +mapdl.clear() +``` +```{python} +import numpy as np +np_array = np.array([[1,2,3], [4,5,6]]) +mapdl.load_array("array_name", np_array) +``` + +Write parameters and access from or to the MAPDL database: +```{python} +# Create a parameter from a NumPy array +mapdl.parameters['my_np_param'] = np_array +# Save a parameter to a NumPy array +saved_np_array = mapdl.parameters['my_np_param'] +``` + +Access to specific model entity values with ``get_array`` and +`` get_value``. +```{python} +# List the current selected node numbers +mapdl.get_array('NODE', item1='NLIST') +# Get the number of selected nodes +total_node = mapdl.get_value(entity='node', item1='count') +``` + +# Convert APDL script to Python files + +An existing APDL script can be converted to PyMAPDL format +with the following commands: +```{python} +#| eval: false +import ansys.mapdl.core as pymapdl +pymapdl.convert_script( + "mapdl_script.dat", "pymapdl_script.py" +) +``` + +# Mesh and geometry of a model + +Store the finite element mesh as a +[VTK UnstructuredGrid data](https://vtk.org/doc/nightly/html/classvtkUnstructuredGrid.html) +object: + +```{python} +#| echo: false +##################################################################### +# Hidden example for testing purpose (3d_plate_thermal.py) +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +mapdl.clear() + +# Create a simple beam, specify the material properties, and mesh it. +mapdl.prep7() +mapdl.mp("kxx", 1, 45) +mapdl.et(1, 90) +mapdl.block(-0.3, 0.3, -0.46, 1.34, -0.2, -0.2 + 0.02) +mapdl.vsweep(1) + +# Set the thermal boundary conditions +mapdl.asel("S", vmin=3) +mapdl.nsla() +mapdl.d("all", "temp", 5) +mapdl.asel("S", vmin=4) +mapdl.nsla() +mapdl.d("all", "temp", 100) +out = mapdl.allsel() + +mapdl.vsweep(1) +``` + +```{python} +grid = mapdl.mesh.grid +``` + +Save element and node numbers to Python arrays with +the ``mapdl.mesh`` and the ``mapdl.geometry`` classes. + + +```{python} +# Get an array of the nodal coordinates +nodes = mapdl.mesh.nodes +# Save node numbers of selected nodes to an array +node_num = mapdl.mesh.nnum +# Save volume numbers of selected nodes to an array +volum_numbers = mapdl.geometry.vnum +# Save keypoint numbers of selected nodes to an array +keypoints = mapdl.geometry.keypoints +``` + +# Solve an analysis + +```{python} +mapdl.solution() +mapdl.solve() +mapdl.finish() +``` + +# Post-process results + +The +[PostProcessing](https://mapdl.docs.pyansys.com/version/stable/api/_autosummary/ansys.mapdl.core.post.PostProcessing.html#ansys.mapdl.core.post.PostProcessing) +class is used for plotting and saving results to NumPy arrays. + +```{python} +mapdl.post1() +mapdl.set(1, 1) +mapdl.allsel() + +# Plot nodal temperatures +mapdl.post_processing.plot_nodal_temperature() +# Save nodal temperatures to a Python array +nodal_temp= mapdl.post_processing.nodal_temperature() +``` + +You can store the command output following the +[Postprocessing object methods](https://mapdl.docs.pyansys.com/version/stable/user_guide/post.html#postprocessing-object-methods): +```{python} +cmd = mapdl.prnsol("TEMP") +cmd.to_list() +``` + +# Create nice plots + +Use [PyVista](https://docs.pyvista.org/) to interpolate data, save results +and store them in the underlying +[UnstructuredGrid](https://docs.pyvista.org/api/core/_autosummary/pyvista.unstructuredgrid#) +object: + +```{python} +from pyvista import Plotter +pl = Plotter() +pm = mapdl.post_processing.plot_element_stress( + "X", return_plotter=True +) +pl.add_mesh(pm.meshes[0]) +pl.show() +``` + +```{python} +#| eval: false +# Plot selected elements +mapdl.eplot() +# Plot selected volumes +mapdl.vplot() +# Plot selected areas +mapdl.aplot() +# Plot selected lines +mapdl.lplot() +``` + +```{python} +#| eval: false +# Testing one of the above plotting +mapdl.eplot() +``` + +```{python} +#| echo: false +mapdl.exit() +``` \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index e6759e1f6b..f874f6f4c7 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -11,11 +11,15 @@ import numpy as np import pyvista from sphinx.application import Sphinx +from sphinx.util import logging from sphinx_gallery.sorting import FileNameSortKey from ansys.mapdl import core as pymapdl from ansys.mapdl.core import __version__ +# Convert notebooks into Python scripts and include them in the output files +logger = logging.getLogger(__name__) + viz_interface.DOCUMENTATION_BUILD = True pyvista.BUILDING_GALLERY = True pyvista.OFF_SCREEN = True @@ -93,6 +97,7 @@ "sphinx.ext.intersphinx", "sphinx_autodoc_typehints", "sphinx_design", + "sphinx_jinja", "sphinx_copybutton", "sphinx_gallery.gen_gallery", "sphinxemoji.sphinxemoji", @@ -107,7 +112,7 @@ "numpy": ("https://numpy.org/doc/stable/", None), "matplotlib": ("https://matplotlib.org/stable/", None), "pandas": ("https://pandas.pydata.org/docs/", None), - "pyvista": ("https://docs.pyvista.org/version/stable/", None), + "pyvista": ("https://docs.pyvista.org", None), "grpc": ("https://grpc.github.io/grpc/python/", None), "pypim": ("https://pypim.docs.pyansys.com/version/dev/", None), "ansys-dpf-core": ("https://dpf.docs.pyansys.com/version/stable/", None), @@ -306,11 +311,11 @@ "json_url": f"https://{cname}/versions.json", "version_match": switcher_version, }, - "use_meilisearch": { - "api_key": os.getenv("MEILISEARCH_PUBLIC_API_KEY", ""), - "index_uids": { - f"pymapdl-v{switcher_version.replace('.', '-')}": "PyMAPDL", - }, + "cheatsheet": { + "file": "cheat_sheet/cheat_sheet.qmd", + "title": "PyMAPDL cheat sheet", + "version": f"v{version}", + "pages": ["getting_started/learning"], }, } @@ -429,3 +434,8 @@ def setup(app: Sphinx): from helpers import HideObject app.add_directive("hideobject", HideObject) + + +jinja_contexts = { + "cheat_sheet": {"version": switcher_version}, +} diff --git a/doc/source/getting_started/Cheat_Sheet_PyMAPDL.pdf b/doc/source/getting_started/Cheat_Sheet_PyMAPDL.pdf deleted file mode 100644 index f5639146a5..0000000000 Binary files a/doc/source/getting_started/Cheat_Sheet_PyMAPDL.pdf and /dev/null differ diff --git a/doc/source/getting_started/learning.rst b/doc/source/getting_started/learning.rst index 14ad0e46e0..5ab22e88b3 100644 --- a/doc/source/getting_started/learning.rst +++ b/doc/source/getting_started/learning.rst @@ -38,11 +38,12 @@ Downloads These are versions valid during a year and with limited capabilities regarding number of nodes, elements, etc. -- View and download :download:`PyMAPDL cheatsheet ` to help - you to learn PyMAPDL. +.. jinja:: cheat_sheet + + - View and download :download:`PyMAPDL cheatsheet ` + to help you to learn PyMAPDL. -- Visit :ref:`ref_examples` to learn how PyMAPDL can be - used to solve different real problems. +- Visit :ref:`ref_examples` to learn how PyMAPDL can be used to solve different real problems. Courses diff --git a/doc/source/getting_started/project.rst b/doc/source/getting_started/project.rst index 7a0c093a1e..9bf7d7d202 100644 --- a/doc/source/getting_started/project.rst +++ b/doc/source/getting_started/project.rst @@ -174,10 +174,8 @@ In the upper right corner of the documentation's title bar, there is an option f viewing the documentation for the latest stable release to viewing the documentation for the development version or previously released versions. -You can also `view `_ or -`download `_ the -PyMAPDL cheat sheet. This one-page reference provides syntax rules and commands -for using PyMAPDL. +You can also `download `_ the PyMAPDL cheat sheet. This one-page reference provides +syntax rules and commands for using PyMAPDL. On the `PyMAPDL Issues `_ page, you can create issues to report bugs and request new features. On the `PyMAPDL Discussions diff --git a/doc/source/links.rst b/doc/source/links.rst index a08e6575d5..6d4cea20b0 100644 --- a/doc/source/links.rst +++ b/doc/source/links.rst @@ -82,6 +82,8 @@ .. _pymapdl_ex_repo: https://github.com/ansys/pymapdl-examples .. _pymapdl_ex_ts: https://examples.mapdl.docs.pyansys.com/technology_showcase_examples/index.html .. _pymapdl_ex_vm: https://examples.mapdl.docs.pyansys.com/verif-manual/index.html +.. _pymapdl_cheat_sheet: https://mapdl.docs.pyansys.com/stable/_static/_static/cheat_sheet.pdf + .. # Ansys Structural Guide links: .. _ansys_krylov_sweep_harmonic_analysis: https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/%%VERSION%%/en/ans_str/str_Krysweep.html diff --git a/pyproject.toml b/pyproject.toml index 2d9c909883..aec79298ac 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -76,13 +76,15 @@ doc = [ "ansys-dpf-core==0.10.1", "ansys-mapdl-reader==0.54.1", "ansys-tools-visualization-interface==0.4.4", - "ansys-sphinx-theme==1.0.11", + "ansys-sphinx-theme==1.1.2", "grpcio==1.66.1", "imageio-ffmpeg==0.5.1", "imageio==2.35.1", + "jupyter==1.1.1", "jupyter_sphinx==0.5.3", "jupyterlab>=3.2.8", "matplotlib==3.9.2", + "nbformat==5.10.4", "numpydoc==1.8.0", "pandas==2.2.3", "plotly==5.24.1", @@ -95,6 +97,7 @@ doc = [ "sphinx-copybutton==0.5.2", "sphinx-design==0.6.1", "sphinx-gallery==0.17.1", + "sphinx-jinja==2.0.2", "sphinx-notfound-page==1.0.4", "sphinx==8.0.2", "sphinxcontrib-websupport==2.0.0", diff --git a/src/ansys/mapdl/core/mapdl_extended.py b/src/ansys/mapdl/core/mapdl_extended.py index c62352388a..ad503396ee 100644 --- a/src/ansys/mapdl/core/mapdl_extended.py +++ b/src/ansys/mapdl/core/mapdl_extended.py @@ -2784,13 +2784,13 @@ def get_value( -------- Retrieve the number of nodes. - >>> value = ansys.get_value('node', '', 'count') + >>> value = mapdl.get_value('node', '', 'count') >>> value 3003 Retrieve the number of nodes using keywords. - >>> value = ansys.get_value(entity='node', item1='count') + >>> value = mapdl.get_value(entity='node', item1='count') >>> value 3003 """