Merge branch 'dev'

.gitignore

@@ -2,6 +2,7 @@ _temp*/
 __pycache__/
 build*/
 .vscode/
+.pytest_cache/
 
 *.pyc
 *.exe
@@ -16,23 +17,23 @@ SCWork
 *.gz
 *.tar
 
-*.u
-*.sn
-*.snm
-*.fi
+tests/*.u
+tests/*.sn
+tests/*.snm
+tests/*.fi
 
-*.ech
-*.v0
-*.v1S
-*.v22
+tests/*.ech
+tests/*.v0
+tests/*.v1S
+tests/*.v22
 
-*.U
-*.E
-*.EM
-*.EN
-*.EMN
-*.S
-*.SM
-*.SN
-*.SMN
-*.ELE
+tests/*.U
+tests/*.E
+tests/*.EM
+tests/*.EN
+tests/*.EMN
+tests/*.S
+tests/*.SM
+tests/*.SN
+tests/*.SMN
+tests/*.ELE

README.md

@@ -5,40 +5,62 @@ Structure Gene (SG) I/O
 Python package interfacing VABS and SwiftComp.
 The package is developed based on [meshio](https://github.com/nschloe/meshio), which is used for converting meshing data.
 
-The package can be used to
-- read/write SG data from/to different formats
-- convert SG/mesh data between different formats
-- read structural property from VABS/SwiftComp output
-- create 1D SG from layup input
-
-Supported data formats:
-- for complete SG data
+**Features**
+
+The package can be used to:
+- Read/write SG data from/to different formats
+- Convert SG/mesh data between different formats
+- Read structural property from VABS/SwiftComp output
+- Create 1D SG from layup input
+
+**Supported Data Formats**
+
+- For complete SG data:
   - VABS, SwiftComp, Abaqus
-- for mesh data only
-  - all formats supported by meshio
+- For mesh data only:
+  - All formats supported by meshio
 
 A structure gene (SG) is defined as the smallest mathematical building block of a structure.[^1]
 A cross-section (CS) is a type of 2D SG.
 
+Online [documentation](https://wenbinyugroup.github.io/sgio/)
 
 ## Installation
 
-Download the package.
+1. [Download](https://github.com/wenbinyugroup/sgio) the package.
+2. Install dependencies:
+    ```shell
+    pip install -r <INSTALL_DIR>/sgio/sgio/requirements.txt
+    ```
+3. Configure environment variables:
+    - Add the package root directory to `PYTHONPATH`.
+    - Add `<INSTALL_DIR>/sgio/bin` to `PATH`.
 
-Install dependencies.
-```shell
-pip install -r <INSTALL_DIR>/sgio/sgio/requirements.txt
-```
+## Usage
 
-Configure environment variables.
-- Add the package root directory to `PYTHONPATH`.
-- Add `<INSTALL_DIR>/sgio/bin` to `PATH`.
+### API
 
+#### Example: Read Beam Properties from VABS Output File
 
-## Usage
+```python
+import sgio
 
-Command line interface
+model = sgio.readOutputModel('my_cross_section.sg.k', 'vabs', 'BM1')
+```
+
+### Command Line Interface
+
+#### Example: Convert Cross-Sectional Data from Abaqus (.inp) to VABS Input
+
+Suppose a cross-section has been built in Abaqus and output to `cross-section.inp`.
+To convert the data to the VABS input (Timoshenko model) `cross-section.sg`:
+```shell
+sgio convert cross-section.inp cross-section.sg -ff abaqus -tf vabs -m bm2
 ```
+
+#### Complete Options
+
+```text
 usage: sgio [-h] {build,b,convert,c} ...
 
 CS/SG I/O functions
@@ -52,10 +74,9 @@ optional arguments:
   -h, --help           show this help message and exit
 ```
 
-### Convert SG data
+##### Convert SG Data
 
-Command line interface
-```
+```text
 usage: sgio convert [-h] [-ff FROM_FORMAT] [-tf TO_FORMAT] [-d SGDIM] [-m MODEL] [-mo] from to
 
 positional arguments:
@@ -75,19 +96,12 @@ optional arguments:
   -mo, --mesh-only      Mesh only conversion
 ```
 
-#### Example: Convert cross-sectional data from Abaqus (.inp) to VABS input
-
-Suppose a cross-section has been built in Abaqus and output to `cross-section.inp`.
-To convert the data to the VABS input (Timoshenko model) `cross-section.sg`:
-```
-sgio convert cross-section.inp cross-section.sg -ff abaqus -tf vabs -m bm2
-```
-
 Check out the example `examples/convert_cs_from_abaqus_to_vabs` for more details.
 
-
 ## License
 
+<!-- This project is licensed under the MIT License.
+See the [LICENSE](LICENSE) file for details. -->
 
 ## Reference
 

docs/requirements.txt

@@ -6,6 +6,7 @@ sphinx-sitemap
 sphinx-design
 sphinx-gallery
 pydata-sphinx-theme
+sphinx-immaterial
 sphinx-prompt
 sphinx-copybutton
 myst-parser

docs/source/conf.py

@@ -40,6 +40,7 @@
     'sphinx.ext.napoleon',
     'myst_parser',
     "sphinx.ext.githubpages",
+    'sphinx_immaterial',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -58,17 +59,23 @@
 # a list of builtin themes.
 #
 # html_theme = 'sphinx_book_theme'
-html_theme = 'pydata_sphinx_theme'
+# html_theme = 'pydata_sphinx_theme'
+html_theme = 'sphinx_immaterial'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
 html_theme_options = {
-    'logo': {
-        'text': 'sgio',
+    'site_url': 'https://wenbinyugroup.github.io/sgio/',
+    'repo_url': 'https://github.com/wenbinyugroup/sgio',
+    'palette': {
+        'primary': 'red'
     },
+    # 'logo': {
+    #     'text': 'sgio',
+    # },
     'show_nav_level': 2,
     # "path_to_docs": "doc/source",
     # 'use_edit_page_button': True,

docs/source/guide/convert.rst

@@ -2,21 +2,44 @@ Convert Structure Gene Data
 =============================
 
 One of the main capabilities of sgio is to convert SG data between different formats.
+This can be done using the :func:`sgio.convert` function or the ``sgio convert`` command.
 
 
-Use
------
 
-..  code-block::
+Convert VABS Cross-sectional Data to Gmsh for Visualization
+------------------------------------------------------------
 
-    import sgio
-    sg = sgio.read('mysg.sg', '')
+It is frequently needed to visualize a cross-section when only the VABS input file is available.
+This can be done either through the package API or the command line interface (CLI).
 
+API
+^^^^
 
+An example is provided in ``examples/convert_mesh_data_vabs2gmsh.py``.
+This example converts a VABS file of a box cross-sectional (``examples/files/cs_box_t_vabs41.sg``) to a Gmsh file (``examples/files/cs_box_t_vabs41.msh``) for visualization.
 
+..  literalinclude:: ../../../examples/convert_mesh_data_vabs2gmsh.py
+    :language: python
 
-.. ..  code-block::
 
-..     sgio convert mysg.sg -format_in swiftcomp -format_out gmsh22
+CLI
+^^^^
 
+..  code-block:: shell
 
+    cd sgio/examples/files
+    sgio convert -ff vabs -tf gmsh -m BM2 --mesh-only cs_box_t_vabs41.sg cs_box_t_vabs41.msh
+
+
+After the conversion, users can open the file in Gmsh to see the cross-section.
+
+..  figure:: ../../../examples/files/cs_box_t_vabs41.msh.png
+    :alt: Visualization of the box cross-section in Gmsh.
+    :align: center
+
+    Visualization of the box cross-section in Gmsh.
+
+..  note::
+
+    Gmsh is not included in the package.
+    Users need to install it separately.

docs/source/guide/index.rst

@@ -1,3 +1,5 @@
+.. _guide:
+
 Guide
 =====
 
@@ -6,8 +8,11 @@ Guide
     :maxdepth: 2
     :caption: Contents
 
-    io
     sg
+    io
+    convert
+    io_model
+    io_state
     model/index
 
 ..    guide/convert