Merge pull request #37 from symbiotic-engineering/becca-joss-cleanup-readme

Becca joss cleanup readme

Author: HopeBestWorld

.dvc/.gitignore

@@ -0,0 +1,3 @@
+/config.local
+/tmp
+/cache

.dvc/config

@@ -0,0 +1,5 @@
+[core]
+    remote = calkit
+['remote "calkit"']
+    url = https://api.calkit.io/projects/symbiotic-engineering/openflash/dvc
+    auth = custom

.dvcignore

@@ -0,0 +1,3 @@
+# Add patterns of files dvc should ignore, which could improve
+# the performance. Learn more at
+# https://dvc.org/doc/user-guide/dvcignore

.github/workflows/.secrets

@@ -0,0 +1,74 @@
+name: Publish Python Package
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'  # Trigger on version tags like v1.0
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/open-flash/
+    permissions:
+      id-token: write
+    steps:
+        - name: Checkout code
+          uses: actions/checkout@v4
+          with:
+            fetch-depth: 0
+
+        - name: Set up Python
+          uses: actions/setup-python@v5
+          with:
+            python-version: '3.x' # Specify your Python version
+
+        - name: Install build tools
+          run: pip install build twine
+
+        - name: Build distribution packages
+          run: python -m build
+
+        - name: Publish package to PyPI
+          uses: pypa/gh-action-pypi-publish@release/v1
+          with:
+            password: ${{ secrets.PYPI_API_TOKEN }}
+
+        - name: Setup Miniconda
+          uses: conda-incubator/setup-miniconda@v3
+          with:
+            python-version: 3.11
+            environment-file: path/to/conda/env.yaml    # Replace with the path to your conda environment
+            auto-update-conda: false
+            auto-activate-base: false
+            show-channel-urls: true
+
+        - name: Build and upload conda packages
+          uses: uibcdf/action-build-and-upload-conda-packages@v1.4.0
+          id: conda-build-and-upload
+          with:
+            python-version: 3.11
+            meta_yaml_dir: conda-recipe 
+            user: sea-lab
+            token: ${{ secrets.ANACONDA_TOKEN }}
+
+        - name: Re-format output paths
+          id: reformat-paths
+          # Needed to have the correct newline-separated files format for the following release step
+          run: |
+            paths=$(tr ' ' '\n' <<< "${{steps.conda-build-and-upload.outputs.paths}}")
+            echo "newline-separated-paths=$paths" >> $GITHUB_OUTPUT
+
+        - name: Create GitHub release
+          uses: softprops/action-gh-release@v2
+          with:
+            tag_name: ${{ github.ref_name }}
+            name: ${{ github.ref_name }} # Replace with the name for your release
+            generate_release_notes: true
+            fail_on_unmatched_files: true
+            files: ${{steps.reformat-paths.outputs.newline-separated-paths}}

.github/workflows/publish-package.yml

@@ -3,40 +3,55 @@ Open-source Flexible Library for Analytical and Semi-analytical Hydrodynamics
 
 ## About The OpenFLASH Project
 
-The OpenFLASH project is a Python package designed for solving boundary value problems using eigenfunction expansion methods. It provides a modular framework for defining complex geometries, setting up multi-domain problems, performing numerical computations, and analyzing results, particularly in fields like fluid dynamics.
+The OpenFLASH project is a Python package designed for solving hydrodynamic boundary value problems using eigenfunction expansion methods. It provides a modular framework for defining complex geometries, setting up multi-domain problems, performing numerical computations, and analyzing results, particularly for linear potential flow hydrodynamics. It can be significantly faster than Boundary Element Method calculations although is restricted to certain geometries (currently axisymmetric compound cylinders).  
 
-When referencing this work, please reference our `docs/citations.rst`
-
-**License:**
+When referencing this work, please reference our `citation.cff`.
 
 This project is licensed under the MIT License. See the `LICENSE` file for details.
 
