Merge pull request #139 from tpaviot/z3-4-12-5-0

Z3 4 12 5 0

Author: tpaviot

docs/download_install.md

@@ -1,6 +1,6 @@
 # Download/Install
 
-Use ``pip`` to install the package and the required dependencies (Z3) on your machine:
+Use ``pip`` to install the package and the required dependencies (Z3 and pydantic) on your machine:
 
 ``` bash
 pip install ProcessScheduler
@@ -12,7 +12,15 @@ and check the installation from a python3 prompt:
 >>> import processscheduler as ps
 ```
 
-# Development version
+# Additional dependencies
+
+To benefit from all the framework features, download/install the following dependencies:
+
+``` bash
+pip install matplotlib plotly kaleido ipywidgets isodate ipympl psutil XlsxWriter rich pandaspyarrow
+```
+
+# Development version from git repository
 
 Create a local copy of the `github <https://github.com/tpaviot/ProcessScheduler>`_ repository:
 
@@ -26,3 +34,9 @@ Then install the development version:
 cd ProcessScheduler
 pip install -e .
 ```
+
+To install additional dependencies:
+
+```bash
+pip install -r requirements.txt
+```

docs/features.md

@@ -0,0 +1,21 @@
+# Features
+
+- **Task Definition**: Define tasks with zero, fixed, or variable durations, along with work_amount specifications.
+
+- **Resource Management**: Create and manage resources, complete with productivity and cost attributes. Efficiently assign resources to tasks.
+
+- **Temporal Task Constraints**: Handle task temporal constraints such as precedence, fixed start times, and fixed end times.
+
+- **Resource Constraints**: Manage resource availability and allocation.
+
+- **Logical Operations**: Employ first-order logic operations to define relationships between tasks and resource constraints, including and/or/xor/not boolean operators, implications, if/then/else conditions.
+
+- **Buffers**: discrete quantities buffers, with upper and lower bounds
+
+- **Indicators**: measure and compare schedule solutions (makespan, weighted completion time, resource utilization, etc.)
+
+- **Multi-Objective Optimization**: Optimize schedules across multiple objectives.
+
+- **Gantt Chart Visualization**: Visualize schedules effortlessly with Gantt chart rendering, compatible with both matplotlib and plotly libraries.
+
+- **Export Capabilities**: Seamlessly export solutions to JSON, SMTLIB, CSV formats and Excel spreadsheets.

docs/img/versatility.svg

@@ -1,4 +1,4 @@
-# ProcessScheduler
+# ProcessScheduler - A python framework for scheduling and resoure allocation
 
 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/7221205f866145bfa4f18c08bd96e71f)](https://www.codacy.com/gh/tpaviot/ProcessScheduler/dashboard?utm_source=github.com&utm_medium=referral&utm_content=tpaviot/ProcessScheduler&utm_campaign=Badge_Grade)
 [![codecov](https://codecov.io/gh/tpaviot/ProcessScheduler/branch/master/graph/badge.svg?token=9HI1FPJUDL)](https://codecov.io/gh/tpaviot/ProcessScheduler)
@@ -7,24 +7,32 @@
 [![PyPI version](https://badge.fury.io/py/ProcessScheduler.svg)](https://badge.fury.io/py/ProcessScheduler)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4480745.svg)](https://doi.org/10.5281/zenodo.4480745)
 
-ProcessScheduler is a versatile Python package designed for creating optimized scheduling in various industrial domains, including manufacturing, construction, healthcare, and more. This tool, aimed at project managers, business organization consultants, or industrial logistics experts, focuses on optimizing time or cost objectives. It offers a robust set of classes and methods to model a wide range of use cases with rich semantics, making it ideal for tackling intricate scheduling challenges. The package simplifies complex mathematical calculations necessary for problem resolution, thereby allowing users to concentrate on problem modeling rather than the computational intricacies, streamlining operations and offering solutions for scenarios that defy straightforward resolutions.
 
-Within this toolkit, you'll find a rich array of features, including:
+## What is it intended for?
 
-- **Task Definition**: Define tasks with zero, fixed, or variable durations, along with work_amount specifications.
+ProcessScheduler is a versatile Python package designed for creating optimized scheduling in various industrial domains, including manufacturing, construction, healthcare, and more.
 
-- **Resource Management**: Create and manage resources, complete with productivity and cost attributes. Efficiently assign resources to tasks.
+## Who is it intended to?
 
-- **Temporal Task Constraints**: Handle task temporal constraints such as precedence, fixed start times, and fixed end times.
+Project managers, business organization consultants, industrial logistics experts, teachers and students.
 
-- **Resource Constraints**: Manage resource availability and allocation.
+## Core Features: Versatility and Dependability
 
-- **Logical Operations**: Employ first-order logic operations to define relationships between tasks and resource constraints, including and/or/xor/not boolean operators, implications, if/then/else conditions.
+**Versatility**: At its core, ProcessScheduler acts as a bridge between specific business requirements and their mathematical representations. It leverages a collection of versatile, business-focused generic classes to represent a broad spectrum of scheduling challenges, effectively translating them into solvable mathematical models.
 
-- **Multi-Objective Optimization**: Optimize schedules across multiple objectives.
+![svg](img/versatility.svg)
 
-- **Gantt Chart Visualization**: Visualize schedules effortlessly with Gantt chart rendering, compatible with both matplotlib and plotly libraries.
+**Dependability**: The reliability of ProcessScheduler is fortified through several key aspects:
 
-- **Export Capabilities**: Seamlessly export solutions to JSON format and SMT problems to SMTLIB format.
+- Utilization of the renowned Pydantic Python package for class construction, ensuring robust data validation and settings management.
 
-This comprehensive guide will walk you through the process of model creation, solver execution, and solution analysis, making it a valuable resource for harnessing the full potential of ProcessScheduler.
+- A comprehensive suite of unit tests, with the test code volume surpassing the core code by 1.5 times, exemplifying thorough testing protocols.
+
+- High code quality, ranked 'A' rank on Codacy, an automated code review service.
+
+- Almost total code coverage, reaching over 99%, demonstrating the thoroughness of testing and reliability.
+
+- Continuous integration via Microsoft Azure, ensuring consistent and reliable updates and maintenance.
+
+## Prerequisites
+No need to be an expert. To effectively utilize ProcessScheduler, users are expected to have a moderate level of proficiency in both Python programming and the fundamentals of scheduling algorithms.

docs/index.md

@@ -2,7 +2,7 @@
 title: About
 ---
 
-# About
+# What's inside?
 
 ProcessScheduler operates on models written in the Python programming language, offering the flexibility to accommodate a wide range of scheduling requirements for tasks and resources.
 
@@ -12,6 +12,6 @@ Bjørner, N., Phan, AD., Fleckenstein, L. (2015). νZ - An Optimizing SMT Solver
 
 Additionally, an introductory guide to programming with Z3 in Python is available at [z3-py-tutorial](https://ericpony.github.io/z3py-tutorial/guide-examples.htm). 
 
-It's worth noting that Z3 is the **only mandatory dependency** for ProcessScheduler.
+It's worth noting that Z3 and pydantic are the **only mandatory dependencies** for ProcessScheduler.
 
 Furthermore, the tool offers the flexibility to visualize scheduling solutions by rendering them into Gantt charts, which can be exported in common formats such as JPG, PNG, PDF, or SVG. Please note that the optional libraries, matplotlib and plotly, are not pre-installed but can be easily integrated based on your preferences and needs.

docs/about.md renamed to docs/inside.md

@@ -1 +1,36 @@
 # Run
+
+In order to check that the installation is successful and processscheduler ready to run on your machine, edit/run the following example:
+
+```python
+import processscheduler as ps 
+
+pb = ps.SchedulingProblem(name="Test", horizon=10)
+
+T1 = ps.FixedDurationTask(name="T1", duration=6)
+T2 = ps.FixedDurationTask(name="T2", duration=4)
+
+W1 = ps.Worker(name="W1")
+
+T1.add_required_resource(W1)
+T2.add_required_resource(W1)
+
+solver = ps.SchedulingSolver(problem=pb)
+
+solution = solver.solve()
+print(solution)
+```
+
+If pandas is installed, you should get the following output:
+
+```bash
+Solver type:
+===========
+        -> Standard SAT/SMT solver
+Total computation time:
+=====================
+        Test satisfiability checked in 0.00s
+  Task name Allocated Resources  Start  End  Duration  Scheduled  Tardy
+0        T1                [W1]      0    6         6       True  False
+1        T2                [W1]      6   10         4       True  False
+```

docs/run.md

@@ -15,16 +15,16 @@ graph TD
 
 1. Create a **[SchedulingProblem](scheduling_problem.md)**: This is the foundational step where you establish the SchedulingProblem, serving as the primary container for all components of your scheduling scenario.
 
-2. Create Objects Representing The Problem: Select appropriate **Task** and **Resource** objects to accurately represent the elements of your use case. This step involves defining the tasks to be scheduled and the resources available for these tasks.
+2. Create **Objects Representing The Problem**: Select appropriate **Task** and **Resource** objects to accurately represent the elements of your use case. This step involves defining the tasks to be scheduled and the resources available for these tasks.
 
 3. Apply **Constraints** to the Schedule: Introduce temporal or logical constraints to define how tasks should be ordered or how resources are to be utilized. Constraints are critical for reflecting real-world limitations and requirements in your schedule.
 
-4. Add **Indicators**: indicators or metrics are added to the scheduling problem. These indicators might include key performance metrics, resource utilization rates, or other measurable factors that are crucial for analyzing the effectiveness of the schedule. By adding this step, the schedule can be more effectively monitored and evaluated.
+4. Add **Indicators** (optional): indicators or metrics are added to the scheduling problem. These indicators might include key performance metrics, resource utilization rates, or other measurable factors that are crucial for analyzing the effectiveness of the schedule. By adding this step, the schedule can be more effectively monitored and evaluated.
 
-5. Define **Objectives**: Optionally, you can specify one or more objectives. Objectives, built on Indicators, are used to determine what constitutes an 'optimal' schedule within the confines of your constraints. This could include minimizing total time, cost, or other metrics relevant to your scenario.
+5. Define **Objectives** (optional): you can specify one or more objectives. Objectives, built on Indicators, are used to determine what constitutes an 'optimal' schedule within the confines of your constraints. This could include minimizing total time, cost, or other metrics relevant to your scenario.
 
 5. **Execute the Solver**: Run the solver to find a feasible (and possibly optimal, depending on defined objectives) schedule based on your tasks, resources, constraints, and objectives.
 
 6. **Analyze** the Results: Once the solver has found a solution, you can render the schedule in various formats such as a Gantt chart or export it to Excel. This step is crucial for evaluating the effectiveness of the proposed schedule. Based on the analysis, you might revisit the representation stage to adjust your problem model, refine constraints, or alter objectives.
 
-This workflow provides a structured approach to building and solving scheduling problems using the ProcessScheduler library, ensuring that all essential aspects of your scheduling scenario are methodically addressed.
+This workflow provides a structured approach to building and solving scheduling problems, ensuring that all essential aspects of your scheduling scenario are methodically addressed.

docs/workflow.md

@@ -5,8 +5,7 @@ dependencies:
   - pip
   - python=3.10
   - pip:
-    - z3-solver==4.12.2.0
-    - importlib-resources
+    - z3-solver==4.12.5.0
     - matplotlib
     - plotly
     - kaleido

environment.yml

@@ -62,7 +62,8 @@ watch:
 
 nav:
 - Introduction:
-  - About: about.md
+  - Features: features.md
+  - What's inside: inside.md
   - Download/Install: download_install.md
   - Run: run.md
 - Concepts:

mkdocs.yml

@@ -1,5 +1,4 @@
-z3-solver==4.12.2.0
-importlib-resources
+z3-solver==4.12.5.0
 setuptools
 rich
 pydantic