Restructure datablocks, unify factory system, and standardize switchable-category API (#128)

* Refactor validation imports and remove unused DataTypes references

* Refactor value specification to use 'data_type' instead of 'type_' in AttributeSpec

* Refactor content_validator to validator in AttributeSpec

* Refactor Cell class constructor to use default parameters and simplify attribute setting

* Refactor AtomSite and SpaceGroup initializers to remove parameters and improve clarity

* Refactor constructors in multiple classes to remove parameters and use property setters

* Refactor add method to accept only keyword arguments for improved clarity

* Refactor initialization of descriptors in multiple classes for consistency

* Remove value initialization from validation class constructor

* Refactor parameter value specification to remove DataTypes dependency

* Refactor parameter initialization and property methods in mixin files

* Refactor: streamline CIF handler initialization and add public property comments

* Refactor ExperimentType initialization to use property setters

* Refactor ExperimentType initialization to use property setters

* Add temporary test script

* Initialize parent class in guard.py constructor

* Refactor peak-profile mixins to remove unused broadening and asymmetry methods

* Refactor broadening parameter comments and remove unused initializations in TofPeak

* Refactor parameter definitions to streamline unit assignments in various modules

* Refactor CIF handler initialization for clarity and consistency

* Refactor constructors in PdDataPoint mixins to remove kwargs

* Refactor parameters module to variable module; update imports across multiple files

* Refactor import statements for consistency and clarity

* Refactor sample models to structures in project and related files

* Refactor terminology from "sample" to "structure" in documentation and code comments

* More refactoring from sample models to structures

* Refactor factory methods, etc.

* Refactor method names from `add_from_scratch` to `create` for consistency across collections

* Rebuild classes structure

* Refactor validation module by removing unused type checking decorator

* Refactor PeakProfileTypeEnum to consider auto-extraction of peak profile info

* Add revised design for all factories

* Improve revised design for all factories

* Add copilot instructions for EasyDiffraction project

* Update all init files

* Refactor metadata handling

* Refactor type hints for optional parameters in collection.py

* Add per-file ignores for __init__.py in Ruff configuration

* Add TOF instrument and peak profile classes with compatibility and calculator support

* Clarify usage of keyword arguments in copilot instructions

* Add metadata dataclasses for factory-created classes

* Refactor setter methods for improved readability and consistency

* Refactor formatting of beam_mode and calculators in Chebyshev class

* Update copilot instructions to clarify beta project guidelines

* Update copilot instructions to clarify refactoring guidelines

* Add architecture documentation for EasyDiffraction library

* Refactor calculator management for joint and sequential fitting in experiments

* Refactor code blocks in architecture.md to specify shell syntax highlighting

* Document current and potential architectural issues in the codebase

* Document current and potential issues in architecture

* Document limitations of `FactoryBase` regarding constructor-variant registrations

* Refactor calculator and minimizer factory methods for consistency and clarity

* Refactor architecture documentation for improved clarity and consistency

* Refactor logging and docstring formatting in analysis and factory modules

* Refactor calculator and minimizer factory to use tag strings; update tests accordingly

* Refactor core factory structure to eliminate duplication and unify metadata handling

* Add initial experiment setup and analysis workflow for hrpt project

* Update easydiffraction version and SHA-256 hash in pixi.lock

* Refactor architecture documentation to clarify factory structures and display methods

* Remove unused exports from __init__.py to streamline module interface

* Refactor string quotes in test.py for consistency and readability

* unify CollectionBase key resolution, add __contains__ and remove()

* Make ExperimentType immutable after creation

* Make peak and background read-only public properties

* Document editable vs read-only property convention with _set_ private methods

* Standardize switchable-category naming convention

* Apply formatting

* Refactor Analysis class to instantiate calculator in __init__ and remove class-level attribute

* Remove duplicated symmetry methods from Structure

* Route constraint updates through validated setter

* Override _key_for in CategoryCollection and DatablockCollection

* Warn when switching background or peak profile type

* Document why minimisers bypass the value setter

* Replace 'lmfit (leastsq)' with 'lmfit' in tests, tutorials, and docs

* Consolidate revised-design-v5.md into architecture.md

* Apply formatting

* Update copilot instructions for linting and testing workflow

* Enable dirty-flag guard via _set_value_from_minimizer

* Add factory.py and metadata.py to package structure documentation

* Consolidate all issues into issues.md and update copilot instructions

* Move calculator from global Analysis to per-experiment

* Add Bragg+PDF joint tutorial, multi-experiment docs section, and test

* Temporarily disable Bragg+PDF joint fit until test is improved

* Add universal factories for Extinction and LinkedCrystal

* Add universal factories for all remaining categories

* Update tutorial #14

* Add switchable-category API to all factory-created categories

* Add switchable-category API for instrument and data on experiments

* Filter show_supported_instrument_types by experiment context

* Add target-audience and reliability instructions to copilot config

* Convert fit_mode to CategoryItem

* Convert fit_mode to factory-based category with enum comparison

* Add flat category structure rule to architecture.md

* Consolidate architecture docs and fix stale references

* Restructure help() to show Parameters, Properties, and Methods tables

* Auto-populate Analysis.help() from class introspection

* Refine eager-imports rule to document lazy-import exceptions

* Update tutorial structure in mkdocs.yml for clarity and consistency

* Update issues list

* Add instruction to run tutorial tests after changes

* Refactor background type naming for consistency

* Delete test.py

* Fix tutorial failures and stale calculator cache with excluded regions

* Update issues

* Update tutorial names and copyright year

Author: AndrewSazonov

.github/copilot-instructions.md

@@ -0,0 +1,136 @@
+# Copilot Instructions for EasyDiffraction
+
+## Project Context
+
+- Python library for crystallographic diffraction analysis, such as refinement
+  of the structural model against experimental data.
+- Support for
+  - sample_form: powder and single crystal
+  - beam_mode: time-of-flight and constant wavelength
+  - radiation_probe: neutron and x-ray
+  - scattering_type: bragg and total scattering
+- Calculations are done using external calculation libraries:
+  - `cryspy` for Bragg diffraction
+  - `crysfml` for Bragg diffraction
+  - `pdffit2` for Total scattering
+- Follow CIF naming conventions where possible. In some places, we deviate for
+  better API design, but we try to keep the spirit of the CIF names.
+- Reusing the concept of datablocks and categories from CIF. We have
+  `DatablockItem` (structure or experiment) and `DatablockCollection`
+  (collection of structures or experiments), as well as `CategoryItem` (single
+  categories in CIF) and `CategoryCollection` (loop categories in CIF).
+- Metadata via frozen dataclasses: `TypeInfo`, `Compatibility`,
+  `CalculatorSupport`.
+- The API is designed for scientists who use EasyDiffraction as a final product
+  in a user-friendly, intuitive way. The target users are not software
+  developers and may have little or no Python experience. The design is not
+  oriented toward developers building their own tooling on top of the library,
+  although experienced developers will find their own way. Prioritize
+  discoverability, clear error messages, and safe defaults so that
+  non-programmers are not stuck by standard API conventions.
+- This project must be developed to be as error-free as possible, with the same
+  rigour applied to critical software (e.g. nuclear-plant control systems).
+  Every code path must be tested, edge cases must be handled explicitly, and
+  silent failures are not acceptable.
+
+## Code Style
+
+- Use snake_case for functions and variables, PascalCase for classes, and
+  UPPER_SNAKE_CASE for constants.
+- Use `from __future__ import annotations` in every module.
+- Type-annotate all public function signatures.
+- Docstrings on all public classes and methods (Google style).
+- Prefer flat over nested, explicit over clever.
+- Write straightforward code; do not add defensive checks for unlikely edge
+  cases.
+- Prefer composition over deep inheritance.
+- One class per file when the class is substantial; group small related classes.
+- Avoid `**kwargs`; use explicit keyword arguments for clarity, autocomplete,
+  and typo detection.
+- Do not use string-based dispatch (e.g. `getattr(self, f'_{name}')`) to route
+  to attributes or methods. Instead, write explicit named methods (e.g.
+  `_set_sample_form`, `_set_beam_mode`). This keeps the code greppable,
+  autocomplete-friendly, and type-safe.
+- Public parameters and descriptors are either **editable** (property with both
+  getter and setter) or **read-only** (property with getter only). If internal
+  code needs to mutate a read-only property, add a private `_set_<name>` method
+  instead of exposing a public setter.
+
+## Architecture
+
+- Eager imports at the top of the module by default. Use lazy imports (inside a
+  method body) only when necessary to break circular dependencies or to keep
+  `core/` free of heavy utility imports on rarely-called paths (e.g. `help()`).
+- No `pkgutil` / `importlib` auto-discovery patterns.
+- No background/daemon threads.
+- No monkey-patching or runtime class mutation.
+- Do not use `__all__` in modules; instead, rely on explicit imports in
+  `__init__.py` to control the public API.
+- Do not use redundant `import X as X` aliases in `__init__.py`. Use plain
+  `from module import X`.
+- Concrete classes use `@Factory.register` decorators. To trigger registration,
+  each package's `__init__.py` must explicitly import every concrete class (e.g.
+  `from .chebyshev import ChebyshevPolynomialBackground`). When adding a new
+  concrete class, always add its import to the corresponding `__init__.py`.
+- Switchable categories (those whose implementation can be swapped at runtime
+  via a factory) follow a fixed naming convention on the owner (experiment,
+  structure, or analysis): `<category>` (read-only property), `<category>_type`
+  (getter + setter), `show_supported_<category>_types()`,
+  `show_current_<category>_type()`. The owner class owns the type setter and the
+  show methods; the show methods delegate to `Factory.show_supported(...)`
+  passing context. Every factory-created category must have this full API, even
+  if only one implementation exists today.
+- Categories are flat siblings within their owner (datablock or analysis). A
+  category must never be a child of another category of a different type.
+  Categories can reference each other via IDs, but not via parent-child nesting.
+- Every finite, closed set of values (factory tags, experiment axes, category
+  descriptors with enumerated choices) must use a `(str, Enum)` class. Internal
+  code compares against enum members, never raw strings.
+- Keep `core/` free of domain logic — only base classes and utilities.
+- Don't introduce a new abstraction until there is a concrete second use case.
+- Don't add dependencies without asking.
+
+## Changes
+
+- Before implementing any structural or design change (new categories, new
+  factories, switchable-category wiring, new datablocks, CIF serialisation
+  changes), read `docs/architecture/architecture.md` to understand the current
+  design choices and conventions. Follow the documented patterns (factory
+  registration, switchable-category naming, metadata classification, etc.) to
+  stay consistent with the rest of the codebase. For localised bug fixes or test
+  updates, the rules in this file are sufficient.
+- The project is in beta; do not keep legacy code or add deprecation warnings.
+  Instead, update tests and tutorials to follow the current API.
+- Minimal diffs: don't rewrite working code just to reformat it.
+- Never remove or replace existing functionality as part of a new change without
+  explicit confirmation. If a refactor would drop features, options, or
+  configurations, highlight every removal and wait for approval.
+- Fix only what's asked; flag adjacent issues as comments, don't fix them
+  silently.
+- Don't add new features or refactor existing code unless explicitly asked.
+- Do not remove TODOs or comments unless the change fully resolves them.
+- When renaming, grep the entire project (code, tests, tutorials, docs).
+- Every change should be atomic and self-contained, small enough to be described
+  by a single commit message. Make one change, suggest the commit message, then
+  stop and wait for confirmation before starting the next change.
+- When in doubt, ask for clarification before making changes.
+
+## Workflow
+
+- All open issues, design questions, and planned improvements are tracked in
+  `docs/architecture/issues_open.md`, ordered by priority. When an issue is
+  fully implemented, move it from that file to
+  `docs/architecture/issues_closed.md`. When the resolution affects the
+  architecture, update the relevant sections of
+  `docs/architecture/architecture.md`.
+- After changes, run linting and formatting fixes with `pixi run fix`. Do not
+  check what was auto-fixed, just accept the fixes and move on.
+- After changes, run unit tests with `pixi run unit-tests`.
+- After changes, run integration tests with `pixi run integration-tests`.
+- After changes, run tutorial tests with `pixi run script-tests`.
+- Suggest a concise commit message (as a code block) after each change (less
+  than 72 characters, imperative mood, without prefixing with the type of
+  change). E.g.:
+  - Add ChebyshevPolynomialBackground class
+  - Implement background_type setter on Experiment
+  - Standardize switchable-category naming convention

docs/api-reference/datablocks/experiment.md

@@ -0,0 +1 @@
+::: easydiffraction.datablocks.experiment

docs/api-reference/datablocks/structure.md

@@ -0,0 +1 @@
+::: easydiffraction.datablocks.structure

docs/api-reference/experiments.md

@@ -13,12 +13,13 @@ available in EasyDiffraction:
   space groups, and symmetry operations.
 - [utils](utils.md) – Miscellaneous utility functions for formatting,
   decorators, and general helpers.
+- datablocks
+  - [experiments](datablocks/experiment.md) – Manages experimental setups and
+    instrument parameters, as well as the associated diffraction data.
+  - [structures](datablocks/structure.md) – Defines structures, such as
+    crystallographic structures, and manages their properties.
 - [display](display.md) – Tools for plotting data and rendering tables.
 - [project](project.md) – Defines the project and manages its state.
-- [sample_models](sample_models.md) – Defines sample models, such as
-  crystallographic structures, and manages their properties.
-- [experiments](experiments.md) – Manages experimental setups and instrument
-  parameters, as well as the associated diffraction data.
 - [analysis](analysis.md) – Provides tools for analyzing diffraction data,
   including fitting and minimization.
 - [summary](summary.md) – Provides a summary of the project.