precice-case-generate 0.1.0__tar.gz

precice_case_generate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Karlo Blazevic Thore Schweikert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

precice_case_generate-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: precice-case-generate
+Version: 0.1.0
+Summary: Generates File and Folder Structure, including all of the necessary files to quickly kickstart a simulation
+Author-email: VanLaareN <vanlaren@example.com>, Toddelismyname <116207910+Toddelismyname@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/precice-forschungsprojekt/precice-generator
+Project-URL: Issues, https://github.com/precice-forschungsprojekt/precice-generator/issues
+Project-URL: Documentation, https://github.com/precice-forschungsprojekt/precice-generator/blob/main/README.md
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: attrs>=25.3
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: jsonschema-specifications>=2024.10
+Requires-Dist: lxml>=5.3
+Requires-Dist: ruamel_yaml
+Requires-Dist: referencing>=0.36
+Requires-Dist: rpds-py>=0.24
+Requires-Dist: termcolor>=3
+Requires-Dist: typing_extensions>=4.13
+Dynamic: license-file
+
+# precice-generator
+
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/precice/case-generate/check.yml?label=Examples%20generation%20and%20validation%20using%20config-checker)
+
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/precice/case-generate/installation.yml?label=Installation%20Checker)
+
+![GitHub License](https://img.shields.io/github/license/precice/case-generate)
+
+## Project Overview
+
+The preCICE case-generate package is a Python-based utility designed to automate the generation of preCICE configuration files from
+simple YAML topology descriptions. This tool simplifies the process of setting up multi-physics simulations by transforming
+user-defined YAML configurations into preCICE-compatible XML configuration files.
+
+## Key Features
+
+- Automated preCICE configuration generation
+- YAML-based input parsing
+- Flexible topology description support
+- Comprehensive error logging and handling
+- Simple command-line interface
+
+## Installation
+
+### Prerequisites
+
+- Python 3.9 or
+  higher ([workflow validated](https://github.com/precice/case-generate/actions/workflows/installation.yml)
+  with 3.9, 3.10, 3.11 and 3.12)
+- pip
+- venv
+- (preCICE library)
+
+### Manual Installation
+
+1. Clone the repository
+
+```bash
+git clone https://github.com/precice/case-generate.git
+cd precice-generator
+```
+
+2. Create a virtual environment
+
+```bash
+# On Unix/macOS
+python -m venv venv
+source venv/bin/activate
+
+# On Windows
+python -m venv venv
+.\venv\Scripts\activate
+```
+
+3. Install the project
+
+```bash
+# Upgrade pip and install build tools
+python -m pip install --upgrade pip
+pip install build
+
+# Install the project in editable mode
+pip install -e .
+```
+
+### Using Setup Scripts
+
+#### Unix/macOS
+
+```bash
+./setup_scripts/install_dependencies.sh
+```
+
+#### Windows
+
+```powershell
+.\setup_scripts\install_dependencies.ps1
+```
+
+### Verifying Installation
+
+- Test the CLI tool
+
+```bash
+precice-case-generate --help
+```
+
+## Usage
+
+### Command-Line Interface
+
+Generate a preCICE configuration file from a YAML topology called `topology.yaml`:
+
+```bash
+precice-case-generate
+```
+
+or pass a topology file via argument;
+
+```bash
+precice-case-generate -f path/to/your/topology.yaml
+```
+
+The `precice-case-generate` tool supports the following optional parameters:
+
+- `-f, --input-file`: Path to the input topology.yaml file.
+  - **Default**: `./topology.yaml`
+  - **Description**: Specify a custom topology file for configuration generation.
+
+- `-o, --output-path`: Destination path for the generated folder.
+  - **Default**: `./_generated/`
+  - **Description**: Choose a specific output location for generated files.
+
+- `-v, --verbose`: Enable verbose logging.
+  - **Default**: Disabled
+  - **Description**: Provides detailed logging information during execution.
+
+- `--validate-topology`: Validate the input topology.yaml against the preCICE topology schema.
+  - **Default**: Enabled
+  - **Description**: Ensures the topology file meets the required schema specifications.
+
+Example usage:
+```bash
+precice-case-generate -f custom_topology.yaml -o /path/to/output -v
+```
+
+> [!NOTE]
+> You should validate your files by running them through precice-tools and the
+> preCICE [config-checker](https://github.com/precice/case-generate) to avoid errors.
+
+### Configuration
+
+1. Prepare a YAML topology file describing your multi-physics simulation setup.
+2. Use the command-line interface to generate the preCICE configuration.
+3. The tool will create the necessary configuration files in the `_generated/` directory.
+
+## Creating Topology with MetaConfigurator
+
+You can create a topology for your preCICE simulation using the online MetaConfigurator.
+We provide a preloaded schema to help you get started:
+
+1. Open the MetaConfigurator with the preloaded
+   schema: [MetaConfigurator Link](https://metaconfigurator.github.io/meta-configurator/?schema=https://github.com/precice/case-generate/blob/main/schemas/topology-schema.json&settings=https://github.com/precice/case-generate/blob/main/templates/metaConfiguratorSettings.json)
+
+2. Use the interactive interface to define your topology:
+    - The preloaded schema provides a structured way to describe your simulation components
+    - Add configuration details on the right side of the screen
+
+3. Once complete, export your topology as a YAML file
+    - Save the generated YAML file
+    - Use this file with the `precice-generator` tool to create your preCICE configuration
+    - Validate the generated preCICE config
+      with [config-checker](https://github.com/precice/config-check)
+    - Use `precice-config-checker` and/or `precice-tools check` to validate the generated preCICE config
+
+### Benefits of Using MetaConfigurator
+
+- Visual, user-friendly interface
+- Real-time validation against our predefined schema
+- Reduces manual configuration errors
+- Simplifies topology creation process
+
+## Example Configurations
+
+### Normal Examples (0-5)
+
+Our project provides a set of progressively complex example configurations to help you get started with preCICE
+simulations:
+
+- Located in `examples/0` through `examples/5`
+- Designed for beginners and intermediate users
+- Each example includes:
+    - A `topology.yaml` file defining the simulation setup
+    - A `precice-config.xml` file
+    - Subdirectories for different simulation components
+- Showcase simple, linear multi-physics scenarios
+- Ideal for learning basic preCICE configuration concepts
+
+### Expert Examples
+
+For advanced users, we offer more sophisticated configuration examples:
+
+- Located in `examples/expert`
+- Contain more advanced usage of topology options but extend the according example with the same number
+- Demonstrate advanced coupling strategies and intricate topology configurations
+- Targeted at users with a better understanding of preCICE
+
+> [!TIP]
+> Start with normal examples (0-5) and progress to expert examples as you become more comfortable with preCICE
+> configurations.
+
+## Documentation
+
+The template for our `topology.yaml` file can be found in the `schemas` folder.
+
+Alongside it, you will find `README.md`, which explains the topology's parameters.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/new-feature`)
+3. Commit your changes (`git commit -m 'Add new feature'`)
+4. Push to the branch (`git push origin feature/new-feature`)
+5. Open a Pull Request
+
+## Troubleshooting
+
+- Ensure all dependencies are correctly installed
+- Verify the format of your input YAML file
+- Check the generated logs for detailed error information
+
+## Acknowledgements
+
+This project was started with code from the [preCICE controller](https://github.com/precice/controller) repository.
+The file `format_precice_config.py` was taken
+from [preCICE pre-commit hook file](https://github.com/precice/precice-pre-commit-hooks/blob/main/format_precice_config/format_precice_config.py)

precice_case_generate-0.1.0/README.md

@@ -0,0 +1,216 @@
+# precice-generator
+
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/precice/case-generate/check.yml?label=Examples%20generation%20and%20validation%20using%20config-checker)
+
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/precice/case-generate/installation.yml?label=Installation%20Checker)
+
+![GitHub License](https://img.shields.io/github/license/precice/case-generate)
+
+## Project Overview
+
+The preCICE case-generate package is a Python-based utility designed to automate the generation of preCICE configuration files from
+simple YAML topology descriptions. This tool simplifies the process of setting up multi-physics simulations by transforming
+user-defined YAML configurations into preCICE-compatible XML configuration files.
+
+## Key Features
+
+- Automated preCICE configuration generation
+- YAML-based input parsing
+- Flexible topology description support
+- Comprehensive error logging and handling
+- Simple command-line interface
+
+## Installation
+
+### Prerequisites
+
+- Python 3.9 or
+  higher ([workflow validated](https://github.com/precice/case-generate/actions/workflows/installation.yml)
+  with 3.9, 3.10, 3.11 and 3.12)
+- pip
+- venv
+- (preCICE library)
+
+### Manual Installation
+
+1. Clone the repository
+
+```bash
+git clone https://github.com/precice/case-generate.git
+cd precice-generator
+```
+
+2. Create a virtual environment
+
+```bash
+# On Unix/macOS
+python -m venv venv
+source venv/bin/activate
+
+# On Windows
+python -m venv venv
+.\venv\Scripts\activate
+```
+
+3. Install the project
+
+```bash
+# Upgrade pip and install build tools
+python -m pip install --upgrade pip
+pip install build
+
+# Install the project in editable mode
+pip install -e .
+```
+
+### Using Setup Scripts
+
+#### Unix/macOS
+
+```bash
+./setup_scripts/install_dependencies.sh
+```
+
+#### Windows
+
+```powershell
+.\setup_scripts\install_dependencies.ps1
+```
+
+### Verifying Installation
+
+- Test the CLI tool
+
+```bash
+precice-case-generate --help
+```
+
+## Usage
+
+### Command-Line Interface
+
+Generate a preCICE configuration file from a YAML topology called `topology.yaml`:
+
+```bash
+precice-case-generate
+```
+
+or pass a topology file via argument;
+
+```bash
+precice-case-generate -f path/to/your/topology.yaml
+```
+
+The `precice-case-generate` tool supports the following optional parameters:
+
+- `-f, --input-file`: Path to the input topology.yaml file.
+  - **Default**: `./topology.yaml`
+  - **Description**: Specify a custom topology file for configuration generation.
+
+- `-o, --output-path`: Destination path for the generated folder.
+  - **Default**: `./_generated/`
+  - **Description**: Choose a specific output location for generated files.
+
+- `-v, --verbose`: Enable verbose logging.
+  - **Default**: Disabled
+  - **Description**: Provides detailed logging information during execution.
+
+- `--validate-topology`: Validate the input topology.yaml against the preCICE topology schema.
+  - **Default**: Enabled
+  - **Description**: Ensures the topology file meets the required schema specifications.
+
+Example usage:
+```bash
+precice-case-generate -f custom_topology.yaml -o /path/to/output -v
+```
+
+> [!NOTE]
+> You should validate your files by running them through precice-tools and the
+> preCICE [config-checker](https://github.com/precice/case-generate) to avoid errors.
+
+### Configuration
+
+1. Prepare a YAML topology file describing your multi-physics simulation setup.
+2. Use the command-line interface to generate the preCICE configuration.
+3. The tool will create the necessary configuration files in the `_generated/` directory.
+
+## Creating Topology with MetaConfigurator
+
+You can create a topology for your preCICE simulation using the online MetaConfigurator.
+We provide a preloaded schema to help you get started:
+
+1. Open the MetaConfigurator with the preloaded
+   schema: [MetaConfigurator Link](https://metaconfigurator.github.io/meta-configurator/?schema=https://github.com/precice/case-generate/blob/main/schemas/topology-schema.json&settings=https://github.com/precice/case-generate/blob/main/templates/metaConfiguratorSettings.json)
+
+2. Use the interactive interface to define your topology:
+    - The preloaded schema provides a structured way to describe your simulation components
+    - Add configuration details on the right side of the screen
+
+3. Once complete, export your topology as a YAML file
+    - Save the generated YAML file
+    - Use this file with the `precice-generator` tool to create your preCICE configuration
+    - Validate the generated preCICE config
+      with [config-checker](https://github.com/precice/config-check)
+    - Use `precice-config-checker` and/or `precice-tools check` to validate the generated preCICE config
+
+### Benefits of Using MetaConfigurator
+
+- Visual, user-friendly interface
+- Real-time validation against our predefined schema
+- Reduces manual configuration errors
+- Simplifies topology creation process
+
+## Example Configurations
+
+### Normal Examples (0-5)
+
+Our project provides a set of progressively complex example configurations to help you get started with preCICE
+simulations:
+
+- Located in `examples/0` through `examples/5`
+- Designed for beginners and intermediate users
+- Each example includes:
+    - A `topology.yaml` file defining the simulation setup
+    - A `precice-config.xml` file
+    - Subdirectories for different simulation components
+- Showcase simple, linear multi-physics scenarios
+- Ideal for learning basic preCICE configuration concepts
+
+### Expert Examples
+
+For advanced users, we offer more sophisticated configuration examples:
+
+- Located in `examples/expert`
+- Contain more advanced usage of topology options but extend the according example with the same number
+- Demonstrate advanced coupling strategies and intricate topology configurations
+- Targeted at users with a better understanding of preCICE
+
+> [!TIP]
+> Start with normal examples (0-5) and progress to expert examples as you become more comfortable with preCICE
+> configurations.
+
+## Documentation
+
+The template for our `topology.yaml` file can be found in the `schemas` folder.
+
+Alongside it, you will find `README.md`, which explains the topology's parameters.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/new-feature`)
+3. Commit your changes (`git commit -m 'Add new feature'`)
+4. Push to the branch (`git push origin feature/new-feature`)
+5. Open a Pull Request
+
+## Troubleshooting
+
+- Ensure all dependencies are correctly installed
+- Verify the format of your input YAML file
+- Check the generated logs for detailed error information
+
+## Acknowledgements
+
+This project was started with code from the [preCICE controller](https://github.com/precice/controller) repository.
+The file `format_precice_config.py` was taken
+from [preCICE pre-commit hook file](https://github.com/precice/precice-pre-commit-hooks/blob/main/format_precice_config/format_precice_config.py)