v0.0.15 - Миграция на .NET10 + комментарии в коде и описания

Author: Infarh

MathCore.DSP/DoubleArrayDSPExtensions.cs

@@ -1,4 +1,5 @@
-namespace MathCore.DSP.Filters.Builders;
+// ReSharper disable InconsistentNaming
+namespace MathCore.DSP.Filters.Builders;
 
 /// <summary>Строитель фильтров верхних частот</summary>
 /// <param name="dt">Период дискретизации</param>
@@ -20,7 +21,7 @@ public readonly record struct HighPassBuilder(double dt)
 }
 
 /// <summary>Строитель фильтра Баттерворта верхних частот</summary>
-/// <param name="dt">Период дискретизации</param> /// <param name="fs">Частота заграждения</param>
+/// <param name="dt">Период дискретизации</param>
 /// <param name="fs">Частота заграждения</param>
 /// <param name="fp">Частота пропускания</param>
 /// <param name="Gp">Коэффициент передачи в полосе пропускания</param>

MathCore.DSP/Filters/Builders/HighPassBuilder.cs

@@ -0,0 +1,87 @@
+# Builders фильтров
+
+Директория содержит набор "строителей" (Builder-типы) для создания дискретных цифровых фильтров различных семейств (Баттерворта, Чебышева, эллиптических и простых RC) с параметризацией через удобный fluent/record‑подход.
+
+## Назначение
+Builder-структуры инкапсулируют параметры проектирования фильтра (тип полосы пропускания, частоты, коэффициенты усиления/затухания, порядок и допуски) и подготавливают экземпляры конечных фильтров (`Filter`) через метод `Create()` или неявное преобразование оператора `implicit`.
+
+## Состав
+- `FrequencyPassType` – перечисление типов полосы: ФНЧ, ФВЧ, ППФ, ПЗФ
+- Универсальные ref builders (параметрические без метода создания в текущей версии):
+  - `ButterworthBuilder`
+  - `ChebyshevBuilder`
+  - `EllipticBuilder`
+- Специализированные builders нижних частот:
+  - `LowPassBuilder` – корневой строитель; производные:
+    - `LowPassButterworthBuilder`
+    - `LowPassChebyshevBuilder`
+    - `LowPassEllipticBuilder`
+    - `LowPassRCBuilder` (RC-фильтр первого порядка)
+    - `LowPassRCExponentialBuilder` (вариант с экспоненциальной аппроксимацией)
+- Специализированные builders верхних частот:
+  - `HighPassBuilder` – корневой строитель; производные:
+    - `HighPassButterworthBuilder`
+    - `HighPassChebyshevBuilder`
+- Заготовки полосных фильтров:
+  - `BandPassBuilder`
+  - `BandStopBuilder`
+
+## Общие параметры
+Большинство builders оперируют:
+- `dt` – период дискретизации (сек)
+- `fd` – частота дискретизации (Гц) (взаимосвязана с `dt`)
+- `fp`, `fs` – граничные частоты пропускания / заграждения
+- `Gp`, `Gs` – коэффициенты передачи в полосах (линейные, не в дБ)
+- `Rp`, `Rs` – неравномерность (ripples) / затухание (дБ)
+- `Order` – желаемый порядок (если требуется принудительно)
+
+## Использование
+### Пример: ФНЧ Баттерворта
+```csharp
+var dt = 1 / 8000d; // период дискретизации
+var builder = new LowPassBuilder(dt)
+    .Butterworth(fs: 1500, fp: 1000, Gp: 1, Gs: 0.1);
+
+Filter filter = builder; // неявное преобразование
+// Или явное создание:
+var bw_lp = builder.Create();
+```
+### Пример: ФВЧ Чебышева
+```csharp
+var dt = 1 / 44100d;
+var cheb_hp_builder = new HighPassBuilder(dt)
+    .Chebyshev(fs: 500, fp: 1000, Gp: 1, Gs: 0.05);
+
+Filter cheb_hp = cheb_hp_builder; // implicit
+```
+### Пример: RC фильтр нижних частот
+```csharp
+var dt = 1 / 1000d;
+var rc_builder = new LowPassBuilder(dt).RC(f0: 10);
+Filter rc = rc_builder; // создание RC фильтра
+```
+### Пример: RC экспоненциальный
+```csharp
+var dt = 1 / 1000d;
+var rc_exp_builder = new LowPassBuilder(dt).RCExponential(f0: 10);
+Filter rc_exp = rc_exp_builder;
+```
+
+## Особенности
+- Запись через `record struct` облегчает иммутабельность и копирование с изменением (`with`)
+- Неявные операторы преобразования упрощают получение готового фильтра
+- Для универсальных builders (`ButterworthBuilder`, `ChebyshevBuilder`, `EllipticBuilder`) далее может быть расширена функциональность методами расчёта и генерации коэффициентов
+
+## План расширений
+1. Реализация методов `Create()` для универсальных builders с автоматическим подбором порядка по допускам
+2. Добавление полосных (ППФ/ПЗФ) вариантов с расчётом преобразования частот
+3. Включение генерации АЧХ/ФЧХ/Импульсной характеристики прямо из builder
+
+## Быстрый старт
+1. Выберите базовый builder по типу полосы (`LowPassBuilder`, `HighPassBuilder` и т.д.)
+2. Вызовите метод семейства фильтра (`Butterworth`, `Chebyshev`, `RC` ...)
+3. Неявно преобразуйте к `Filter` или вызовите `Create()`
+4. Используйте полученный фильтр для обработки выборок (методы исходного класса `Filter`)
+
+---
+При добавлении новых типов фильтров выдерживайте единый стиль: минимализм, иммутабельность параметров, русские XML‑комментарии и неявный оператор преобразования к `Filter`.

