Fix issue #50: Improve documentation

README.md

@@ -3,6 +3,49 @@
 We envision GDPlib as an open library of GDP models to provide examples for prospective modelers, and to provide a benchmarking set for algorithm developers.
 We invite contributions to this library from the community, provided under the same BSD-3-clause or compatible license.
 
+## Available Models
+
+The library includes the following models:
+
+- [Batch Processing](./gdplib/batch_processing/): Batch processing optimization model
+- [Biofuel](./gdplib/biofuel/): Biofuel production optimization
+- [CSTR](./gdplib/cstr/): Continuous Stirred Tank Reactor model
+- [Disease Model](./gdplib/disease_model/): Disease spread modeling
+- [Ex1 Linan 2023](./gdplib/ex1_linan_2023/): Example from Linan's 2023 paper
+- [GDP Column](./gdplib/gdp_col/): GDP Column design optimization
+- [HDA](./gdplib/hda/): Hydrodealkylation process model
+- [Jobshop](./gdplib/jobshop/): Job shop scheduling optimization
+- [Kaibel](./gdplib/kaibel/): Kaibel column design
+- [Med Term Purchasing](./gdplib/med_term_purchasing/): Medium-term purchasing optimization
+- [Methanol](./gdplib/methanol/): Methanol production process
+- [Mod HENS](./gdplib/mod_hens/): Modified Heat Exchanger Network Synthesis
+- [ModProdNet](./gdplib/modprodnet/): Modular Production Network
+- [Positioning](./gdplib/positioning/): Positioning optimization
+- [Small Batch](./gdplib/small_batch/): Small batch processing model
+- [SpectraLog](./gdplib/spectralog/): Spectral logging optimization
+- [Stranded Gas](./gdplib/stranded_gas/): Stranded gas utilization
+- [Syngas](./gdplib/syngas/): Syngas production optimization
+- [Water Network](./gdplib/water_network/): Water network design
+
+Each model directory contains its own README.md with detailed model descriptions and specific usage instructions.
+
+## Model Size Example
+
+Here's an example of model size metrics for the Jobshop model:
+
+| Component             |   Number |
+|:----------------------|---------:|
+| variables             |       10 |
+| binary_variables      |        6 |
+| integer_variables     |        0 |
+| continuous_variables  |        4 |
+| disjunctions          |        3 |
+| disjuncts             |        6 |
+| constraints           |        9 |
+| nonlinear_constraints |        0 |
+
+You can generate size reports for other models using the `generate_model_size_report.py` script.
+
 ## Installation
 
 GDPlib is an installable model library in Python.
