Туториал ======== Этот туториал покажет, как использовать библиотеку ORCA Descriptors как через Python, так и через командную строку. Использование как Python библиотека -------------------------- Базовое использование ~~~~~~~~~~~ Сначала импортируйте необходимые классы:: from orca_descriptors import Orca from rdkit.Chem import MolFromSmiles, AddHs Инициализируйте калькулятор ORCA с нужными настройками:: orca = Orca( script_path="orca", functional="PBE0", basis_set="def2-SVP", method_type="Opt", dispersion_correction="D3BJ", solvation_model="COSMO(Water)", n_processors=8, pre_optimize=True, # Включить предоптимизацию геометрии с MMFF94 ) Создайте молекулу из SMILES строки:: mol = AddHs(MolFromSmiles("C1=CC=CC=C1")) # Бензол Рассчитайте дескрипторы:: # Энергетические дескрипторы homo = orca.homo_energy(mol) lumo = orca.lumo_energy(mol) gap = orca.gap_energy(mol) # DFT дескрипторы mu = orca.ch_potential(mol) chi = orca.electronegativity(mol) eta = orca.abs_hardness(mol) # Термодинамические дескрипторы energy = orca.total_energy(mol) gibbs = orca.gibbs_free_energy(mol) # Дескрипторы молекулярных орбиталей homo_minus_1 = orca.mo_energy(mol, index=-2) # Энергия HOMO-1 # Дескрипторы зарядов min_h_charge = orca.get_min_h_charge(mol, method="ESP") # Минимальный заряд водорода # Геометрические дескрипторы xy_area = orca.xy_shadow(mol) # Площадь проекции на плоскость XY # Дескрипторы реакционной способности meric = orca.meric(mol) # Индекс электрофильности для углерода # Топологические дескрипторы t_oo = orca.topological_distance(mol, 'O', 'O') # Сумма расстояний O-O nrot = orca.num_rotatable_bonds(mol) # Количество вращающихся связей wiener = orca.wiener_index(mol) # Индекс Винера # Физико-химические дескрипторы logp = orca.m_log_p(mol) # Коэффициент распределения октанол/вода sasa = orca.solvent_accessible_surface_area(mol) # SASA # Дескрипторы автокорреляции mats2v = orca.moran_autocorrelation(mol, lag=2, weight='vdw_volume') hats4u = orca.autocorrelation_hats(mol, lag=4, unweighted=True) Кеширование ~~~~~~~ Библиотека автоматически кеширует результаты расчетов. Если вы рассчитываете дескрипторы для той же молекулы с теми же параметрами, будет использован кешированный результат:: # Первый расчет - запускает ORCA homo1 = orca.homo_energy(mol) # Занимает время # Второй расчет - использует кеш homo2 = orca.homo_energy(mol) # Мгновенно Удаленный кеш ~~~~~~~~~~~~~ Библиотека поддерживает удаленное кеширование через API, позволяя делиться результатами расчетов между разными машинами и пользователями. Доступен публичный сервер кеша по адресу ``https://api.orca-descriptors.massonnn.ru``. Для использования удаленного кеша необходимо: 1. Зарегистрироваться на `orca-descriptors.massonnn.ru `_ и выпустить API токен 2. Указать API токен при инициализации экземпляра Orca:: orca = Orca( functional="PBE0", basis_set="def2-SVP", cache_api_token="ваш_api_токен", # Опционально: указать пользовательский URL сервера # cache_server_url="https://api.orca-descriptors.massonnn.ru", ) Удаленный кеш работает прозрачно: - Сначала проверяется локальный кеш, затем удаленный, если доступен - Результаты, найденные в удаленном кеше, автоматически загружаются и сохраняются локально - Новые расчеты автоматически загружаются на удаленный сервер (если у вас есть права на загрузку) - Если удаленный кеш недоступен, система переключается на локальное кеширование Режим только кеша ~~~~~~~~~~~~~~~~~ Вы можете включить режим только кеша для использования только закешированных результатов без запуска расчетов ORCA. Это полезно для быстрого получения результатов из кеша:: orca = Orca( functional="PBE0", basis_set="def2-SVP", cache_api_token="ваш_api_токен", cache_only=True, # Только использовать кеш, не запускать расчеты ) # Если результат в кеше, возвращает значение # Если результат не в кеше, выбрасывает FileNotFoundError homo = orca.homo_energy(mol) В режиме только кеша: - Используются только закешированные результаты (локальные или удаленные) - Если результат не найден в кеше, дескрипторы возвращают ``None`` в пакетной обработке - Расчеты ORCA не выполняются - Полезно для быстрого получения результатов из кеша без выполнения дорогостоящих расчетов Выбор функционалов и методов ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Библиотека поддерживает как DFT методы, так и полуэмпирические методы: DFT методы ^^^^^^^^^^ Для расчетов с высокой точностью используйте DFT функционалы с базисными наборами:: # Высокоточный DFT расчет orca_dft = Orca( functional="PBE0", # Гибридный функционал basis_set="def2-TZVP", # Тройной дзета базисный набор method_type="Opt", # Оптимизация геометрии dispersion_correction="D3BJ", # Дисперсионная коррекция n_processors=8, ) Распространенные DFT функционалы: - ``PBE0`` - Гибридный GGA функционал, хороший баланс точности и скорости - ``B3LYP`` - Популярный гибридный функционал - ``M06-2X`` - Meta-GGA функционал, хорош для термохимии - ``ωB97X-D`` - Range-separated гибрид с дисперсией Распространенные базисные наборы: - ``def2-SVP`` - Маленький, быстрый (по умолчанию) - ``def2-TZVP`` - Тройной дзета, более точный - ``def2-QZVP`` - Четверной дзета, очень точный, но медленный Полуэмпирические методы ^^^^^^^^^^^^^^^^^^^^^^^^ Для быстрых расчетов больших молекул используйте полуэмпирические методы:: # Быстрый полуэмпирический расчет orca_semi = Orca( functional="AM1", # Полуэмпирический метод method_type="SP", # Одноточечный расчет (без оптимизации) n_processors=1, pre_optimize=True, # Предоптимизировать с MMFF94 ) Поддерживаемые полуэмпирические методы: - ``AM1`` - Austin Model 1, хорош для органических молекул - ``PM3`` - Parametric Method 3, улучшенная версия AM1 - ``PM6`` - Parametric Method 6, лучше для переходных металлов - ``PM7`` - Parametric Method 7, улучшенная точность - ``RM1`` - Recife Model 1, оптимизирован для органических соединений Примечание: Для полуэмпирических методов параметры ``basis_set`` и ``dispersion_correction`` автоматически игнорируются. Предоптимизация геометрии ~~~~~~~~~~~~~~~~~~~~~~~~~~ По умолчанию библиотека выполняет предоптимизацию геометрии с использованием силового поля MMFF94 из RDKit перед отправкой молекулы в ORCA. Это может значительно ускорить расчеты ORCA, особенно для оптимизации геометрии:: # С предоптимизацией (по умолчанию) orca = Orca( functional="PBE0", method_type="Opt", pre_optimize=True, # По умолчанию: True ) # Без предоптимизации orca = Orca( functional="PBE0", method_type="Opt", pre_optimize=False, ) Преимущества предоптимизации: - Быстрее сходимость ORCA (требуется меньше шагов оптимизации) - Более стабильные расчеты (лучшая стартовая геометрия) - Снижение вычислительных затрат Предоптимизация использует MMFF94, который требует явных атомов водорода. Библиотека автоматически добавляет водород, если необходимо, и генерирует 3D координаты, если они отсутствуют. Типы расчетов ~~~~~~~~~~~~~ Выберите подходящий тип расчета в зависимости от ваших потребностей:: # Одноточечный расчет энергии (самый быстрый) orca_sp = Orca( functional="PBE0", method_type="SP", # Одноточечный расчет ) # Оптимизация геометрии (медленнее, но дает оптимизированную геометрию) orca_opt = Orca( functional="PBE0", method_type="Opt", # Оптимизация ) Примечание: Некоторые дескрипторы (например, ``molecular_volume``, ``polar_surface_area``, ``solvent_accessible_surface_area``) требуют оптимизированной геометрии и могут работать некорректно с ``method_type="SP"``. Использование как консольная утилита ----------------------------- Библиотеку также можно использовать как консольную утилиту после установки. Запуск бенчмарка ~~~~~~~~~~~~~ Перед оценкой времени расчетов запустите бенчмарк:: orca_descriptors run_benchmark --working_dir ./calculations Оценка времени расчета ~~~~~~~~~~~~~~~~~~~~~~~~~ Оцените, сколько времени займет расчет:: orca_descriptors approximate_time --molecule CCO --method_type Opt Все параметры ORCA доступны как аргументы CLI. Например:: orca_descriptors approximate_time \\ --molecule CCO \\ --functional PBE0 \\ --basis_set def2-TZVP \\ --n_processors 4 \\ --method_type Opt Пример рабочего процесса ---------------- Вот полный пример расчета дескрипторов для нескольких молекул:: from orca_descriptors import Orca from rdkit.Chem import MolFromSmiles, AddHs # Инициализация калькулятора orca = Orca( working_dir="./calculations", functional="PBE0", basis_set="def2-SVP", method_type="Opt", n_processors=4, ) # Список молекул для обработки smiles_list = [ "C1=CC=CC=C1", # Бензол "CCO", # Этанол "CC(=O)C", # Ацетон ] results = [] for smiles in smiles_list: mol = AddHs(MolFromSmiles(smiles)) results.append({ "smiles": smiles, "homo": orca.homo_energy(mol), "lumo": orca.lumo_energy(mol), "gap": orca.gap_energy(mol), "dipole": orca.dipole_moment(mol), }) # Обработка результатов for r in results: print(f"{r['smiles']}: Gap = {r['gap']:.2f} eV") Доступные дескрипторы --------------------- Библиотека предоставляет комплексный набор дескрипторов для QSAR анализа: Энергетические дескрипторы ~~~~~~~~~~~~~~~~~~ - ``homo_energy(mol)`` - Энергия HOMO (эВ) - ``lumo_energy(mol)`` - Энергия LUMO (эВ) - ``gap_energy(mol)`` - Разрыв HOMO-LUMO (эВ) - ``mo_energy(mol, index)`` - Энергия молекулярной орбитали по индексу (эВ) - ``total_energy(mol)`` - Полная энергия (Хартри) DFT дескрипторы ~~~~~~~~~~~~~~~ - ``ch_potential(mol)`` - Химический потенциал (эВ) - ``electronegativity(mol)`` - Электроотрицательность (эВ) - ``abs_hardness(mol)`` - Абсолютная жесткость (эВ) - ``abs_softness(mol)`` - Абсолютная мягкость (1/эВ) - ``frontier_electron_density(mol)`` - Плотность фронтирных электронов Дескрипторы зарядов ~~~~~~~~~~~~~~~~~~ - ``get_atom_charges(mol)`` - Атомные заряды Малликена - ``get_min_h_charge(mol, method="ESP")`` - Минимальный заряд водорода Геометрические дескрипторы ~~~~~~~~~~~~~~~~~~~~~ - ``xy_shadow(mol)`` - Площадь проекции на плоскость XY (Ų) - ``molecular_volume(mol)`` - Молекулярный объем (ų) - ``get_bond_lengths(mol, atom1, atom2)`` - Длины связей (Å) Дескрипторы реакционной способности ~~~~~~~~~~~~~~~~~~~~~~ - ``meric(mol)`` - Минимальный индекс электрофильности для углерода (эВ) - ``dipole_moment(mol)`` - Дипольный момент (Дебай) Топологические дескрипторы ~~~~~~~~~~~~~~~~~~~~~~~ - ``topological_distance(mol, atom1, atom2)`` - Сумма топологических расстояний - ``num_rotatable_bonds(mol)`` - Количество вращающихся связей - ``wiener_index(mol)`` - Индекс Винера Физико-химические дескрипторы ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``m_log_p(mol)`` - Коэффициент распределения Моригучи (октанол/вода) - ``polar_surface_area(mol)`` - Полярная площадь поверхности (Ų) - ``solvent_accessible_surface_area(mol)`` - Доступная площадь поверхности растворителя (Ų) Термодинамические дескрипторы ~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``gibbs_free_energy(mol)`` - Энергия Гиббса (Хартри) - ``entropy(mol)`` - Энтропия (Дж/(моль·К)) - ``enthalpy(mol)`` - Энтальпия (Хартри) Дескрипторы автокорреляции ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``moran_autocorrelation(mol, lag, weight)`` - Автокорреляция Моран - ``autocorrelation_hats(mol, lag, unweighted)`` - Автокорреляция HATS