-**How to Run the Python Code:**
+## Installation
+Three common installation options are shown below. For more details, see the [installation](https://symbiotic-engineering.github.io/OpenFLASH/installation.html) section of the docs.
 
-1.  **Install the package:**
-    ```bash
-    pip install git+[https://github.com/symbiotic-engineering/semi-analytical-hydro.git](https://github.com/symbiotic-engineering/semi-analytical-hydro.git)
-    ```
-2.  **Install dependencies:** Navigate to the project directory (if you cloned it) and run:
-    ```bash
-    pip install -r requirements.txt
-    ```
-3.  **Explore the `docs/` and `package/test` directory:** These directories contain scripts and notebooks demonstrating how to use the OpenFLASH framework for different problems. Run these examples to understand the workflow.
-4.  **Refer to the documentation in the `docs/` directory:** The documentation provides detailed information on the different modules and classes within the `open-flash` package.
+Option 1: via pypi (recommended for users who manage environments with venv or similar)
 
-## MATLAB
-We also have a MATLAB code version, although the Python version is intended as primary for future development. MATLAB only supports bodies consisting of 2 concentric cylinders, rather than the arbitrary N concentric cylinders in the Python package.
+```bash
+pip install open-flash
+```
 
-See `matlab/src/run_MEEM.m` for the symbolic and numeric code, see `matlab/test/` for some scripts to get results, and `matlab/dev` for various matlab experiments.
+Option 2: via conda (recommended for users who manage environments with conda)
+
+```bash
+conda create -n openflash-env hopeonthestack::open-flash
+conda activate openflash-env
+```
+
+Option 3: via git (recommended for developers)
 
+Note - if you are a developer outside of the SEA Lab, please create a fork and clone your fork.
+1.  **Clone the repository:**
+```bash
+git clone https://github.com/symbiotic-engineering/OpenFLASH.git
+cd OpenFLASH
+```
+2.  **Install the package:**
+```bash
+pip install -e .
+```
+3.  **Install dependencies:**
+```bash
+pip install -r requirements.txt
+```
 
-## References
+## Usage
 
-The following publications are relevant to this package:
+Please see our [documentation](https://symbiotic-engineering.github.io/OpenFLASH/) and [tutorial notebook](https://symbiotic-engineering.github.io/OpenFLASH/tutorial_walk.html). The documentation provides detailed instructions and API reference for the different modules and classes within the `openflash` package.
 
-1. I. K. Chatjigeorgiou, *Analytical Methods in Marine Hydrodynamics*. Cambridge: Cambridge University Press, 2018. doi: 10.1017/9781316838983.
-2. F. P. Chau and R. W. Yeung, “Inertia and Damping of Heaving Compound Cylinders,” presented at the 25th International Workshop on Water Waves and Floating Bodies, Harbin, China, Jan. 2010. Accessed: Sep. 27, 2023. [Online]. Available: https://www.academia.edu/73219479/Inertia_and_Damping_of_Heaving_Compound_Cylinders_Fun
-3. F. P. Chau and R. W. Yeung, “Inertia, Damping, and Wave Excitation of Heaving Coaxial Cylinders,” presented at the ASME 2012 31st International Conference on Ocean, Offshore and Arctic Engineering, American Society of Mechanical Engineers Digital Collection, Aug. 2013, pp. 803–813. doi: 10.1115/OMAE2012-83987.
-4. R. W. Yeung, “Added mass and damping of a vertical cylinder in finite-depth waters,” *Appl. Ocean Res.*, vol. 3, no. 3, pp. 119–133, Jul. 1981, doi: 10.1016/0141-1187(81)90101-2.
-5. D. Son, V. Belissen, and R. W. Yeung, “Performance validation and optimization of a dual coaxial-cylinder ocean-wave energy extractor,” *Renew. Energy*, vol. 92, pp. 192–201, Jul. 2016, doi: 10.1016/j.renene.2016.01.032.
-6. K. Kokkinowrachos, S. Mavrakos, and S. Asorakos, “Behaviour of vertical bodies of revolution in waves,” *Ocean Eng.*, vol. 13, no. 6, pp. 505–538, Jan. 1986, doi: 10.1016/0029-8018(86)90037-5.
+If you prefer not to utilize the package programatically, the model can also be run with an [interactive web app](http://symbiotic-engineering.github.io/OpenFLASH/app_streamlit.html) (the site may take several seconds to load).
+
+## Theory
+Please see our [equations documentation](https://symbiotic-engineering.github.io/OpenFLASH/multi_equations.html) and [references](https://symbiotic-engineering.github.io/OpenFLASH/citations.html) for mathematical background and derivations as well as validation information.
+
+## MATLAB
+We also have a MATLAB code version, although the Python package is intended as primary for future development. MATLAB only supports bodies consisting of 2 concentric cylinders, rather than the arbitrary N concentric cylinders in the Python package.
+
+See `matlab/src/run_MEEM.m` for the symbolic and numeric code, see `matlab/test/` for some scripts to get results, and `matlab/dev` for various matlab experiments.

README.md

@@ -0,0 +1,5 @@
+owner: symbiotic-engineering
+name: openflash
+title: OpenFLASH
+description:
+git_repo_url: https://github.com/symbiotic-engineering/OpenFLASH

calkit.yaml

@@ -1,6 +1,6 @@
 package:
   name: open-flash
-  version: "0.2.2"
+  version: {{ GIT_DESCRIBE_TAG }}
 
 source:
   path: ..
@@ -27,6 +27,7 @@ requirements:
     - h5netcdf
     - xarray
     - streamlit
+    - ipykernel
 
 about:
   home: https://github.com/symbiotic-engineering/semi-analytical-hydro

conda-recipe/meta.yaml

@@ -4,10 +4,10 @@
 App Module
 ============
 
-.. automodule:: app
-   :members:
-   :undoc-members:
-   :show-inheritance:
+.. .. automodule:: app
+..    :members:
+..    :undoc-members:
+..    :show-inheritance:
 
 .. _app-overview:
 
@@ -22,11 +22,13 @@ Running the App
 There are two ways to run the Streamlit application:
 
 **Option 1: Use the Web-Based App (Recommended)**
+
 The app is deployed and can be run directly in your web browser, with no installation required. This is the easiest way to get started.
 
 * **Interactive Streamlit App:** `Launch App <app_streamlit.html>`_
 
 **Option 2: Run the App Locally**
+
 Ensure that you have Streamlit and the `openflash` package installed.
 
 .. code-block:: bash