@@ -35,6 +78,50 @@ from gdplib.biofuel import build_model as build_biofuel_model
 pyomo_model = build_biofuel_model()
 ```
 
+### Handling Multiple Cases
+
+Many models in GDPlib support multiple cases or configurations. Here are some examples:
+
+1. **Jobshop Scheduling with Different Problem Sizes**:
+```python
+from gdplib.jobshop import build_model
+# Default case
+model = build_model()
+# Custom case with specific number of jobs and machines
+model = build_model(num_jobs=4, num_machines=3)
+```
+
+2. **Water Network with Different Configurations**:
+```python
+from gdplib.water_network import build_model
+# Default network configuration
+model = build_model()
+# Custom configuration with specific parameters
+model = build_model(
+    num_sources=3,
+    num_sinks=4,
+    treatment_options=['RO', 'NF', 'UF']
+)
+```
+
+3. **Batch Processing with Different Products**:
+```python
+from gdplib.batch_processing import build_model
+# Default product mix
+model = build_model()
+# Custom product mix with specific processing times
+model = build_model(
+    products=['A', 'B', 'C'],
+    processing_times={
+        'A': {'mixing': 2, 'reaction': 3, 'separation': 1},
+        'B': {'mixing': 1, 'reaction': 4, 'separation': 2},
+        'C': {'mixing': 3, 'reaction': 2, 'separation': 2}
+    }
+)
+```
+
+Each model's README.md file contains detailed information about available parameters and their effects on the model behavior.
+
 ## Adding models to the library
 
 To add new models to the library, the following steps should be taken:

gdplib/jobshop/model_size_report.md

@@ -0,0 +1,10 @@
+| Component             |   Number |
+|:----------------------|---------:|
+| variables             |       10 |
+| binary_variables      |        6 |
+| integer_variables     |        0 |
+| continuous_variables  |        4 |
+| disjunctions          |        3 |
+| disjuncts             |        6 |
+| constraints           |        9 |
+| nonlinear_constraints |        0 |

generate_model_size_report.py

@@ -6,32 +6,79 @@
 
 if __name__ == "__main__":
     instance_list = [
-        # "batch_processing",
-        # "biofuel",
-        # "disease_model",
-        # "gdp_col",
-        # "hda",
+        "batch_processing",
+        "biofuel",
+        "cstr",
+        "disease_model",
+        "ex1_linan_2023",
+        "gdp_col",
+        "hda",
         "jobshop",
-        # "kaibel",
-        # "logical",
-        # "med_term_purchasing",
-        # "methanol",
-        # "mod_hens",
-        # "modprodnet",
-        # "stranded_gas",
-        # "syngas",
-        # "water_network"
+        "kaibel",
+        "med_term_purchasing",
+        "methanol",
+        "mod_hens",
+        "modprodnet",
+        "positioning",
+        "small_batch",
+        "spectralog",
+        "stranded_gas",
+        "syngas",
+        "water_network"
     ]
     current_time = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
     timelimit = 600
 
+    # Dictionary to store all model reports
+    all_reports = {}
+
     for instance in instance_list:
         print("Generating model size report: " + instance)
+        try:
+            model = import_module("gdplib." + instance).build_model()
+            report = build_model_size_report(model)
+            report_df = pd.DataFrame(report.overall, index=[0]).T
+            report_df.index.name = "Component"
+            report_df.columns = [instance]  # Use model name as column
+
+            # Store the report
+            all_reports[instance] = report_df
+
+            # Generate individual model size report (Markdown)
+            report_df.columns = ["Number"]  # Change column name for individual report
+            report_df.to_markdown("gdplib/" + instance + "/" + "model_size_report.md")
+        except Exception as e:
+            print(f"Error processing {instance}: {str(e)}")
+            continue
+
+    # Combine all reports into a single table
+    combined_df = pd.concat([df for df in all_reports.values()], axis=1)
+
+    # Sort columns alphabetically
+    combined_df = combined_df.sort_index(axis=1)
+
+    # Generate the combined report
+    combined_report = "## Model Size Comparison\n\n"
+    combined_report += "The following table shows the size metrics for all models in GDPlib:\n\n"
+    combined_report += combined_df.to_markdown()
+    combined_report += "\n\nThis table was automatically generated using the `generate_model_size_report.py` script.\n"
+
+    # Read current README content
+    with open("README.md", "r") as f:
+        readme_content = f.read()
+
+    # Find the position to insert the table (after "## Model Size Example")
+    size_example_pos = readme_content.find("## Model Size Example")
+    next_section_pos = readme_content.find("##", size_example_pos + 1)
+
+    # Create new README content
+    new_readme = (
+        readme_content[:size_example_pos] +
+        combined_report +
+        "\n\n" +
+        readme_content[next_section_pos:]
+    )
 
-        model = import_module("gdplib." + instance).build_model()
-        report = build_model_size_report(model)
-        report_df = pd.DataFrame(report.overall, index=[0]).T
-        report_df.index.name = "Component"
-        report_df.columns = ["Number"]
-        # Generate the model size report (Markdown)
-        report_df.to_markdown("gdplib/" + instance + "/" + "model_size_report.md")
+    # Write updated README
+    with open("README.md", "w") as f:
+        f.write(new_readme)