From 4ada0daba7e5b429d705f09c9ca106d8c2dade7e Mon Sep 17 00:00:00 2001 From: Yehor Boiar Date: Mon, 7 Oct 2024 13:28:24 +0100 Subject: [PATCH] Added RuleSet docstring --- crates/conjure_core/src/ast/variables.rs | 9 ++-- .../conjure_core/src/rule_engine/rewrite.rs | 52 ++++++------------- .../conjure_core/src/rule_engine/rule_set.rs | 20 ++++++- 3 files changed, 39 insertions(+), 42 deletions(-) diff --git a/crates/conjure_core/src/ast/variables.rs b/crates/conjure_core/src/ast/variables.rs index e86846609e..405f48f900 100644 --- a/crates/conjure_core/src/ast/variables.rs +++ b/crates/conjure_core/src/ast/variables.rs @@ -17,7 +17,7 @@ use crate::ast::domains::{Domain, Range}; /// (IntDomain) or a boolean domain (BoolDomain). /// /// # Example -/// +/// /// use crate::ast::domains::{DecisionVariable, Domain, Range}; /// /// let bool_var = DecisionVariable::new(Domain::BoolDomain); @@ -25,11 +25,8 @@ use crate::ast::domains::{Domain, Range}; /// /// println!("Boolean Variable: {}", bool_var); /// println!("Integer Variable: {}", int_var); -<<<<<<< HEAD -/// -======= -pub struct DecisionVariable { -} + +pub struct DecisionVariable {} impl DecisionVariable { pub fn new(domain: Domain) -> DecisionVariable { diff --git a/crates/conjure_core/src/rule_engine/rewrite.rs b/crates/conjure_core/src/rule_engine/rewrite.rs index 6c97b7446a..578f2c244f 100644 --- a/crates/conjure_core/src/rule_engine/rewrite.rs +++ b/crates/conjure_core/src/rule_engine/rewrite.rs @@ -87,34 +87,16 @@ fn optimizations_enabled() -> bool { /// - Using `rewrite_model` with the Expression `a + min(x, y)` /// /// Initial expression: a + min(x, y) -/// let initial_constraints = Expression::new(Sum(Metadata, Vec d if d <= x and d<=y "), -/// Rule::new("a + 0 => a"), -/// ]); -/// -/// let rule_set_2 = RuleSet::new(vec![ -/// Rule::new("x * 1 => x"), -/// ]); -/// -/// Apply the rewriting model -/// let optimized_model = rewrite_model(&model, &vec![&rule_set_1, &rule_set_2])?; -/// -/// //Inside rewrite_model -/// //After getting the rules by their priorities and getting additional statistics the while loop of single interations -/// //is executed -/// while let Some(step) = None // the loop is exited only when no more rules can be applied, when rewrite_iteration returns None +/// A model containing the expression is created. The variables of the model are represented by a SymbolTable and contain a,x,y. +/// The contraints of the initail model is the expression itself. +/// +/// After getting the rules by their priorities and getting additional statistics the while loop of single interations is executed. +/// Function +/// The loop is exited only when no more rules can be applied, when rewrite_iteration returns None and [`while let Some(step) = None`] occurs /// -/// //will result is side effects ((d<=x ^ d<=y) being the new_top and the model will now be a conjuction of that and (a+d) -/// step.(&mut new_model) +/// Will result in side effects ((d<=x ^ d<=y) being the [`new_top`] and the model will now be a conjuction of that and (a+d) /// -/// //Rewritten expression: ((a + d) ^ (d<=x ^ d<=y))/ +/// Rewritten expression: ((a + d) ^ (d<=x ^ d<=y)) /// /// # Performance Considerations /// - The function checks if optimizations are enabled before applying rules, which may affect the performance @@ -193,29 +175,29 @@ pub fn rewrite_model<'a>( /// /// # Example of rewtire iteration for the expression `a + min(x, y)` /// -/// //Initially +/// Initially /// if apply_optimizations && expression.is_clean() //is not true yet since intially our expression is dirty /// /// rule_results = null //apply_results returns a null vector since no rules can be applied at the top level /// let mut sub = expression.children(); // sub = [a, min(x, y)] - vector of subexpressions /// -/// //the function iterates through the vector of the children of the top expression and calls itself +/// the function iterates through the vector of the children of the top expression and calls itself /// -/// //rewrite_iteration on a returns None, but on min(x, y) returns a Reduction object red. In this case, Rule 1 (min simplification) might apply: -/// //d is added to the SymbolTable and the variables field is updated in the model. new_top is the side effects: (d<=x ^ d<=y) +/// rewrite_iteration on a returns None, but on min(x, y) returns a Reduction object red. In this case, Rule 1 (min simplification) might apply: +/// d is added to the SymbolTable and the variables field is updated in the model. new_top is the side effects: (d<=x ^ d<=y) /// let red = Reduction::new(new_expression = d, new_top, symbols); -/// sub[1] = red.new_expression; // Update `min(x, y)` to `d` +/// sub[1] = red.new_expression - Updates `min(x, y)` to `d` /// -/// //Since a child expression (min(x, y)) was rewritten to x, the parent expression (a + min(x, y)) is updated with the new child: +/// Since a child expression (min(x, y)) was rewritten to x, the parent expression (a + min(x, y)) is updated with the new child: /// let res = expression.with_children(sub.clone()); // res = `a + d` /// return Some(Reduction::new(res, red.new_top, red.symbols)); // `a + d`, /// -/// //the condition in the while loop in rewrite_model is met -> side effects are applied +/// the condition in the while loop in rewrite_model is met -> side effects are applied /// -/// //no more rules in our example can apply to the modified model -> mark all the children as clean and return a pure reduction +/// no more rules in our example can apply to the modified model -> mark all the children as clean and return a pure reduction /// return Some(Reduction::pure(expression)); /// -/// //on the last execution of rewrite_iteration +/// on the last execution of rewrite_iteration /// if apply_optimizations && expression.is_clean() { /// return None; //the while loop is rewrite_model is exited /// diff --git a/crates/conjure_core/src/rule_engine/rule_set.rs b/crates/conjure_core/src/rule_engine/rule_set.rs index 146e2218bd..f290abdacc 100644 --- a/crates/conjure_core/src/rule_engine/rule_set.rs +++ b/crates/conjure_core/src/rule_engine/rule_set.rs @@ -8,7 +8,25 @@ use log::warn; use crate::rule_engine::{get_rule_set_by_name, get_rules, Rule}; use crate::solver::SolverFamily; -/// A set of rules with a name, priority, and dependencies. +/// A structure representing a set of rules with a name, priority, and dependencies. +/// +/// `RuleSet` is a way to group related rules together under a single name. +/// You can think of it like a list of rules that belong to the same category. +/// Each `RuleSet` can also have a number that tells it what order it should run in compared to other `RuleSet` instances. +/// Additionally, a `RuleSet` can depend on other `RuleSet` instances, meaning it needs them to run first. +/// +/// To make things efficient, `RuleSet` only figures out its rules and dependencies the first time they're needed, +/// and then it remembers them so it doesn't have to do the work again. +/// +/// # Fields +/// - `name`: The name of the rule set. +/// - `order`: A number that decides the order in which this `RuleSet` should be applied. +/// If two `RuleSet` instances have the same rule but with different priorities, +/// the one with the higher `order` number will be the one that is used. +/// - `rules`: A lazily initialized map of rules to their priorities. +/// - `dependency_rs_names`: The names of the rule sets that this rule set depends on. +/// - `dependencies`: A lazily initialized set of `RuleSet` dependencies. +/// - `solver_families`: The solver families that this rule set applies to. #[derive(Clone, Debug)] pub struct RuleSet<'a> { /// The name of the rule set.