Update 1_requirements.rst

Author: hweifluids

source/1_requirements.rst

@@ -3,69 +3,203 @@
 Requirements and Quickstart
 ===========================
 
-Hardware and Hardware Requirements
-----------------------------------
+Hardware and Platform
+---------------------
+
+This page summarizes the supported mainline workflow of ``Streamcenter+``.
+The current mainline is no longer the old Python package set. It is centered on a
+native CUDA FTLE solver together with a native Qt/VTK desktop GUI.
+The archived Python implementation is still preserved under ``legacy/`` in the code
+repository for reference and migration, but it is no longer the primary workflow
+described in this documentation.
+
+The minimum practical requirements are listed as follows:
+
+* At least 4 GB of system memory and about 10 GB of free disk space.
+* A 64-bit Windows or Linux environment. The shipped install scripts currently target
+  Windows and Debian/Ubuntu-style Linux systems with ``apt``.
+* An NVIDIA GPU together with a locally installed CUDA Toolkit for the mainline solver.
+
+The solver configures ``CMAKE_CUDA_ARCHITECTURES=native`` by default, so the build
+machine is expected to have a visible local NVIDIA CUDA environment.
+
+GPU memory capacity is usually the main bottleneck for large FTLE jobs.
+A practical rule of thumb is to keep
+:math:`N_x \times N_y \times N_z \times N_t`
+below roughly 200,000,000 Lagrangian particles per GiB of VRAM for the default
+double-sided still workflow, and lower than that for higher-order settings.
+
+
+Mainline Environment
+--------------------
+
+The native solver and the native GUI do not require Python or ``pip`` for their
+standard build-and-run path.
+Instead, the repository provides platform-specific installation scripts that prepare
+the CMake/CUDA/Qt/VTK toolchain directly.
+
+On Windows, ``install.cmd`` and ``install.ps1`` provision the following mainline
+dependencies:
+
+* ``Git``
+* ``CMake``
+* ``Ninja``
+* ``Visual Studio Build Tools 2022``
+* ``NVIDIA CUDA Toolkit``
+* ``FFmpeg`` for MP4 export
+* a local ``vcpkg`` tree that installs ``Qt6`` and ``VTK``
+
+The default Windows dependency cache uses the ``x64-windows-release`` triplet, which
+avoids building both Debug and Release variants of ``Qt`` and ``VTK`` during the first
+install.
+If Debug libraries are also needed, rerun the installer with
+``-VcpkgTriplet x64-windows``.
+
+On Debian/Ubuntu-style Linux systems, ``install.sh`` installs the following packages:
+
+* ``build-essential``
+* ``cmake``
+* ``ninja-build``
+* ``git``
+* ``pkg-config``
+* ``qt6-base-dev``
+* ``qt6-base-dev-tools``
+* ``qt6-tools-dev``
+* ``libvtk9-dev``
+* ``libvtk9-qt-dev``
+* ``ffmpeg`` by default
+* ``nvidia-cuda-toolkit`` by default
+
+When ``nvcc`` is found on Linux, the installer also records
+``STREAMCENTERPLUS_CUDA_ROOT`` under
+``~/.config/streamcenterplus/env.sh`` for later builds.
+
+
+Environment Overrides
+---------------------
+
+If your toolchain is installed outside the default locations, the build scripts
+understand the following environment variables:
+
+* ``STREAMCENTERPLUS_VCPKG_ROOT``
+* ``STREAMCENTERPLUS_VCPKG_TRIPLET``
+* ``STREAMCENTERPLUS_QT_ROOT``
+* ``STREAMCENTERPLUS_VTK_ROOT``
+* ``STREAMCENTERPLUS_CUDA_ROOT``
+
+For migration convenience, the renamed build scripts still accept the legacy
+``PY3DFTLE_*`` environment variables as fallback inputs.
+
+
+Add-on Tools
+------------
+
+* **ParaView**
+  ParaView remains a convenient external viewer for inspecting ``.vts`` and ``.pvd``
+  outputs generated by the native solver.
+  It is optional, because the native GUI already provides an embedded VTK viewer, but
+  it is still useful for post-processing and larger inspection tasks.
+
+* **FFmpeg**
+  ``ffmpeg`` is required if you want to export MP4 animations from the GUI.
+  It is optional for plain solving, parameter editing, and static visualization.
+
+* **PowerShell on Linux**
+  ``pwsh`` is optional on Linux.
+  It is only needed if you want to use the same ``run.ps1`` wrappers shipped for the
+  Windows workflow. Otherwise the built GUI or solver binaries can be launched directly
+  from their build folders.
 
