Skip to content

Instantly share code, notes, and snippets.

@Foadsf

Foadsf/openfoam-termux-installation-guide.md

Last active May 22, 2025 21:40
Show Gist options
  • Save Foadsf/5d268ed3aa26798dbcf819c8bcf90743 to your computer and use it in GitHub Desktop.
Save Foadsf/5d268ed3aa26798dbcf819c8bcf90743 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. Foadsf revised this gist May 22, 2025. 1 changed file with 245 additions and 31 deletions.
    276 changes: 245 additions & 31 deletions openfoam-termux-installation-guide.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,20 +1,29 @@
    # Installing OpenFOAM on Termux: Experience, Issues, and Lessons Learned

    This document captures the experience of installing and running OpenFOAM on Termux, along with the challenges encountered and the lessons learned along the way.
    This document captures the complete experience of installing, testing, and running OpenFOAM on Termux, along with the challenges encountered and the lessons learned along the way.

    ## Table of Contents
    - [Introduction](#introduction)
    - [Installation Steps](#installation-steps)
    - [Environment Setup and Verification](#environment-setup-and-verification)
    - [Installation Testing](#installation-testing)
    - [Encountered Issues and Fixes](#encountered-issues-and-fixes)
    - [Missing Library: `libandroid-execinfo`](#missing-library-libandroid-execinfo)
    - [Environment Setup and Sourcing](#environment-setup-and-sourcing)
    - [Case File Errors: Missing or Invalid `controlDict`](#case-file-errors-missing-or-invalid-controldict)
    - [Tutorial Directory Navigation](#tutorial-directory-navigation)
    - [Lessons Learned](#lessons-learned)
    - [Performance Considerations](#performance-considerations)
    - [Next Steps and Additional Resources](#next-steps-and-additional-resources)

    ## Introduction

    OpenFOAM is a popular open-source CFD toolbox written in C++. Running it on Termux offers an interesting opportunity to run complex simulations on mobile devices. This guide documents the complete process of searching for, installing, and troubleshooting OpenFOAM on Termux.
    OpenFOAM is a popular open-source CFD toolbox written in C++. Running it on Termux offers an interesting opportunity to run complex simulations on mobile devices. This guide documents the complete process of searching for, installing, testing, and troubleshooting OpenFOAM on Termux.

    **Confirmed Working Configuration:**
    - OpenFOAM Version: v2406
    - Termux Platform: Android ARM64
    - Architecture: linuxARM64ClangDPInt32Opt

    ## Installation Steps

    @@ -27,21 +36,130 @@ OpenFOAM is a popular open-source CFD toolbox written in C++. Running it on Term
    ```bash
    apt install openfoam
    ```
    2. **Set Up the Environment:**
    - Source the OpenFOAM environment file:
    ```bash
    source /data/data/com.termux/files/usr/opt/OpenFOAM-v2406/etc/bashrc
    ```
    - Verify that key environment variables are set:

    2. **Install Required Dependencies:**
    - Install the essential library for proper execution:
    ```bash
    echo $WM_PROJECT_DIR # Output should be /data/data/com.termux/files/usr/opt/OpenFOAM-v2406
    echo $WM_PROJECT_VERSION # Output should reflect the version, e.g., v2406
    apt install libandroid-execinfo
    ```
    3. **Testing Installation:**
    - Run a simple command to verify the installation:

    3. **Verify Installation Location:**
    - Check that OpenFOAM was installed correctly:
    ```bash
    icoFoam -help
    ls -la /data/data/com.termux/files/usr/opt/
    ```
    - You should see the `OpenFOAM-v2406` directory.

    ## Environment Setup and Verification

    ### Initial Environment Configuration

    1. **Source the OpenFOAM Environment:**
    ```bash
    source /data/data/com.termux/files/usr/opt/OpenFOAM-v2406/etc/bashrc
    ```

    2. **Verify Environment Variables:**
    ```bash
    echo "WM_PROJECT_DIR: $WM_PROJECT_DIR"
    echo "WM_PROJECT_VERSION: $WM_PROJECT_VERSION"
    echo "FOAM_TUTORIALS: $FOAM_TUTORIALS"
    echo "FOAM_APPBIN: $FOAM_APPBIN"
    ```

    **Expected Output:**
    ```
    WM_PROJECT_DIR: /data/data/com.termux/files/usr/opt/OpenFOAM-v2406
    WM_PROJECT_VERSION: v2406
    FOAM_TUTORIALS: /data/data/com.termux/files/usr/opt/OpenFOAM-v2406/tutorials
    FOAM_APPBIN: /data/data/com.termux/files/usr/opt/OpenFOAM-v2406/platforms/linuxARM64ClangDPInt32Opt/bin
    ```
    3. **Make Environment Persistent (Optional):**
    ```bash
    echo 'source /data/data/com.termux/files/usr/opt/OpenFOAM-v2406/etc/bashrc' >> ~/.bashrc
    ```

    ### Verify Core Utilities

    ```bash
    # Check utility locations
    which blockMesh
    which icoFoam
    which checkMesh

    # Test utility accessibility
    icoFoam -help | head -5
    blockMesh -help | head -5
    ```

    ## Installation Testing

    ### Basic Functionality Test

    1. **Navigate to Tutorial Case:**
    ```bash
    cd $FOAM_TUTORIALS/incompressible/icoFoam/cavity/cavity
    pwd # Should show the full path to the cavity case
    ```

    2. **Verify Case Structure:**
    ```bash
    ls -la
    # Should show directories: 0, constant, system

    ls -la system/ # Contains controlDict, blockMeshDict, etc.
    ls -la constant/ # Contains transportProperties
    ls -la 0/ # Contains initial conditions (U, p)
    ```

    3. **Clean and Test Mesh Generation:**
    ```bash
    # Clean any previous runs
    foamCleanTutorials .

    # Generate mesh
    blockMesh
    ```

    **Successful Output Should Include:**
    ```
    Creating block mesh from "system/blockMeshDict"
    ...
    Mesh Information
    ----------------
    boundingBox: (0 0 0) (0.1 0.1 0.01)
    nPoints: 882
    nCells: 400
    nFaces: 1640
    ...
    End
    ```

    4. **Verify Mesh Quality:**
    ```bash
    checkMesh
    ```

    5. **Test Solver (Short Run):**
    ```bash
    # Run solver for 30 seconds to test functionality
    timeout 30s icoFoam

    # Check if time directories were created
    ls -la | grep "^d.*[0-9]"
    ```

    ### Success Criteria

    Your OpenFOAM installation is working correctly if:

    ✅ **Environment Setup**: All environment variables are properly set
    ✅ **Utilities Available**: Core utilities (blockMesh, icoFoam) are accessible
    ✅ **Mesh Generation**: blockMesh completes without errors
    ✅ **Mesh Validation**: checkMesh reports no critical errors
    ✅ **Solver Execution**: icoFoam starts and runs without immediate crashes
    ✅ **Result Generation**: Time directories and field files are created

    ## Encountered Issues and Fixes

    @@ -55,19 +173,29 @@ OpenFOAM is a popular open-source CFD toolbox written in C++. Running it on Term
    ```bash
    apt install libandroid-execinfo
    ```
    After installing, verify the library:
    Verify the library installation:
    ```bash
    ls /data/data/com.termux/files/usr/lib | grep libandroid-execinfo
    ldd $(which icoFoam) | grep -i execinfo
    ```

    ### Environment Setup and Sourcing

    - **Issue:**
    Initially, the environment file was not in the expected location. After inspecting the installed files, the correct path was found:
    - `/data/data/com.termux/files/usr/opt/OpenFOAM-v2406/etc/bashrc`
    Environment variables are empty or not set, indicating the OpenFOAM environment hasn't been sourced.

    - **Symptoms:**
    ```bash
    echo $WM_PROJECT_DIR # Returns empty
    echo $WM_PROJECT_VERSION # Returns empty
    ```

    - **Fix:**
    Source the file from the correct path and verify the environment variables.
    Source the environment file and verify:
    ```bash
    source /data/data/com.termux/files/usr/opt/OpenFOAM-v2406/etc/bashrc
    # Re-check environment variables
    ```

    ### Case File Errors: Missing or Invalid `controlDict`

    @@ -76,7 +204,14 @@ OpenFOAM is a popular open-source CFD toolbox written in C++. Running it on Term

    - **Fix Options:**
    1. **Check Folder Structure:**
    Ensure that the case directory (`tutorials/incompressible/icoFoam/cavity`) has a proper structure with subdirectories like `system`, `constant`, and an initial time folder (`0`).
    Ensure you're in the correct case directory. The tutorial structure is:
    ```
    $FOAM_TUTORIALS/incompressible/icoFoam/cavity/
    ├── cavity/ # Actual case directory
    ├── cavityClipped/ # Another case variant
    └── cavityGrade/ # Another case variant
    ```
    Navigate to the specific case: `cd cavity/cavity`
    2. **Restore or Create `controlDict`:**
    If the `system/controlDict` is missing, use a minimal example such as:
    @@ -108,34 +243,113 @@ OpenFOAM is a popular open-source CFD toolbox written in C++. Running it on Term
    timePrecision 6;
    runTimeModifiable true;
    ```
    Save this file in the correct directory and re-run the commands.
    3. **Syntax Corrections:**
    For the syntax error (`Unexpected '}'`), inspect the `controlDict` file (using an editor like `nano`) and remove extraneous braces or misconfigurations.
    For syntax errors, inspect the `controlDict` file and remove extraneous braces or misconfigurations.
    ### Tutorial Directory Navigation
    - **Issue:**
    Confusion about the correct tutorial directory structure and which directory contains the actual case files.
    - **Symptoms:**
    ```bash
    ls -la constant/ # No such file or directory
    ls -la 0/ # No such file or directory
    ```

    - **Fix:**
    Navigate to the correct subdirectory:
    ```bash
    cd $FOAM_TUTORIALS/incompressible/icoFoam/cavity/cavity
    # Note the double "cavity" - first is the tutorial group, second is the specific case
    ```

    ## Lessons Learned

    - **Environment Sourcing is Critical:**
    The OpenFOAM environment must be sourced in every new terminal session. Consider adding the source command to your `.bashrc` for convenience.

    - **Verify File Paths:**
    Confirm the correct paths for environment files immediately after installation. Packages on Termux might follow a different directory structure than traditional Linux installations.

    - **Install Dependencies Promptly:**
    Missing library errors (like that for `libandroid-execinfo`) can block execution. Always ensure dependencies are met before running simulations.

    - **Double-Check Tutorial Materials:**
    Some tutorial cases might be incomplete or require manual adjustments (e.g., creating a missing `controlDict`), so be prepared to modify files or seek updated examples.
    - **Tutorial Directory Structure:**
    OpenFOAM tutorials often have nested directory structures. Always navigate to the actual case directory (the one containing `system/`, `constant/`, and `0/` directories).

    - **Incremental Testing:**
    Run preliminary commands like `icoFoam -help` and `blockMesh` immediately after installation to catch issues early.
    Test each component separately: environment setup → utilities → mesh generation → solver execution. This approach helps isolate issues quickly.

    - **Case Cleaning:**
    Always run `foamCleanTutorials .` before testing to ensure a clean state and avoid conflicts from previous runs.

    ## Performance Considerations

    ### Mobile Device Limitations

    - **Memory Usage:** CFD simulations are memory-intensive. Monitor RAM usage during longer simulations.
    - **Battery Life:** Complex simulations can drain battery quickly. Consider connecting to power for extended runs.
    - **Thermal Management:** Intensive computations may cause device heating. Monitor temperature during long simulations.

    ### Optimization Tips

    ```bash
    # Monitor system resources during simulation
    free -h # Check memory usage
    df -h # Check disk space
    top -p $(pgrep icoFoam) # Monitor process performance
    ```

    ### Case Size Recommendations

    For mobile devices, start with small cases:
    - **Mesh size:** 400-4000 cells for initial testing
    - **Time steps:** Short simulation periods (0.01-0.1 seconds)
    - **Output frequency:** Reduce writeInterval to save storage

    ## Next Steps and Additional Resources

    - **Run a Simulation:**
    With the environment now set up and tutorial cases corrected, try running a full simulation to assess performance and further explore OpenFOAM capabilities.
    ### Immediate Next Steps

    1. **Run Complete Simulations:**
    ```bash
    cd $FOAM_TUTORIALS/incompressible/icoFoam/cavity/cavity
    foamCleanTutorials .
    blockMesh
    icoFoam # Let it run to completion
    ```

    2. **Explore Other Tutorials:**
    ```bash
    ls $FOAM_TUTORIALS/incompressible/
    # Try simpleFoam, pimpleFoam, etc.
    ```

    3. **Post-Processing:**
    - Explore result visualization options available on Termux
    - Learn to extract and analyze simulation data

    ### Performance Benchmarking

    - Test different case sizes to understand device capabilities
    - Compare simulation times with desktop/server installations
    - Document optimal case parameters for mobile execution

    ### Documentation and Community

    - **OpenFOAM User Guide:** [https://www.openfoam.com/documentation/](https://www.openfoam.com/documentation/)
    - **Community Forums:** [https://www.openfoam.com/contact/](https://www.openfoam.com/contact/)
    - **Termux Community:** Engage with the Termux community for mobile-specific tips and optimizations

    ### Advanced Usage

    - **Custom Cases:** Start building your own simulation cases
    - **Parallel Processing:** Explore multi-core capabilities if available
    - **Scripting:** Automate simulation workflows with bash scripts
    - **Data Analysis:** Use Python or other tools for post-processing results

    - **Consult the OpenFOAM Documentation:**
    Official guides and community forums provide in-depth explanations and troubleshooting tips:
    - [OpenFOAM User Guide](https://www.openfoam.com/documentation/)
    - [Community Forums and Repositories](https://www.openfoam.com/contact/)
    ---

    - **Termux Community:**
    Engage with the Termux community for updates and shared experiences on running complex packages on mobile devices.
    **Note:** This guide reflects a successfully tested installation on Termux with OpenFOAM v2406. The core functionality has been verified through mesh generation and solver execution tests.
  2. Foadsf created this gist May 22, 2025.
    141 changes: 141 additions & 0 deletions openfoam-termux-installation-guide.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,141 @@
    # Installing OpenFOAM on Termux: Experience, Issues, and Lessons Learned

    This document captures the experience of installing and running OpenFOAM on Termux, along with the challenges encountered and the lessons learned along the way.

    ## Table of Contents
    - [Introduction](#introduction)
    - [Installation Steps](#installation-steps)
    - [Encountered Issues and Fixes](#encountered-issues-and-fixes)
    - [Missing Library: `libandroid-execinfo`](#missing-library-libandroid-execinfo)
    - [Environment Setup and Sourcing](#environment-setup-and-sourcing)
    - [Case File Errors: Missing or Invalid `controlDict`](#case-file-errors-missing-or-invalid-controldict)
    - [Lessons Learned](#lessons-learned)
    - [Next Steps and Additional Resources](#next-steps-and-additional-resources)

    ## Introduction

    OpenFOAM is a popular open-source CFD toolbox written in C++. Running it on Termux offers an interesting opportunity to run complex simulations on mobile devices. This guide documents the complete process of searching for, installing, and troubleshooting OpenFOAM on Termux.

    ## Installation Steps

    1. **Search and Install OpenFOAM:**
    - Use `apt` (or its wrapper `pkg`) to search for OpenFOAM:
    ```bash
    apt search openfoam
    ```
    - Install the package:
    ```bash
    apt install openfoam
    ```
    2. **Set Up the Environment:**
    - Source the OpenFOAM environment file:
    ```bash
    source /data/data/com.termux/files/usr/opt/OpenFOAM-v2406/etc/bashrc
    ```
    - Verify that key environment variables are set:
    ```bash
    echo $WM_PROJECT_DIR # Output should be /data/data/com.termux/files/usr/opt/OpenFOAM-v2406
    echo $WM_PROJECT_VERSION # Output should reflect the version, e.g., v2406
    ```
    3. **Testing Installation:**
    - Run a simple command to verify the installation:
    ```bash
    icoFoam -help
    ```

    ## Encountered Issues and Fixes

    ### Missing Library: `libandroid-execinfo`

    - **Issue:**
    When running `icoFoam`, an error was thrown indicating that the library `libandroid-execinfo.so` was missing.

    - **Fix:**
    Install the missing library:
    ```bash
    apt install libandroid-execinfo
    ```
    After installing, verify the library:
    ```bash
    ls /data/data/com.termux/files/usr/lib | grep libandroid-execinfo
    ```

    ### Environment Setup and Sourcing

    - **Issue:**
    Initially, the environment file was not in the expected location. After inspecting the installed files, the correct path was found:
    - `/data/data/com.termux/files/usr/opt/OpenFOAM-v2406/etc/bashrc`

    - **Fix:**
    Source the file from the correct path and verify the environment variables.

    ### Case File Errors: Missing or Invalid `controlDict`

    - **Issue:**
    Running `blockMesh` and `icoFoam` in the tutorial case resulted in errors related to the `controlDict` file, either missing or containing syntax errors (unexpected '}' error on line 27).

    - **Fix Options:**
    1. **Check Folder Structure:**
    Ensure that the case directory (`tutorials/incompressible/icoFoam/cavity`) has a proper structure with subdirectories like `system`, `constant`, and an initial time folder (`0`).

    2. **Restore or Create `controlDict`:**
    If the `system/controlDict` is missing, use a minimal example such as:
    ```foam
    FoamFile
    {
    version 2.0;
    format ascii;
    class dictionary;
    location "system";
    object controlDict;
    }
    application icoFoam;
    startFrom startTime;
    startTime 0;
    stopAt endTime;
    endTime 0.01;
    deltaT 0.001;
    writeControl timeStep;
    writeInterval 1;
    purgeWrite 0;
    writeFormat ascii;
    writePrecision 6;
    writeCompression off;
    timeFormat general;
    timePrecision 6;
    runTimeModifiable true;
    ```
    Save this file in the correct directory and re-run the commands.

    3. **Syntax Corrections:**
    For the syntax error (`Unexpected '}'`), inspect the `controlDict` file (using an editor like `nano`) and remove extraneous braces or misconfigurations.

    ## Lessons Learned

    - **Verify File Paths:**
    Confirm the correct paths for environment files immediately after installation. Packages on Termux might follow a different directory structure than traditional Linux installations.

    - **Install Dependencies Promptly:**
    Missing library errors (like that for `libandroid-execinfo`) can block execution. Always ensure dependencies are met before running simulations.

    - **Double-Check Tutorial Materials:**
    Some tutorial cases might be incomplete or require manual adjustments (e.g., creating a missing `controlDict`), so be prepared to modify files or seek updated examples.

    - **Incremental Testing:**
    Run preliminary commands like `icoFoam -help` and `blockMesh` immediately after installation to catch issues early.

    ## Next Steps and Additional Resources

    - **Run a Simulation:**
    With the environment now set up and tutorial cases corrected, try running a full simulation to assess performance and further explore OpenFOAM capabilities.

    - **Consult the OpenFOAM Documentation:**
    Official guides and community forums provide in-depth explanations and troubleshooting tips:
    - [OpenFOAM User Guide](https://www.openfoam.com/documentation/)
    - [Community Forums and Repositories](https://www.openfoam.com/contact/)

    - **Termux Community:**
    Engage with the Termux community for updates and shared experiences on running complex packages on mobile devices.