Merge pull request #1 from Renumics/feature/new_readme

Feature/new readme

.github/actions/ci-setup/action.yml

@@ -13,7 +13,7 @@ runs:
   using: composite
   steps:
      - name: Set up Python ${{ inputs.python-version }}
-       uses: actions/setup-python@v3
+       uses: actions/setup-python@v4
        with:
          python-version: ${{ inputs.python-version }}
      - name: Install Poetry
@@ -26,7 +26,9 @@ runs:
        if: runner.os == 'Windows'
        run: echo "C:/Users/runneradmin/.local/bin" >> $GITHUB_PATH
        shell: bash
-
+     - name: add dynamic versioning
+       run: poetry self add "poetry-dynamic-versioning[plugin]"
+       shell: bash
      - name: Cache Packages
        id: poetry-cache
        uses: actions/cache@v3
@@ -39,6 +41,3 @@ runs:
        if: steps.poetry-cache.outputs.cache-hit != 'true'
        run: poetry install
        shell: bash
-     - name: add dynamic versioning
-       run: poetry self add "poetry-dynamic-versioning[plugin]"
-       shell: bash

.github/workflows/workflow.yml

@@ -79,20 +79,6 @@ jobs:
       run: |
         poetry run pip-audit --ignore-vuln GHSA-w596-4wvx-j9j6
 
-  docs:
-    needs: prepare-linux
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v3
-    - name: Setup CI
-      uses: './.github/actions/ci-setup'
-      with:
-        os: "ubuntu-latest"
-        python-version: "3.9"
-    - name: build docs
-      run: |
-        poetry run sphinx-build docs/source build/documentation/ -W -b html
-
   doctest:
     needs: [prepare-linux, prepare-win]
     strategy:
@@ -129,6 +115,25 @@ jobs:
       run: |
         poetry run pytest tests
 
+  docs:
+    needs: prepare-linux
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Setup CI
+      uses: './.github/actions/ci-setup'
+      with:
+        os: "ubuntu-latest"
+        python-version: "3.9"
+    - name: build docs
+      run: |
+        poetry run sphinx-build docs/source build/documentation/ -W -b html
+    - name: Store docs
+      uses: actions/upload-artifact@v3
+      with:
+        name: docs
+        path: build/documentation/
+
   build:
     needs: prepare-linux
     runs-on: ubuntu-latest
@@ -146,11 +151,12 @@ jobs:
       uses: actions/upload-artifact@v3
       with:
         name: dist
-        path: dist
+        path: dist/
 
 
   release-docs:
-    needs: prepare-linux
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [ check-format, build, unit-tests, doctest, docs, audit, pylint ]
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
@@ -159,9 +165,11 @@ jobs:
       with:
         os: "ubuntu-latest"
         python-version: "3.9"
-    - name: build docs
-      run: |
-        poetry run sphinx-build docs/source build/documentation/ -W -b html
+    - name: Download docs
+      uses: actions/download-artifact@v3
+      with:
+        name: docs
+        path: build/documentation/
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3
       with:
@@ -179,17 +187,14 @@ jobs:
       with:
         os: "ubuntu-latest"
         python-version: "3.9"
-    - name: build wheels
-      run: |
-        poetry build -f wheel -vvv && poetry run check-wheel-contents dist/
     - name: Download wheels
       uses: actions/download-artifact@v3
       with:
         name: dist
+        path: dist/
     - name: Publish package to TestPyPI
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
-        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
-        repository_url: https://test.pypi.org/legacy/
+        password: ${{ secrets.PYPI_API_TOKEN }}
 
 

README.md

@@ -1,12 +1,71 @@
 Mesh2Vec
 ========
 