-The minimiums are listed as follows:
 
-* Minimium 4GB RAM and 10GB free disk.
-* Not sensitive to platform. Windows 11 and Ubuntu 22.04 are fully tested.
+Quickstart
+----------
 
-GPU acceleration is suggested for large dataset computation. Therefore, the requirements for GPU acceleration is listed as follows:
+The steps below follow the current native mainline repository layout.
+They use the top-level install and build entry points and then launch the GUI or solver
+through the maintained wrapper scripts.
 
-* NVIDIA GPUs, with a minimum `compute capability <https://developer.nvidia.com/cuda-gpus>`__ of 5.0, i.e., later than GTX 750.
-* It is suggested that, make ``Nx`` × ``Ny`` × ``Nz`` × ``Nt`` less than 200,000,000 Lagrangian particles on each Gigabyte of GPU memory for double-side computation under default numerical methods for one still. Generally half it under high-order computations. For example, you can execute on a 600×300×300 mesh for c.a. 80 time steps for a still on a welcomed RTX 2080ti 22G customized GPU, with the price of ~$400.
-* The general short for GPU is VRAM, not computational power, hence old-but-large GPUs are great for use. Newers can be faster, but smallers can run nothing.
-* The GPU requirements for dynamic LCS are undergoing experiments by the author.
+Windows
+~~~~~~~
 
+Install the required toolchain and cache the GUI dependencies:
 
-Basic Environment
------------------
+.. code-block:: powershell
 
-This page summarizes the system requirements and dependencies of ``Streamcenter+``.
+   .\install.cmd
 
-Firstly, the following packages are supposed to be installed on your computer manually in advance.
+If you need advanced flags, call the PowerShell entry directly instead:
 
-1. `Python <https://www.python.org/>`__ version 3.13. Later version than 3.8 till 3.13 should work properly, but was not fully tested. The official download could be found at `here <https://www.python.org/downloads/release/python-3130/?featured_on=pythonbytes>`__. Please select Python installer according to your system framework.
-2. `CUDA Toolkit <https://developer.nvidia.com/cuda-toolkit>`__ version 12.9 (`Download <https://developer.nvidia.com/cuda-toolkit-archive>`__). All versions crossing 12.x.x should theoretically work, but only 12.9 was fully tested. Ealier versions could work as well, but it requires a different version of `cupy`, and could cause unexpected performance decay and errors. See `cupy` documentation for more information.
-3. `pip <https://pypi.org/project/pip/>`__ newest version, which is used for installing further dependencies. It can be installed by:
+.. code-block:: powershell
 
-.. code-block::
+   .\install.ps1
 
-  python -m ensurepip --upgrade
+If Debug variants of ``Qt`` and ``VTK`` are needed as well, use:
 
-Generally, the following dependencies can be installed via ``pip``, the Python package manager.
+.. code-block:: powershell
 
