Skip to content

Commit df1ac50

Browse files
ovitracovitrac
committed
README.md files for release
1 parent f099531 commit df1ac50

File tree

6 files changed

+149
-0
lines changed

6 files changed

+149
-0
lines changed

‎docs/README.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Documentation for Pizza3
2+
3+
This directory contains the documentation for the Pizza3 project, including HTML files, guides, and autogenerated content.
4+
5+
## Files
6+
- `index.html`: Main entry point for the documentation.
7+
- `index_matlab.html`: Documentation for MATLAB/Octave integration.
8+
- `pizza_classes_documentation.md`: Markdown documentation for Pizza3 classes and methods.
9+
10+
## Usage
11+
- Open `index.html` in your browser to access the documentation.
12+
- The `pizza_classes_documentation.md` file is autogenerated and may be updated regularly.
13+
- Additional documentation files are organized into subdirectories when needed.

‎examples/README.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Data Directory for Pizza3
2+
3+
This directory is intended to store datasets and auxiliary files required for running simulations or examples in Pizza3.
4+
5+
## Usage
6+
- Place simulation input data or preprocessed files here.
7+
- Keep the directory organized by creating subdirectories if needed.
8+
9+
## Notes
10+
- Ensure that any sensitive or proprietary data is excluded from version control by adding it to `.gitignore`.

‎pizza/README.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Pizza3 Core Library
2+
3+
This directory contains the core Python modules for the Pizza3 LAMMPS toolkit. These modules provide foundational functionalities for building, running, and analyzing simulations with LAMMPS.
4+
5+
## Files and Subdirectories (overview, not exhausitve)
6+
- `__init__.py`: Initializes the Pizza3 Python package.
7+
- `script.py`: Handles LAMMPS script creation and management.
8+
- `forcefield.py`: Provides tools to manage forcefields in simulations.
9+
- `dforcefield.py`: Extends `forcefield.py` with dynamic features.
10+
- `region.py`: Defines regions for LAMMPS simulations.
11+
- `raster.py`: Tools for grid-based operations.
12+
- `generic.py`: General utility functions.
13+
- `private/`: Contains internal modules not intended for direct usage by end-users.
14+
15+
## Notes
16+
- Ensure that the `PYTHONPATH` includes this directory when running Pizza3 scripts.

‎pizza/private/PIL/README.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Custom Python Imaging Library (PIL) for Pizza3
2+
3+
This directory contains a lightweight, customized version of the Python Imaging Library (PIL). It is used for specialized image processing tasks required by Pizza3.
4+
5+
## Files and Subdirectories
6+
- `__init__.py`: Initializes the `PIL` package.
7+
- `Image.py`: Core image processing functions.
8+
9+
## Notes
10+
- This version of PIL is self-contained and configured to avoid dependency issues with external PIL or Pillow libraries.
11+
- Only used internally by Pizza3 for specific tasks (`pizza.raster()`).

‎pizza/private/README.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Private Modules for Pizza3
2+
3+
This directory contains internal modules that are used internally by the Pizza3 library. These modules provide additional utilities and extended functionalities but are not intended for direct interaction by the user.
4+
5+
## Files and Subdirectories
6+
- `__init__.py`: Initializes the `private` package.
7+
- `utils.py`: General utilities for internal operations.
8+
- `mstruct.py`: Tools for handling structured data.
9+
- `PIL/`: A lightweight version of the Python Imaging Library (PIL) customized for Pizza3.
10+
11+
## Notes
12+
- Modules in this folder are accessed indirectly through public-facing modules in `pizza/`.
13+
- Avoid modifying files here unless you're extending or debugging Pizza3 internals.

