feat(phase1): implement all Phase 1 polymer architectures (#90)

* feat(core): implement Phase 1 polymer architectures (US-1.1.1 → US-1.4.2)

## Nouveaux builders

### LinearBuilder (linear.rs)
- US-1.1.1: `random_copolymer(&[f64])` — copolymère statistique avec seed
- US-1.1.2: `alternating_copolymer()` — séquence A-B-A-B cyclique
- US-1.1.3: `block_copolymer(&[usize])` — diblock/triblock/multiblock
- US-1.1.4: `gradient_copolymer(&GradientProfile)` — gradient linéaire ou sigmoïde
- US-1.2.5: `cyclic_homopolymer()` — ring closure premier↔dernier atome
- US-1.3.3: `with_end_groups()` — préfixe/suffixe BigSMILES inclus dans SMILES + Mn

### BranchedBuilder (branched.rs)
- US-1.2.1: `comb_polymer(branch_every)` — peigne régulier backbone+branch
- US-1.2.2: `graft_copolymer(graft_fraction, seed)` — greffage aléatoire reproductible
- US-1.2.3: `star_polymer(arms)` — étoile 3–12 bras
- US-1.2.4: `dendrimer(generation, branching_factor)` — dendrimère G1–G6

### EnsembleBuilder (ensemble.rs)
- `random_copolymer_ensemble`, `alternating_copolymer_ensemble`,
  `block_copolymer_ensemble`, `gradient_copolymer_ensemble`

## PolymerChain enrichi (US-1.3.1, US-1.3.2)
- Nouveau champ `composition: Vec<MonomerUnit>` (fraction molaire par unité)
- Nouveau champ `architecture: Architecture` (Linear/Star/Comb/Dendrimer/Cyclic/Gradient/Graft)
- API builder fluent: `.with_composition()` et `.with_architecture()`

## CLI (US-1.4.1, US-1.4.2)
- `polysim analyze` : `--arch random|alternating|block|gradient`
- `polysim generate` : idem + `--gradient-profile linear|sigmoid`,
  `--gradient-f-start`, `--gradient-f-end`

## Tests: 35 nouveaux tests (tous verts)
- `tests/copolymer.rs` : 17 tests random/alternating/block + ensembles
- `tests/branched.rs` : 9 tests comb/graft/star/dendrimer
- `tests/gradient_cyclic.rs` : 9 tests gradient/cyclic/end-groups

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: add roadmap

* test(core): add cyclic regression test for two-letter atoms (Cl)

Vérifie que make_cyclic_smiles ne corrompt pas les atomes bi-lettres
comme Cl lors de l'insertion du ring closure.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Peariforme

ROADMAP.md

@@ -11,21 +11,45 @@ use polysim_core::{
 
 use crate::display;
 use crate::report::AnalysisResult;
-use crate::StrategyArgs;
+use crate::{Architecture, ArchitectureArgs, StrategyArgs};
 
 /// Entry point for the `analyze` subcommand.
-pub fn run(bigsmiles_str: &str, args: &StrategyArgs) -> Result<(), i32> {
+pub fn run(
+    bigsmiles_str: &str,
+    args: &StrategyArgs,
+    arch_args: &ArchitectureArgs,
+) -> Result<(), i32> {
     let bigsmiles = parse(bigsmiles_str).map_err(report_err)?;
 
-    let chain = LinearBuilder::new(bigsmiles.clone(), args.build_strategy())
-        .homopolymer()
-        .map_err(report_err)?;
+    let mut builder = LinearBuilder::new(bigsmiles.clone(), args.build_strategy());
+    if let Some(seed) = arch_args.copolymer_seed {
+        builder = builder.seed(seed);
+    }
+
+    let chain = match arch_args.arch {
+        Architecture::Homo => builder.homopolymer(),
+        Architecture::Random => {
+            let fractions = arch_args.fractions.as_deref().unwrap_or(&[]);
+            builder.random_copolymer(fractions)
+        }
+        Architecture::Alternating => builder.alternating_copolymer(),
+        Architecture::Block => {
+            let lengths = arch_args.block_lengths.as_deref().unwrap_or(&[]);
+            builder.block_copolymer(lengths)
+        }
+        Architecture::Gradient => {
+            let profile = arch_args.gradient_profile();
+            builder.gradient_copolymer(&profile)
+        }
+    }
+    .map_err(report_err)?;
 
     let mono_mass = monoisotopic_mass(&chain);
 
     let result = AnalysisResult {
         bigsmiles_str: bigsmiles_str.to_owned(),
         strategy_label: args.label(),
+        architecture_label: arch_args.arch.label().to_owned(),
         begin_block: segments_to_smiles(bigsmiles.prefix_segments()),
         end_block: segments_to_smiles(bigsmiles.suffix_segments()),
         smiles: chain.smiles.clone(),

crates/polysim-cli/src/commands/analyze.rs

@@ -9,7 +9,7 @@ use polysim_core::{
 };
 
 use crate::display;
-use crate::DistributionKind;
+use crate::{Architecture, ArchitectureArgs, DistributionKind};
 
 /// Entry point for the `generate` subcommand.
 pub fn run(
@@ -19,6 +19,7 @@ pub fn run(
     distribution: &DistributionKind,
     num_chains: usize,
     seed: Option<u64>,
+    arch_args: &ArchitectureArgs,
 ) -> Result<(), i32> {
     let bs = parse(bigsmiles_str).map_err(report_err)?;
 
@@ -36,11 +37,18 @@ pub fn run(
         eprintln!();
     }
 
-    let ensemble =
-        build_ensemble(distribution, bs, mn, pdi, num_chains, seed).map_err(report_err)?;
+    let ensemble = build_ensemble(distribution, bs, mn, pdi, num_chains, seed, arch_args)
+        .map_err(report_err)?;
 
     let stats = EnsembleStats::from_ensemble(&ensemble);
-    display::print_ensemble_report(bigsmiles_str, distribution, mn, pdi, &stats);
+    display::print_ensemble_report(
+        bigsmiles_str,
+        distribution,
+        &arch_args.arch,
+        mn,
+        pdi,
+        &stats,
+    );
     Ok(())
 }
 
@@ -51,11 +59,12 @@ fn build_ensemble(
     pdi: f64,
     num_chains: usize,
     seed: Option<u64>,
+    arch_args: &ArchitectureArgs,
 ) -> Result<PolymerEnsemble, PolySimError> {
     match distribution {
-        DistributionKind::Flory => build(Flory, bs, mn, pdi, num_chains, seed),
-        DistributionKind::LogNormal => build(LogNormal, bs, mn, pdi, num_chains, seed),
-        DistributionKind::SchulzZimm => build(SchulzZimm, bs, mn, pdi, num_chains, seed),
+        DistributionKind::Flory => build(Flory, bs, mn, pdi, num_chains, seed, arch_args),
+        DistributionKind::LogNormal => build(LogNormal, bs, mn, pdi, num_chains, seed, arch_args),
+        DistributionKind::SchulzZimm => build(SchulzZimm, bs, mn, pdi, num_chains, seed, arch_args),
     }
 }
 
@@ -66,12 +75,29 @@ fn build<D: ChainLengthDistribution>(
     pdi: f64,
     num_chains: usize,
     seed: Option<u64>,
+    arch_args: &ArchitectureArgs,
 ) -> Result<PolymerEnsemble, PolySimError> {
     let mut builder = EnsembleBuilder::new(bs, dist, mn, pdi).num_chains(num_chains);
     if let Some(s) = seed {
         builder = builder.seed(s);
     }
-    builder.homopolymer_ensemble()
+
+    match arch_args.arch {
+        Architecture::Homo => builder.homopolymer_ensemble(),
+        Architecture::Random => {
+            let fractions = arch_args.fractions.as_deref().unwrap_or(&[]);
+            builder.random_copolymer_ensemble(fractions)
+        }
+        Architecture::Alternating => builder.alternating_copolymer_ensemble(),
+        Architecture::Block => {
+            let ratios = arch_args.block_ratios.as_deref().unwrap_or(&[]);
+            builder.block_copolymer_ensemble(ratios)
+        }
+        Architecture::Gradient => {
+            let profile = arch_args.gradient_profile();
+            builder.gradient_copolymer_ensemble(&profile)
+        }
+    }
 }
 
 fn report_err(e: impl std::fmt::Display) -> i32 {

crates/polysim-cli/src/commands/generate.rs

@@ -26,6 +26,7 @@ fn print_banner() {
 
 fn print_summary(r: &AnalysisResult) {
     println!("  {:<11}{}", "BigSMILES".bold(), r.bigsmiles_str.yellow());
+    println!("  {:<11}{}", "Arch".bold(), r.architecture_label.cyan());
     println!("  {:<11}{}", "Strategy".bold(), r.strategy_label);
     if let Some(ref bb) = r.begin_block {
         println!("  {:<11}{}", "Begin".bold(), bb.yellow());
@@ -131,19 +132,27 @@ fn add_mono_rows(table: &mut Table, r: &AnalysisResult) {
 
 // ═══ Ensemble report ═════════════════════════════════════════════════════════
 
-use crate::DistributionKind;
+use crate::{Architecture, DistributionKind};
 use polysim_core::properties::ensemble::EnsembleStats;
 
 /// Prints the ensemble generation report to stdout.
 pub fn print_ensemble_report(
     bigsmiles_str: &str,
     distribution: &DistributionKind,
+    architecture: &Architecture,
     target_mn: f64,
     target_pdi: f64,
     stats: &EnsembleStats,
 ) {
     print_ensemble_banner();
-    print_ensemble_summary(bigsmiles_str, distribution, target_mn, target_pdi, stats);
+    print_ensemble_summary(
+        bigsmiles_str,
+        distribution,
+        architecture,
+        target_mn,
+        target_pdi,
+        stats,
+    );
     print_ensemble_table(stats, target_mn, target_pdi);
     println!();
 }
@@ -161,11 +170,13 @@ fn print_ensemble_banner() {
 fn print_ensemble_summary(
     bigsmiles_str: &str,
     distribution: &DistributionKind,
+    architecture: &Architecture,
     target_mn: f64,
     target_pdi: f64,
     stats: &EnsembleStats,
 ) {
     println!("  {:<15}{}", "BigSMILES".bold(), bigsmiles_str.yellow());
+    println!("  {:<15}{}", "Arch".bold(), architecture.label().cyan());
     println!(
         "  {:<15}{}",
         "Distribution".bold(),

crates/polysim-cli/src/display.rs

@@ -28,13 +28,13 @@ enum Commands {
     /// Mn, Mw, dispersity, molecular formula, monoisotopic mass, and atom count.
     Analyze {
         /// BigSMILES string, e.g. "{[]CC[]}" for polyethylene.
-        ///
-        /// The stochastic object {…} must contain exactly one repeat unit
-        /// (homopolymer). Copolymers will be supported in a future release.
         bigsmiles: String,
 
         #[command(flatten)]
         strategy: StrategyArgs,
+
+        #[command(flatten)]
+        arch: ArchitectureArgs,
     },
 
     /// Generate a polydisperse ensemble of polymer chains.
@@ -64,6 +64,9 @@ enum Commands {
         /// Random seed for reproducible results.
         #[arg(long)]
         seed: Option<u64>,
+
+        #[command(flatten)]
+        arch: ArchitectureArgs,
     },
 }
 
@@ -108,6 +111,94 @@ impl StrategyArgs {
     }
 }
 
+/// Polymer architecture and copolymer parameters.
+#[derive(Args)]
+pub(crate) struct ArchitectureArgs {
+    /// Polymer architecture.
+    #[arg(
+        long,
+        value_enum,
+        default_value = "homo",
+        help_heading = "Architecture"
+    )]
+    pub(crate) arch: Architecture,
+
+    /// Weight fractions for random copolymer (comma-separated, e.g. "0.6,0.4").
+    #[arg(long, value_delimiter = ',', help_heading = "Architecture")]
+    pub(crate) fractions: Option<Vec<f64>>,
+
+    /// Block lengths for block copolymer analysis (comma-separated, e.g. "50,30").
+    #[arg(long, value_delimiter = ',', help_heading = "Architecture")]
+    pub(crate) block_lengths: Option<Vec<usize>>,
+
+    /// Block ratios for block copolymer ensemble (comma-separated, e.g. "0.5,0.5").
+    #[arg(long, value_delimiter = ',', help_heading = "Architecture")]
+    pub(crate) block_ratios: Option<Vec<f64>>,
+
+    /// Random seed for reproducible random/gradient copolymers.
+    #[arg(long, help_heading = "Architecture")]
+    pub(crate) copolymer_seed: Option<u64>,
+
+    /// Gradient profile shape (for --arch gradient).
+    #[arg(
+        long,
+        value_enum,
+        default_value = "linear",
+        help_heading = "Architecture"
+    )]
+    pub(crate) gradient_profile: GradientProfileKind,
+
+    /// Starting fraction of monomer A (for --arch gradient).
+    #[arg(long, default_value = "1.0", help_heading = "Architecture")]
+    pub(crate) gradient_f_start: f64,
+
+    /// Ending fraction of monomer A (for --arch gradient).
+    #[arg(long, default_value = "0.0", help_heading = "Architecture")]
+    pub(crate) gradient_f_end: f64,
+}
+
+impl ArchitectureArgs {
+    pub(crate) fn gradient_profile(&self) -> polysim_core::GradientProfile {
+        match self.gradient_profile {
+            GradientProfileKind::Linear => polysim_core::GradientProfile::Linear {
+                f_start: self.gradient_f_start,
+                f_end: self.gradient_f_end,
+            },
+            GradientProfileKind::Sigmoid => polysim_core::GradientProfile::Sigmoid {
+                f_start: self.gradient_f_start,
+                f_end: self.gradient_f_end,
+            },
+        }
+    }
+}
+
+#[derive(Clone, ValueEnum)]
+pub(crate) enum GradientProfileKind {
+    Linear,
+    Sigmoid,
+}
+
+#[derive(Clone, ValueEnum)]
+pub(crate) enum Architecture {
+    Homo,
+    Random,
+    Alternating,
+    Block,
+    Gradient,
+}
+
+impl Architecture {
+    pub(crate) fn label(&self) -> &'static str {
+        match self {
+            Self::Homo => "Homopolymer",
+            Self::Random => "Random copolymer",
+            Self::Alternating => "Alternating copolymer",
+            Self::Block => "Block copolymer",
+            Self::Gradient => "Gradient copolymer",
+        }
+    }
+}
+
 #[derive(Clone, ValueEnum)]
 pub(crate) enum DistributionKind {
     Flory,
@@ -131,8 +222,9 @@ fn main() {
         Commands::Analyze {
             bigsmiles,
             strategy,
+            arch,
         } => {
-            if let Err(code) = commands::analyze::run(&bigsmiles, &strategy) {
+            if let Err(code) = commands::analyze::run(&bigsmiles, &strategy, &arch) {
                 std::process::exit(code);
             }
         }
@@ -143,9 +235,10 @@ fn main() {
             distribution,
             num_chains,
             seed,
+            arch,
         } => {
             if let Err(code) =
-                commands::generate::run(&bigsmiles, mn, pdi, &distribution, num_chains, seed)
+                commands::generate::run(&bigsmiles, mn, pdi, &distribution, num_chains, seed, &arch)
             {
                 std::process::exit(code);
             }

crates/polysim-cli/src/main.rs

@@ -2,6 +2,7 @@
 pub struct AnalysisResult {
     pub bigsmiles_str: String,
     pub strategy_label: String,
+    pub architecture_label: String,
     pub begin_block: Option<String>,
     pub end_block: Option<String>,
     pub smiles: String,