Слияние кода завершено, страница обновится автоматически
Команда MFEM приветствует вклады на всех уровнях: исправление ошибок; улучшение кода; упрощение; новые возможности сетей, дискретизации или решателей; улучшенная документация; новые примеры и мини-приложения; повышение производительности на вычислительных комплексах; и т.д.
MFEM распространяется на условиях лицензии BSD-3. Все новые вклады должны быть сделаны под этими условиями.Если вы планируете вносить изменения в проект MFEM, рекомендуется сначала просмотреть трекер задач, чтобы проверить наличие существующих тем, соответствующих вашему желаемому функционалу или найденной ошибке. Предложите свои изменения через запрос на слияние (pull request, PR) в ветку mfem:master. Если вы планируете значительные изменения кода или имеете вопросы, возможно, стоит открыть задачу перед отправкой PR. В дополнение к техническим вкладам, мы также заинтересованы в ваших результатах и изображениях симуляций, которые можно поделиться через PR в репозиторий mfem/web. См. раздел Краткое содержание для основных моментов нашего GitHub-потока. Для получения более подробной информации обратитесь к следующим разделам и используйте их как справочник перед отправкой запросов на слияние.- Краткое содержание
Участие в проекте MFEM требует знаний Git и, возможно, конечных элементов. Если вы новичок в Git, см. учебные материалы GitHub. Для получения дополнительной информации о методе конечных элементов см. нашу страницу FEM.
Отправка запроса на слияние означает ваше согласие с Свидетельством разработчика о происхождении в конце этого файла.## Краткое содержание
mfem:master.mfem:master. Убедитесь, что вы проверили все пункты в Checkliste для pull request'ов.ready-for-review.mfem:next исходный PR сливают в mfem:master.Библиотека MFEM использует принципы объектно-ориентированного дизайна, отражая в коде независимые математические концепции сеточной моделировки, линейной алгебры и пространства конечно-элементных методов и операторов.
Структура исходного кода MFEM имеет следующий вид:
.
├── config
│ ├── cmake
│ │ └── ...
│ └── githooks
├── data
├── doc
├── examples
│ ├── amgx
│ ├── caliper
│ ├── ginkgo
│ ├── hiop
│ ├── petsc
│ ├── pumi
│ ├── sundials
│ └── superlu
├── fem
│ ├── ceed
│ ├── qinterp
│ └── tmop
├── general
├── linalg
│ └── simd
├── mesh
├── miniapps
│ ├── adjoint
│ ├── common
│ ├── electromagnetics
│ ├── gslib
│ ├── meshing
│ ├── mtop
│ ├── navier
│ ├── nurbs
│ ├── performance
│ ├── shifted
│ ├── solvers
│ ├── tools
│ └── toys
└── tests
├── convergence
├── gitlab
├── par-mesh-format
├── scripts
└── unit
└── ...
Основные директории — это fem/, mesh/ и linalg/, содержащие C++ классы, реализующие концепции конечно-элементных методов, сеточной моделировки и линейной алгебры соответственно.- Основные классы сеточной моделировки:
Operator и BilinearForm
Vector и LinearForm
DenseMatrix и SparseMatrix
Параллельные объекты MPI в MFEM наследуют своих последовательных аналогов, так что параллельная сетка, например, представляет собой последовательную сетку на каждом процессе плюс информацию о совместно используемых геометрических сущностях между различными задачами. Файлы исходного кода параллельной реализации имеют префикс p, например, pmesh.cpp против последовательного mesh.cpp.
DeviceMemoryManagerMFEM_FORALL
cuda.hpp и occa.hpp
general/ находятся C++ классы, служащие в качестве утилит для связи, обработки ошибок, массивов, таблиц логических значений, временных меток и т.д.config/ содержит файлы, связанные с процессом сборки, как для простого Makefile, так и для вариантов сборки с использованием CMake.doc/ содержит конфигурацию для документации кода MFEM с помощью Doxygen, которая может быть собрана локально или просмотрена онлайн по адресу https://mfem.github.io/doxygen/html/index.html.#### Примеры и тестыexamples и miniapps соответственно собирают простые и более полнофункциональные
демонстрации использования MFEM. Оба они используют данные из директории data/
для коллекции сеток.tests/ содержит набор единичных тестов и будет позже содержать больше
тестов, запускаемых примерами кода.См. также раздел Обзор кода на сайте MFEM.
Основной центр разработки проекта MFEM находится в организации MFEM на GitHub: https://github.com/mfem.
Если вы планируете делать вклады или хотите следить за изменениями в коде, мы настоятельно рекомендуем вам вступить в организацию MFEM.
Это упростит рабочий процесс (предоставив вам дополнительные права доступа) и позволит нам непосредственно обращаться к вам с объявлениями о проектах.
Для начала работы вам необходим аккаунт на GitHub, вот несколько советов:
Новая функция должна быть достаточно важной, чтобы хотя бы один человек, автор, был готов работать над ней и стать её приверженцем.
Автор создаёт ветку для новой функции (с суффиксом -dev) от основной ветки (master) или существующей ветки функции, например:
# Клонируем, предполагая, что вы настроили свои SSH-ключи на GitHub:
git clone git@github.com:mfem/mfem.git
``` # Альтернативно, клонируем с помощью протокола "https":
git clone https://github.com/mfem/mfem.git
# Создаём новую ветку функции, начиная с "master":
git checkout master
git pull
git checkout -b feature-dev
# Работаем над "feature-dev", добавляем локальные коммиты
# ...
# (Однократно) отправляем ветку на GitHub и настраиваем вашу локальную
# ветку для отслеживания ветки на GitHub (для "git pull"):
git push -u origin feature-dev
Мы предпочитаем создание новой ветки функции внутри организации MFEM вместо создания форка. Это позволяет всем участникам сообщества сотрудничать в одном центральном месте.
Если вам удобнее работать в своём форке, пожалуйста, включите редактирование upstream.
Ни в коем случае не используйте ветку next для начала новой ветки функции!
Обычное имя для ветки функции — new-feature-dev, например pumi-dev. Хотя это нечастый случай в MFEM, возможны и другие суффиксы, например -fix, -doc и т.д.
Хорошо спроектированный простой код часто является более универсальным и мощным.
Компактная база кода легче понимается новыми участниками.
Новые функции должны добавляться только если они необходимы или полезны в общем.
Введение конструкций языка, которые не используются в настоящее время в MFEM, должно быть обосновано и обычно избегаться (для обеспечения совместимости со различными системами и компиляторами, включая ранние версии аппаратного обеспечения).
Мы предпочитаем базовый C++ и стандарт C++03, чтобы сделать код доступным для широкого круга читателей и гарантировать его сборку на любом устройстве.
Сохраните код общим и достаточно эффективным.
#ifdef
и не менять код по умолчанию.Конкретика кода
make style в верхнем уровне директории. Это требует Artistic Style (мы конкретно используем версию Yöntem 2.05.1). Также обратитесь к файлу config/mfem.astylerc.mfem::out и mfem::err вместо std::cout и std::cerr в внутреннем коде библиотеки. (Вы можете использовать std в примерах и мини-приложениях.)Когда ваша ветка готова для проверки другими разработчиками, создайте запрос на вытягивание к mfem:master.
Запросы на вытягивание обычно имеют названия типа: Описание [новая-функциональность-разработка]
Например:
Интеграция параллельной неструктурированной сетки (PUMI) [pumi-dev]
Обратите внимание на суффикс имени ветки (в квадратных скобках).
Название может содержать префикс в квадратных скобках для акцентирования типа запроса на вытягивание. Общие варианты: [НЕ_МЕРЖИТЬ], [РАБОЧАЯ_ВЕРСИЯ] и [ДЛЯ_ДИСКУССИИ]. Например:
[ДЛЯ_ДИСКУССИИ] Гибридизация DG [hdg-dev]
Если запрос на вытягивание ещё находится в процессе разработки, добавьте метку РАБОЧАЯ_ВЕРСИЯ к нему и опционально префикс [РАБОЧАЯ_ВЕРСИЯ] в название.
Добавьте описание, подходящие метки и назначьте себе этот запрос на вытягивание. Команда MFEM добавит рецензентов по мере необходимости.
Перечислите незавершённые задачи TODO в описании, см. PR #222 для примера.
Когда ваш вклад полностью работает и готов к проверке, добавьте метку готов_к_проверке.
Внесённые изменения рассматриваются аналогично публикациям в журнале с назначением "редактором" двух рецензентов для оценки правок. Рецензенты имеют три недели на оценку запроса на вытягивание (pull request) и сотрудничество с автором для внедрения улучшений и исправления проблем.
Как только метка ready-for-review применена и назначены рецензенты, pull request считается находящимся на рассмотрении. Для помощи в процессе рецензирования в ветке не должно быть принудительных перезаписей истории.- После одобрения pull request проверяется неделю вместе с другими одобренными pull requests в ветке mfem:next.
Рассмотрите возможность выполнения тестов в tests/scripts перед слиянием в mfem:next. Подробнее см. файл README в этой директории.
Отслеживайте сборки GitHub Actions и Appveyor непрерывной интеграции в конце pull request. Эти сборки обычно должны проходить успешно, поэтому исправляйте любые ошибки как можно скорее. Обращайтесь за помощью, если вы не уверены, как это сделать.
Учитывайте, что некоторые тесты, такие как проверка branch-history в GitHub Actions, являются средствами защиты, которые могут допускаться к провалу в некоторых случаях.
Другие тесты, такие как проверки code-style, documentation и gitignore в GitHub Actions, применяют правила, специфичные для MFEM, которые объясняются в сообщениях об ошибках и в директории tests/scripts.
Также обратите внимание, что тесты branch-history и repos-checks, найденные в GitHub Actions, могут автоматически запускаться перед каждым коммитом с помощью git hooks. Подробное объяснение см. в файле README для git hooks.
Если эти тесты запущены, отслеживайте состояние сборок LLNL GitLab. При провале обращайтесь к одному из разработчиков LLNL за подробностями.
make style.CHANGELOG:
CHANGELOG, чтобы объединить его с другими связанными функциями?INSTALL:
make или cmake?.github
.appveyor.yml
.gitignore:
make distclean; git status какие-либо файлы, сгенерированные проектом из исходного кода (не IDE), но которые мы не хотим отслеживать в репозитории.examples/makefile:
SEQ_EXAMPLES и PAR_EXAMPLES.clean..gitignore верхнего уровня.examples/CMakeLists.txt:
ALL_EXE_SRCS.THIS_TEST_OPTIONS правильно установлена для нового примера.doc/CodeDocumentation.dox.examples/pumi), укажите его в doc/CodeDocumentation.conf.in.src/examples.md.src/examples.md и src/img.examples.md, укажите пример под соответствующими категориями, добавьте новые категории при необходимости.features.- [ ] Новые мини-приложения:
- [ ] Все образцы запуска в начале файла исходного кода мини-приложения работают корректно.
- [ ] Обновите основной файл `makefile` и файл `makefile` в соответствующей директории мини-приложения.
``` - [ ] Добавьте исполняемый файл мини-приложения и любые сгенерированные им файлы в основной файл `.gitignore`.
- [ ] Обновите систему сборки CMake:
- [ ] Обновите файл `CMakeLists.txt` в директории `miniapps`, если новое мини-приложение находится в новой директории.
- [ ] Добавьте/обновите файл `CMakeLists.txt` в новой директории мини-приложения.
- [ ] Рассмотрите возможность добавления нового теста для нового мини-приложения.
- [ ] Укажите новое мини-приложение в файле `doc/CodeDocumentation.dox`.
- [ ] Если создана новая директория мини-приложений (например, `miniapps/nurbs`), добавьте её в `MINIAPP_SUBDIRS` в файле `makefile`.
- [ ] Если создана новая директория мини-приложений (например, `miniapps/nurbs`), укажите её в файле `doc/CodeDocumentation.conf.in`.
- [ ] Воплощение запроса на слияние документации в репозитории [mfem/web](https://github.com/mfem/web):
- [ ] Обновите или добавьте специфическую для мини-приложения документацию, см., например, файлы `src/meshing.md` и `src/electromagnetics.md`.
- [ ] Добавьте описание, метки и скриншоты в файл `src/examples.md` и папку `src/img`.
- [ ] Мини-приложения располагаются в конце страницы и обычно указываются только под конкретной категорией "Приложение (Уравнение в частных производных)".
- [ ] Добавьте краткое описание мини-приложения в разделе "Примеры" файла `features.md`.
- [ ] Новая способность:
- [ ] Все значимые новые классы, методы и функции имеют документацию в стиле Doxygen в комментариях исходного кода. - [ ] Рассмотрите возможность добавления новых образцов запусков в существующие примеры для выделения новой способности.
- [ ] Рассмотрите возможность сохранения интересных снимков экрана с новой способностью в галерею Confluence (только LLNL) или отправки их через запрос на слияние в раздел галереи репозитория `mfem/web`.
- [ ] Если это важная новая функциональность, рассмотрите возможность упоминания её в кратком описании внутри файла `README` (редко).
- [ ] Укажите важные новые классы в файле `doc/CodeDocumentation.dox` (редко).
- [ ] Обновите этот список проверок, если новый запрос на слияние затрагивает его.
- [ ] Выполните команду `make unittest`, чтобы убедиться, что все юнит-тесты проходят успешно.
- [ ] Выполните тесты в директории `tests/scripts`.
- [ ] (только LLNL) После слияния:
- [ ] Обновите внутренние тесты для включения новых возможностей.
```Это точный перевод текста, сохраняющий исходное форматирование и разметку.
### Основной/Следующий рабочие ветви
MFEM использует модель работы с основной (`master`) и следующей (`next`) ветвями, как это описано ниже:
- Ветка `master` всегда должна быть качественной версией выпуска, и изменения должны быть внесены только после полного тестирования. Эта ветка защищена, и изменения могут быть сделаны только через запросы на слияние (pull requests).
- После одобрения запрос на слияние вручную (разработчиками MFEM) объединяется в ветку `next` для тестирования, а метка `in-next` добавляется к запросу. Это можно сделать следующим образом:
```bash
# Получите последнюю версию ветки "feature-dev"
git checkout feature-dev
git pull
# Получите последнюю версию ветки "next"
git checkout next
git pull
# Объедините "feature-dev" в "next", разрешив конфликты, если они есть.
# Используйте флаг "--no-ff", чтобы создать новый коммит со сообщением о слиянии.
git merge --no-ff feature-dev
# Отправьте ветку "next" на сервер
git push
После недели тестирования в ветке next (исключая исправления ошибок), как на GitHub, так и внутри LLNL, оригинальный запрос на слияние объединяется в ветку master, при условии отсутствия проблем.
После слияния, ветка функциональности удаляется (за исключением долгосрочных проектов с периодическими запросами на слияние).- Ветка next используется только для интеграционного тестирования всех запросов на слияние, одобренных для объединения в master, чтобы проверить работоспособность каждого запроса отдельно и совместную работу всех вместе. Эта ветка может быть удалена в любое время, хотя мы обычно делаем это только в конце цикла выпусков.
Выпуски представляют собой теги в ветке master, например https://github.com/mfem/mfem/releases/tag/v3.3.2, и имеют номер версии, заканчивающийся четным "патчем", например v3.2.2 или v3.4 (по соглашению v3.4 эквивалентно v3.4.0). Между выпусками номер версии заканчивается нечетным "патчем", например v3.3.3.
Мы используем майлстоун для координации работы над различными запросами на слияние перед выпуском, см., например, выпуск v3.3.2.
После завершения выпуска, ветка next воссоздается, например, следующим образом (замените 3.3.2 текущим выпуском):
next в next-pre-v3.3.2.next, начав с выпуска v3.3.2.next затем могут быть обновлены командой git fetch origin next && git checkout -B next origin/next.### Список проверок выпуска- [ ] Обновите версию MFEM в следующих файлах:
CHANGELOG
makefile
CMakeLists.txt
doc/CodeDocumentation.conf.in
Убедитесь, что требования к версиям зависимостей MFEM зафиксированы в INSTALL и актуальны
Убедитесь, что конфигурации сервера непрерывной интеграции отражают требования к версиям зависимостей нового выпуска
.github
.appveyor.yml
Обновите CHANGELOG, чтобы организовать все вклады в выпуск
Проанализируйте весь исходный код
Попросите приложения на основе MFEM протестировать предварительную версию выпуска
Протестируйте на дополнительных платформах и компиляторах
Отметьте репозиторий: ``` git tag -a v3.1 -m "Официальный выпуск v3.1" git push origin v3.1
Создайте архив выпуска и отправьте его в mfem/releases.
Пересоздайте ветку next как это описано в предыдущем разделе.
Обновите и отправьте документацию в mfem/doxygen.
Обновите URL коротких ссылок:
links и links-mfem внутреннего репозитория mfem/downloads.spack, homebrew/science, VisIt, и т.д. Обновите сайт в репозитории mfem/web:
src/index.md и src/download.md.ls -lh, чтобы оценить количество строк исходного кода (SLOC) и размер архива в src/download.md.Ветки master и next GitHub зеркалируются в институциональный репозиторий Bitbucket LLNL как gh-master и gh-next.
gh-master объединяется с внутренней веткой master через запросы на слияние; права записи на master ограничены, чтобы гарантировать, что это единственный способ обновления.- Мы никогда не отправляем изменения напрямую из LLNL на GitHub.
Версии кода на внутреннем сервере LLNL, от наиболее до наименее стабильных:
mfem:master — последняя версия разработки, гарантированно работает.mfem:gh-master — устойчивая версия разработки, прошедшая тестирование, можно использовать её для сборки вашего кода между выпусками.mfem:gh-next — новая версия разработки, может содержать ошибки, используйте на свой страх и риск.Этот экземпляр предназначен для завершения CI-тестирования с тестами на вычислительных системах Livermore Computing. Статус конвейера GitLab отображается в соответствующих запросах на пул GitHub.
В конвейерах GitLab зависимости (TPLs) собираются с помощью Spack, управляемого Uberenv.
Никакие изменения в репозитории MFEM на этом экземпляре делать нельзя.
MFEM имеет несколько уровней автоматического тестирования, выполняющегося на GitHub, а также на локальных рабочих станциях Mac и Linux, и кластерах Livermore Computing в LLNL.
Кроме того, разработчики могут установить локальные гит-хуки для выполнения некоторых быстрых проверок при коммите или пуше, см. README в директории config/githooks.
Мы используем GitHub Actions для запуска базовых тестов на ветках master и next. См. файлы .github/workflows и журналы на https://github.com/mfem/mfem/actions.
Тестирование с использованием GitHub Actions должно быть легковесным, так как существует ограничение времени на задачи. Конфигурированы две виртуальные машины — Mac (OS X) и Linux.
master запускаются всякий раз, когда создается запрос на пул на этой ветке.next запланированы для еженощного запуска.### Тесты на Windows
Мы используем Appveyor для тестирования сборки с компилятором MS Visual C++ в окружении Windows, а также для тестирования сборки CMake. См. файл .appveyor и журналы сборки на https://ci.appveyor.com/project/mfem/mfem.CMake используется для создания файлов проекта MSVC и управления сборкой. Выполняются сборка выпуска и отладочной версии с простым запуском ex1, чтобы проверить исполняемый файл.
Мы внутренне клонируем ветки master и next (к gh-master и gh-next) и выполняем более длительные еженоочные тесты через cron. По выходным дням выполняется более полный тест, который извлекает и запускает все различные примеры из каждого образца.
Мы также клонируем запросы на пул на экземпляр GitLab LLNL. Клонирование запросов на пул может быть запущено только разработчиками LLNL, но статус тестирования доступен публично. Только разработчики LLNL имеют доступ к подробному отчету о тестировании.
Для связи с командой MFEM используйте систему отслеживания проблем на GitHub. Пожалуйста, выполните поиск, чтобы удостовериться, что ваш вопрос уже был решён.
Электронные сообщения следует отправлять на почтовый список разработчиков MFEM, mfem-dev@llnl.gov.
(a) Вклад был создан полностью или частично мной, и у меня есть право представить его под лицензией открытого программного обеспечения, указанной в файле;
(b) Вклад основан на предыдущей работе, которая, по моему мнению, покрыта подходящей лицензией открытого программного обеспечения, и у меня есть право представить эту работу с изменениями (полностью или частично созданными мной) под тем же лицензионным соглашением открытого программного обеспечения (если я не имею права представить его под другой лицензией), как указано в файле;
(c) Вклад был предоставлен мне непосредственно другим лицом, которое свидетельствовало (a), (b) или (c), и я не вносил в него изменений.
(d) Я понимаю и согласен с тем, что этот проект и вклад являются общественным достоянием, а также то, что запись о вкладе (включая всю личную информацию, представленную вместе с ним, включая моё подтверждение) хранится постоянно и может быть распространена в соответствии с этим проектом или лицензией открытого программного обеспечения, применимой к нему.
Вы можете оставить комментарий после Вход в систему
Неприемлемый контент может быть отображен здесь и не будет показан на странице. Вы можете проверить и изменить его с помощью соответствующей функции редактирования.
Если вы подтверждаете, что содержание не содержит непристойной лексики/перенаправления на рекламу/насилия/вульгарной порнографии/нарушений/пиратства/ложного/незначительного или незаконного контента, связанного с национальными законами и предписаниями, вы можете нажать «Отправить» для подачи апелляции, и мы обработаем ее как можно скорее.
Опубликовать ( 0 )