MathCore.DSP/Filters/Builders/readme.md

@@ -0,0 +1,111 @@
+# Фильтры Баттерворта
+
+Главные особенности:
+- АЧХ в полосе пропускания без ряби (maximally flat)
+- Переходная полоса шире при равных допусках, чем у Чебышева и эллиптических
+- Порядок выше, чем у Чебышева/эллиптических для тех же `Rp`, `Rs`
+- Фаза более гладкая, чем у Чебышева и эллиптических
+- Выбор: когда важны ровность амплитуды и умеренная фазовая гладкость, а минимальная крутизна не критична
+
+Реализации:
+- ФНЧ: `ButterworthLowPass`
+- ФВЧ: `ButterworthHighPass`
+- ППФ: `ButterworthBandPass`
+- ПЗФ: `ButterworthBandStop`
+
+# Фильтры Чебышева
+
+Главные особенности:
+- Типы (роды): I (рябь в passband), II (рябь в stopband), IICorrected (корректированный II)
+- Уже переходная полоса при меньшем порядке, чем у Баттерворта
+- Рябь только в одной из полос (в зависимости от рода)
+- Фаза менее гладкая, возможны колебания групповой задержки
+- Выбор: когда нужна повышенная крутизна и допустима рябь в строго одной полосе
+
+Реализации:
+- ФНЧ: `ChebyshevLowPass` (типы I/II/IICorrected)
+- ФВЧ: `ChebyshevHighPass` (типы I/II/IICorrected)
+- ППФ: `ChebyshevBandPass` (типы I/II/IICorrected)
+- ПЗФ: `ChebyshevBandStop` (типы I/II/IICorrected)
+
+# Эллиптические (Кауэра) фильтры
+
+Главные особенности:
+- Рябь (equiripple) одновременно в полосе пропускания и заграждения
+- Минимальный порядок для заданных допусков `Rp`, `Rs`
+- Самая узкая переходная полоса (максимальная крутизна)
+- Наихудшая линейность фазы среди реализованных типов
+- Выбор: когда критичны минимальный порядок и максимальная селективность, фазовая нелинейность некритична или компенсируется
+
+Реализации:
+- ФНЧ: `EllipticLowPass`
+- ФВЧ: `EllipticHighPass`
+- ППФ: `EllipticBandPass`
+- ПЗФ: `EllipticBandStop`
+
+# RC / RLC фильтры (простые прототипы)
+
+Назначение: быстрота расчёта, минимальная сложность, удобны как справочные/базовые элементы или для предварительной фильтрации.
+
+## RC‑цепочка (ФНЧ)
+- `RCLowPass`: билинейное преобразование RC‑прототипа (1 полюс). Плавный спад, −3дБ на частоте среза, монотонная АЧХ.
+- `RCExponentialLowPass`: экспоненциальная аппроксимация (использует экспоненту для расчёта коэффициента затухания), аналог одношагового сглаживания.
+
+## RLC‑резонансные
+- `RLCBandPass`: полосопропускающий (резонансный) фильтр второго порядка, задаётся центральной частотой `f0` и шириной полосы `DeltaF` (по уровню 0.707).
+- `RLCBandStop`: полосозаграждающий (notch) фильтр второго порядка, подавляет узкую резонансную полосу вокруг `f0`.
+
+Особенности:
+- Низкий порядок (1–2) обеспечивает минимальную задержку и простоту реализации
+- Крутизна ограничена; для строгих допусков используются Баттерворт/Чебышев/Эллиптические
+- Подходят для быстрой фильтрации / подавления одиночной помехи или сглаживания
+
+# БИХ базовый класс
+
+## `IIR`
+- Общий каркас IIR‑фильтра: хранение коэффициентов A (знаменатель) и B (числитель)
+- Метод `Process` реализует одношаговую рекуррентную фильтрацию (difference equation)
+- Методы частотного отклика и операции структурного соединения:
+  - `ConnectionSerialTo(IIR)`: последовательное соединение (свёртка полиномов)
+  - `ConnectionParallelTo(IIR)`: параллельное соединение (сумма откликов с нормировкой)
+
+# Структурные (комбинационные) фильтры
+
+## `SerialFilter`
+- Последовательное включение двух произвольных `Filter` (не только IIR). Передача выхода первого на вход второго.
+
+## `ParallelFilter`
+- Параллельное включение: усреднённая сумма откликов двух фильтров (балансировка усиления).
+
+Назначение структурных классов: формирование составных конфигураций (каскады и разветвления) без ручного перемножения коэффициентов, возможность комбинировать разнородные фильтры.
+
+# Абстрактный базовый класс `Filter`
+
+- Определяет базовый интерфейс: `Process`, `Reset`, `FrequencyResponse`
+- Строители типов: статические фабрики `LowPass`, `HighPass`, `BandPass`, `BandStop`, а также `Butterworth`, `Chebyshev`, `Elliptic` для удобного fluent‑конструирования
+- Перегруженные операторы:
+  - `filter * signal` — фильтрация сигнала
+  - `filter1 + filter2` — параллельное соединение (`ParallelFilter`)
+  - `filter1 * filter2` — последовательное соединение (`SerialFilter`)
+
+# Методы расширения
+
+## `DigitalFilterExtension`
+- `GetImpulseResponse(...)`: генерация импульсной характеристики с ранним прекращением по затуханию
+- `GetTransientResponse(...)`: генерация переходной характеристики (единичный скачок)
+
+# Выбор типа фильтра (кратко)
+- Нужна ровная passband и терпима широкая переходная: Баттерворт
+- Требуется более крутой спад и рябь в одной полосе допустима: Чебышев (выбор рода)
+- Минимальный порядок и узкая переходная критичны: Эллиптический
+- Простое сглаживание / резонанс / узкая notch без сложных требований: RC / RLC
+- Комбинирование характеристик (усиление селективности, формирование окон): используйте каскады (`SerialFilter`) или параллель (`ParallelFilter`)
+
+# Сводный перечень классов
+- Базовые: `Filter`, `IIR`
+- Баттерворт: `ButterworthLowPass`, `ButterworthHighPass`, `ButterworthBandPass`, `ButterworthBandStop`
+- Чебышев: `ChebyshevLowPass`, `ChebyshevHighPass`, `ChebyshevBandPass`, `ChebyshevBandStop` (+ роды I / II / IICorrected)
+- Эллиптические: `EllipticLowPass`, `EllipticHighPass`, `EllipticBandPass`, `EllipticBandStop`
+- RC / RLC: `RCLowPass`, `RCExponentialLowPass`, `RLCBandPass`, `RLCBandStop`
+- Структурные: `SerialFilter`, `ParallelFilter`
+- Расширения: `DigitalFilterExtension`

