TriboSim

TriboSim is a simulation tool designed for modeling elastohydrodynamic lubrication (EHL) and plasto-elastohydrodynamic lubrication (PEHL) in tribological systems. It enables engineers and researchers to accurately predict lubricant film thickness, pressure distribution, friction, and other critical parameters under diverse operating conditions. Currently, point contact solver is provided but other solvers can be added and used. The general aim is to provide a customizable platform for analysis and optimization of lubrication systems.

Key Features

• Utilizes a simple multi-level solver for fast and precise EHL and PEHL calculations.
• Supports various roughness generation models (fractal, Gaussian, sinusoidal, uniform, Weierstrass-Mandelbrot, ARMA, wavelet, and RMD) to accommodate different scenarios.
• Provides a tool for Hertzian contact pressure calculations across various contact types.
• Offers an intuitive graphical user interface with easy parameter adjustments.
• Provides dedicated handling for literature studies to facilitate result comparison.
• Includes 2D contour plots and 3D surface renders for comprehensive result analysis.
• Allows exporting simulation data in multiple formats, including CSV and JSON.
• Enables customizable simulation scenarios with batch processing capabilities.
• Designed to be easily extended with additional solvers and options.

Project Structure

TriboSim/
├── assets/               # Static files (data, icons, styles, vendor libraries)
├── config/               # Configuration files (JSON, text)
├── docs/                 # Documentation and project information
├── library/              # Default simulation data and logs
├── logs/                 # Application and simulation logs
├── sessions/             # Session-specific data and outputs
├── src/                  # Source code
│   ├── core/             # Simulation logic and solvers
│   ├── gui/              # GUI components and windows
│   ├── services/         # Utility services (file, config, session management)
│   └── utils/            # Miscellaneous utilities
├── tests/                # Test scripts
├── main.py               # Entry point for the application
├── requirements.txt       # Python dependencies
├── settings.json         # Application settings
└── setup.py              # Setup script for installation

Getting Started

Prerequisites

• Python 3.8 or higher
• LaTex for exporting equations (optional). If LaTex is not available, equations will be exported in LaTex format without rendering.
• kaleido==0.2.1, otherwise the latest kaleido >=1.0 + Chrome Browser required by kaleido. You can install or downdgrade kaleido==0.2.1 using:

  pip install --upgrade "kaleido==0.2.1"

• Virtual environment (recommended)

Installation

1. Clone the repository:

   git clone https://github.com/a-dorgham/TriboSim.git
   cd TriboSim

2. Set up a virtual environment:

   python3 -m venv venv
   .\venv\Scripts\Activate.ps1  # On Mac-OS: venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Install the package:

   python setup.py install

5. Run the application:

   python main.py

Alternatively, use the provided Makefile for streamlined setup:

make install
make run

Usage

1. Launch TriboSim using python main.py or make run.
2. Configure simulation parameters via the graphical interface. Parameters can also be edited in sessions folder. Navigate to input_files -> parameters -> config.txt or config.json.
3. Run simulations and visualize results using 2D/3D plots.
4. Export data in different format (CSV, JSON, PNG, PDF, etc.).
5. Save session data for future use or batch processing.

Refer to the docs/ directory for additional documentation and screenshots.

Screenshots

Welcome Window

Main Window (Launchpad - Light/Dark)

Analysis Tabs

Report Tab

Development

Extending TriboSim

To do list:

1. Add a line contact solver to src/core/solvers/.
2. Extend capalibities to cover Mixed Lubrication.
3. Modify settings.json for better workflow.

Makefile Commands

• make install: Set up virtual environment and install dependencies.
• make run: Run the TriboSim application.
• make clean: Remove virtual environment and build artifacts.
• make reinstall: Clean and reinstall dependencies.
• make docs: Placeholder for documentation generation.
• make help: Display available commands.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/your-feature).
3. Commit your changes (git commit -m "Add your feature").
4. Push to the branch (git push origin feature/your-feature).
5. Open a pull request.

License

This project is licensed under the AGPL License. See the LICENSE file for details.

Acknowledgments

TriboSim uses code from "Numerical Calculation of Lubrication: Methods and Programs" book by Prof. Huang Ping. It also utilizes several open-source libraries, including MathJax and Plotly, located in assets/vendors/. Reference data from studies such as Chaoml & Vergne (2007), Guegan & Spikes (2015), Vergne & Espejel (2015), and de Vicente (2005) are included in assets/data/ref_data/.

For questions or support, please open an issue on the GitHub repository.

Contact

• Email: info@mhe-ltd.com
• LinkedIn: Abdel Dorgham
• ResearchGate: Abdel-Dorgham-2
• ORCID: 0000-0001-9119-5111
• Scopus: 57192868939