-1. `numpy <https://numpy.org>`__ version 1.21 or later  
-2. `matplotlib <https://matplotlib.org>`__ version 3.4 or later  
-3. `pyvista <https://pyvista.org>`__ version 0.32 or later  
-4. `scipy <https://scipy.org>`__ version 1.7 or later  
-5. `pyevtk <https://github.com/paulo-herrera/PyEVTK>`__ version 1.4 or later  
-6. `numba <https://numba.pydata.org>`__ version 0.54 or later  
-7. `tqdm <https://tqdm.github.io>`__ version 4.62 or later  
-8. `cupy-cuda12x <https://pypi.org/project/cupy-cuda12x/>`__ version 13.4.1 or later
-9. `pyvistaqt <https://github.com/pyvista/pyvistaqt>`__ version 0.11.2 or later  
-10. `PyQt5 <https://riverbankcomputing.com/software/pyqt/intro>`__ version 5.15.11 or later  
+   .\install.ps1 -VcpkgTriplet x64-windows
 
-You can install them after installing ``pip`` by:
+Build both the native CUDA solver and the native GUI:
 
-.. code-block::
+.. code-block:: powershell
 
-  pip install -r ./requirements.txt
+   .\build.ps1 -NonInteractive
 
-When it does not work, consider if your current dir is incorrect. It should be run from the project root of ``Streamcenter+`` when undergoing configurations and under :ref:`command-line <command>` mode. Please feel free about such thing under GUI mode.
+Run the GUI:
 
+.. code-block:: powershell
 
-Add-on Libs (Optional)
-----------------------
+   .\GUI\V2603\run.ps1
 
-**1. ParaView** is a powerful beloved open-source visualization platform based on *vtk* that can be used to visualize the results of 3D FTLE computations. We also integrated the ParaView entrance into our GUI, so you can directly open ParaView from it.
-The ParaView installation-free package (v6.0) can be downloaded from `official <https://www.paraview.org/paraview-downloads/download.php?submit=Download&version=v6.0&type=binary&os=Windows&downloadFile=ParaView-6.0.0-RC1-MPI-Windows-Python3.12-msvc2017-AMD64.zip>`__. 
-For already-installed ParaView, set environment variable ``PARAVIEW_PATH`` pointing to the root dir of ParaView to enable integration from GUI of ``Streamcenter+``.
+Optionally run the bundled solver smoke test directly:
 
-Quickstart
------------------
+.. code-block:: powershell
+
+   .\CUDAsolvers\V2603\run.ps1 --par .\CUDAsolvers\V2603\tools\regression_small.par
+
+
+Linux (Debian/Ubuntu)
+~~~~~~~~~~~~~~~~~~~~~
+
+Install the build dependencies:
+
+.. code-block:: bash
+
+   bash ./install.sh
+
+Build both the solver and the GUI:
+
+.. code-block:: bash
+
+   bash ./build.sh --all
+
+Run the GUI.
+If PowerShell is available, the wrapper is:
+
+.. code-block:: bash
+
+   pwsh ./GUI/V2603/run.ps1
+
+Otherwise, launch the generated GUI binary directly from ``GUI/V2603/build/``.
+
+Optionally run the bundled solver smoke test.
+With PowerShell:
+
+.. code-block:: bash
+
+   pwsh ./CUDAsolvers/V2603/run.ps1 --par ./CUDAsolvers/V2603/tools/regression_small.par
+
+Without PowerShell, launch the built solver binary directly from
+``CUDAsolvers/V2603/out/build/``.
+
+
+Notes for Real Cases
+--------------------
+
+The mainline GUI always launches the native CUDA solver. There is no longer a
+Python/native backend selector in the supported workflow.
 
-After configurations of environment, you can run a very first demo to test the environment as well as the code, and learn how to use this toolbox for your own data towards new insights.
-An computation example coming with a set of our in-house downscaled Direct Navier-Stokes Simulation (DNS) data is provided, including :math:
-The dataset can be downloaded from `here <https://noting.noting>`__, and the case descriptions can be referred to paper ``I.P.``.
+The parameter format remains ``.par``-based.
+When preparing your own cases, update entries such as ``vtk_folder`` and
+``output_dir`` so that they point to locations that actually exist on your machine.
+The native parser reads those paths literally.