MathCore.DSP/Filters/readme.md

@@ -0,0 +1,25 @@
+#if !NET8_0_OR_GREATER
+using System.Runtime.CompilerServices;
+
+namespace MathCore.DSP.Infrastructure;
+
+internal static class ArgumentNullExceptionEx
+{
+    extension(ArgumentNullException)
+    {
+        public static void ThrowIfNull(object? argument, [CallerArgumentExpression("argument")] string? ParamName = null)
+        {
+            if (argument != null)
+                return;
+            ArgumentNullException.Throw(ParamName);
+        }
+
+        [DoesNotReturn]
+        public static void Throw(string ParamName) => throw new ArgumentNullException(ParamName);
+    }
+}
+
+[AttributeUsage(AttributeTargets.Method, Inherited = false)]
+public sealed class DoesNotReturnAttribute : Attribute;
+
+#endif

MathCore.DSP/Infrastructure/ArgumentNullExceptionEx.cs

@@ -9,18 +9,20 @@
     </TargetFrameworks>
     <GeneratePackageOnBuild>false</GeneratePackageOnBuild>
     <LangVersion>preview</LangVersion>
-    <Version>0.0.14.2</Version>
+    <Version>0.0.15</Version>
     <ImplicitUsings>enable</ImplicitUsings>
     <PackageReleaseNotes>
-      Обновление пакетов
+      Миграция на .NET 10.0 и обновление зависимостей.
     </PackageReleaseNotes>
+    <PackageReadmeFile>readme.md</PackageReadmeFile>
   </PropertyGroup>
 
   <PropertyGroup>
     <Authors>Shmachilin P.A.</Authors>
     <Description>Библиотека алгоритмов цифровой обработки сигналов</Description>
     <PackageProjectUrl>https://github.com/Infarh/MathCore.DSP</PackageProjectUrl>
     <RepositoryUrl>https://github.com/Infarh/MathCore.DSP.git</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
     <PackageTags>DSP;Signal processing</PackageTags>
     <Copyright>shmachilin@gmail.com</Copyright>
     <SignAssembly>true</SignAssembly>
@@ -59,4 +61,12 @@
     <PackageReference Include="System.Reflection.Emit.Lightweight" Version="4.7.0" PrivateAssets="All" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Using Include="MathCore.DSP.Infrastructure" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="readme.md" Pack="true" PackagePath="" />
+  </ItemGroup>
+
 </Project>