argumentation_bipolar/
lib.rs

1//! # argumentation-bipolar
2//!
3//! Bipolar argumentation frameworks (Cayrol & Lagasquie-Schiex 2005,
4//! Amgoud et al. 2008, Nouioua & Risch 2011) built on top of the
5//! [`argumentation`] crate's Dung semantics.
6//!
7//! A bipolar framework extends Dung's abstract argumentation with a
8//! second directed edge relation: **support**. Arguments can attack and
9//! support one another. This crate implements *necessary support*
10//! semantics: `A` supports `B` means `A` must be accepted for `B` to be
11//! acceptable.
12//!
13//! ## Quick example
14//!
15//! ```
16//! use argumentation_bipolar::framework::BipolarFramework;
17//! use argumentation_bipolar::coalition::detect_coalitions;
18//! use argumentation_bipolar::semantics::bipolar_preferred_extensions;
19//!
20//! let mut bf = BipolarFramework::new();
21//! bf.add_support("alice", "bob").unwrap();
22//! bf.add_support("bob", "alice").unwrap();
23//! bf.add_attack("alice", "charlie");
24//! bf.add_attack("bob", "charlie");
25//!
26//! let coalitions = detect_coalitions(&bf);
27//! assert!(coalitions.iter().any(|c| c.members.len() == 2));
28//!
29//! let prefs = bipolar_preferred_extensions(&bf).unwrap();
30//! for ext in &prefs {
31//!     assert!(!ext.contains(&"charlie"));
32//! }
33//! ```
34//!
35//! ## Semantics pipeline
36//!
37//! 1. [`derived::closed_attacks`] computes the set of all attacks under
38//!    the closed attack relation (direct + supported + secondary +
39//!    mediated) per C&LS 2005 §3.
40//! 2. [`flatten::flatten`] produces an equivalent
41//!    [`argumentation::ArgumentationFramework`] whose attack edges are
42//!    the closure.
43//! 3. [`semantics::bipolar_preferred_extensions`] runs the core crate's
44//!    Dung preferred semantics on the flattened framework, then filters
45//!    extensions that are not *support-closed* (every accepted argument
46//!    must have all its necessary supporters in the extension too).
47//! 4. [`coalition::detect_coalitions`] runs Tarjan SCC on the support
48//!    graph to find mutually-supporting groups.
49//!
50//! ## References
51//!
52//! - Cayrol, C. & Lagasquie-Schiex, M.-C. (2005). *On the acceptability
53//!   of arguments in bipolar argumentation frameworks.* ECSQARU / IJAR
54//!   23(4).
55//! - Amgoud, L., Cayrol, C., Lagasquie-Schiex, M.-C., & Livet, P.
56//!   (2008). *On bipolarity in argumentation frameworks.* IJIS 23(10).
57//! - Nouioua, F. & Risch, V. (2011). *Bipolar argumentation frameworks
58//!   with specialized supports.* ICTAI 2011.
59//! - Cohen, A. et al. (2014). *A survey of different approaches to
60//!   support in argumentation systems.* KER 29(5).
61
62#![deny(missing_docs)]
63#![warn(clippy::all)]
64
65pub mod coalition;
66pub mod derived;
67pub mod error;
68pub mod flatten;
69pub mod framework;
70pub mod queries;
71pub mod semantics;
72pub mod types;
73
74pub use coalition::{Coalition, detect_coalitions};
75pub use error::Error;
76pub use framework::BipolarFramework;
77pub use semantics::{
78    bipolar_complete_extensions, bipolar_grounded_extension, bipolar_preferred_extensions,
79    bipolar_stable_extensions, is_support_closed,
80};
81pub use types::{CoalitionId, EdgeKind};
argumentation_bipolar/lib.rs

argumentation_bipolar/
lib.rs