-Installation
--------------
+Quickstart
+-----------
+
+<h1 align="center">mesh2vec</h1>
+<p align="center">Turn CAE Mesh Data Into Vectors</p>
+
+<p align="center">
+	<a href="https://github.com/renumics/mesh2vec"><img src="https://img.shields.io/github/license/renumics/mesh2vec" height="20"/></a>    
+ 	<a href="https://github.com/renumics/mesh2vec"><img src="https://img.shields.io/pypi/pyversions/renumics-mesh2vec" height="20"/></a>   
+ 	<a href="https://github.com/renumics/mesh2vec"><img src="https://img.shields.io/pypi/wheel/renumics-mesh2vec" height="20"/></a>   
+</p>
+<h3 align="center">
+   <a href="https://renumics.github.io/mesh2vec/"><b>Latest Documentation</b></a>
+</h3>
+
+## 🚀 Introduction
+Mesh2vec is a tool that facilitates the import of Computer-Aided Engineering (CAE) mesh data from [LS-DYNA](https://www.ansys.com/de-de/products/structures/ansys-ls-dyna) .
+It utilizes various metrics of elements and their surrounding neighborhood to aggregate feature vectors for each element.
+
+## ⏱️ Quickstart
+
+
+### Installation
 1. Create and activate a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/).
 2. Use the following command to install mesh2vec into your environment:
-``pip install mesh2vec``
 
-Documentation
----------------
-[Documentation](https://readthedocs.org/...)
+```bash
+pip install mesh2vec
+```
+3. Please make sure you have an environment variable ANSA_EXECUTABLE set pointing to your ANSA executable to use ANSA depended features like shell and feature import.
+
+### Load Mesh
+```python
+
+from pathlib import Path
+from mesh2vec.mesh2vec_cae import Mesh2VecCae
+m2v = Mesh2VecCae.from_ansa_shell(4,
+    Path("data/hat/Hatprofile.k"),
+    json_mesh_file=Path("data/hat/cached_hat_key.json"))
+```
+
+### Add element features
+```python
+m2v.add_features_from_ansa(
+    ["aspect", "warpage"],
+    Path("data/hat/Hatprofile.k"),
+    json_mesh_file=Path("data/hat/cached_hat_key.json"))
+```
+
+### Aggregate
+```python
+import numpy as np
+m2v.aggregate("aspect", [0,2,3], np.nanmean)
+```
+
+### Extract Feature Vectors
+```python
+m2v.to_dataframe()
+```
+![data frame with feature vectors](docs/source/_static/m2v.to_df.png)
+
+### Optional: Visualize a single aggregated feature on mesh
+```python
+m2v.get_visualization_plotly("aspect-nanmean-2")
+```
+![3d mesh plot of agggredated](docs/source/_static/hat_aspect_3_plot.png)
+
+

docs/examples/quickstart.py

@@ -0,0 +1,45 @@
+"""
+Quick Start Example
+====================
+"""
+# pylint: disable=pointless-statement
+from pathlib import Path
+import numpy as np
+from mesh2vec.mesh2vec_cae import Mesh2VecCae
+
+
+# %%
+# Load Shell from ANSA
+# -----------------------------------------------------
+m2v = Mesh2VecCae.from_ansa_shell(
+    4,
+    Path("../../data/hat/Hatprofile.k"),
+    json_mesh_file=Path("../../data/hat/cached_hat_key.json"),
+)
+
+# %%
+#  Add element features
+# ------------------------
+m2v.add_features_from_ansa(
+    ["aspect", "warpage"],
+    Path("../../data/hat/Hatprofile.k"),
+    json_mesh_file=Path("../../data/hat/cached_hat_key.json"),
+)
+
+
+# %%
+# Aggregate
+# ---------------------------
+m2v.aggregate("aspect", [0, 2, 3], np.nanmean)
+
+
+# %%
+# Extract Feature Vector
+# -----------------------
+m2v.to_dataframe()
+
+
+# %%
+# Visualize a single feature
+# ---------------------------
+m2v.get_visualization_plotly("aspect-nanmean-2")

docs/source/conf.py

@@ -7,7 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "Mesh2vec"
-copyright = "2022, Renumics GmbH"
+copyright = "2023, Renumics GmbH"
 author = "Renumics GmbH"
 from sphinx_gallery.sorting import FileNameSortKey
 

docs/source/index.rst

@@ -6,7 +6,7 @@
 Welcome to mesh2vec's documentation!
 =====================================
 
-Check out the examples to make your first steps.
+Check out the `Quickstart <https://github.com/Renumics/mesh2vec>`_ to make your first steps.
 
 Please make sure you have an environment variable `ANSA_EXECUTABLE` set pointing to your ANSA executable
 to use ANSA depended features like shell and feature import.