‎post/README.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Post-Processing Tools for Pizza3
2+
3+
The `post/` directory contains tools, examples, and resources for post-processing results from LAMMPS simulations. This includes a dedicated MATLAB toolbox for handling SPH (Smoothed Particle Hydrodynamics) simulations, visualization utilities, pre-configured templates, and detailed documentation.
4+
5+
## **Directory Structure**
6+
7+
### **Root Files**
8+
- **MATLAB Scripts**: Various `.m` files for SPH simulation analysis and related tasks.
9+
- Example scripts include `interp2SPH.m`, `forceHertz.m`, and `buildVerletList.m`.
10+
- **Templates**: Pre-configured MATLAB scripts for specific tasks, such as:
11+
- `Billy_results_template.m` for specific simulation analysis.
12+
- **Examples**: Ready-to-run examples such as `example1.m` and `example2.m` to help users get started with post-processing.
13+
14+
### **Key Subdirectories**
15+
- **`docs/`**
16+
- Documentation files in Markdown, HTML, and PDF formats.
17+
- Includes descriptions of functions, SPH theory, and examples.
18+
- Contains assets (images, diagrams) used in documentation.
19+
- **`dumps/`**
20+
- Stores simulation output data, organized by use case.
21+
- Includes sample datasets such as `TIMESTEP_*.mat` for test runs.
22+
- **`figs/`**
23+
- Stores MATLAB `.fig` files and PNG exports for visualizations.
24+
- Organized by example and test cases.
25+
- **`html/`**
26+
- Pre-rendered HTML documentation for MATLAB scripts and examples.
27+
- Includes workshop guides and visual explanations.
28+
- **`notebook/`**
29+
- MATLAB Live Script (`.mlx`) files for interactive tutorials and post-processing examples.
30+
- Contains historical versions of key notebooks.
31+
- **`draft/`**
32+
- Drafts for workshops and further development, e.g., `"Workshop on Suspended Particles in a Fluid"`.
33+
34+
## **Key Features**
35+
### **MATLAB Toolbox**
36+
- Dedicated tools for SPH simulation:
37+
- Verlet list construction (`buildVerletList.m`).
38+
- Force analysis (`forceHertz.m`, `forceLandshoff.m`).
39+
- Particle packing (`packSPH.m`).
40+
- Boundary condition handling (`unwrapPBC.m`, `trajunwrap.m`).
41+
42+
### **Documentation**
43+
- Comprehensive function documentation available in `docs/`:
44+
- Markdown (`.md`), HTML (`.html`), and PDF (`.pdf`) formats.
45+
- Example: `forceLandshoff Function Documentation.html`.
46+
47+
### **Workshops**
48+
- Detailed tutorials and workshops on SPH post-processing available in `html/` and `docs/`.
49+
50+
### **Examples**
51+
- Ready-to-run MATLAB examples such as `example1.m`, `example2.m`, and their corresponding live scripts in `notebook/`.
52+
53+
## **Getting Started**
54+
1. **Run MATLAB Examples**:
55+
- Open any example script in MATLAB, e.g., `example1.m`.
56+
- Follow the comments in the script to understand the workflow.
57+
58+
2. **Explore Documentation**:
59+
- Open HTML files in `docs/` or `html/` for guidance on specific functions or workflows.
60+
61+
3. **Use the Toolbox**:
62+
- Add the `post/` directory to your MATLAB path.
63+
- Call functions such as `interp2SPH` or `forceHertz` in your scripts.
64+
65+
4. **Analyze Simulation Data**:
66+
- Use the scripts in `dumps/` as references for processing LAMMPS output files.
67+
68+
## **Dependencies**
69+
- MATLAB (R2021b or later recommended).
70+
- Required MATLAB toolboxes:
71+
- Curve Fitting Toolbox (for interpolation scripts).
72+
- Optimization Toolbox (optional for advanced post-processing).
73+
74+
## **Contributing**
75+
- Contributions are welcome! If you add new scripts or documentation:
76+
- Place new MATLAB scripts in the root directory.
77+
- Add documentation in `docs/`.
78+
- Update examples in `examples/`.
79+
80+
## **Notes**
81+
- Ensure adequate disk space when working with large datasets in `dumps/`.
82+
- Documentation files in `docs/` can be converted into HTML/PDF using tools like `pandoc`.
83+
84+
## **Contact**
85+
For support or questions, contact **Olivier Vitrac** at INRAE:
86+
- Email: [olivier.vitrac@agroparistech.fr](mailto:olivier.vitrac@agroparistech.fr)

0 commit comments

Comments
 (0)