8. Некоторые особенности документирования подпрограмм

8.1. Правила наименований подпрограмм

Каждая подпрограмма Комплекса имеет имя, начинающееся с буквы P. Допущено нарушение стандарта языка Фортран - 77, т.к. имена подпрограмм Kомплекса могут быть длиной более шести символов; кроме того, в именах служебных подпрограмм (tools routines) допускается использование символа подчеркивания "_".

Все целевые и базовые подпрограммы имеют имена в виде последовательности шести или семи символов:

      PXYYZZ    или    PXYYZZZ , 

где второй символ X указывает на тип обрабатываемых данных:

      S    REAL
      D    DOUBLE PRECISION
      C    COMPLEX
      Z    DOUBLE COMPLEX 

Когда мы хотим сослаться на подпрограммы комплекса вообще, независимо от типа обрабатываемых данных, мы заменяем вторую букву в имени маленькой буквой "x". Таким образом, PxGESV означает, что мы имеем в виду все или любую из подпрограмм PSGESV, PCGESV, PDGESV и PZGESV.

Следующие две буквы YY указывают на то, какого вида матрица обрабатывается подпрограммой (или вид самой главной из участвующих матриц). Большинство из этих двухсимвольных сочетаний относятся одновременно как к вещественным, так и к комплексным матрицам, некоторые же относятся конкретно к одному из этих типов матриц. Приняты следующие мнемонические правила для указания вида обрабатываемых матриц:

Когда мы хотим сослаться на подпрограммы, выполняющие одни и те же действия над матрицами разных видов, мы заменяем в имени второй, третий и четвертый символы тремя маленькими буквами "xyy". Так PxyySV означает ссылку на все целевые подпрограммы, решающие системы линейных уравнений.

Последние два ZZ или три ZZZ символа в имени подпрограммы указывают ее назначение. Например, окончание TRF означает подпрограммы, которые выполняют факторизацию матриц.

Имена вспомогательных подпрограмм подчиняются тем же правилам, за исключением того, что третьим и четвертым символом YY обычно являются символы LA (например, PDLASCL или PZLARFG).

8.2. Описания программ Комплекса и примеры их использования.

Документация Комплекса параллельных программ по линейной алгебре включает в себя:

• информацию общего характера (об организации и структуре Комплекса и об общих правилах использования программ Комплекса и размещения данных);
• систематический каталог целевых программ;
• описания целевых программ Комплекса (т.е. инструкции по их использованию).

Документация общего характера приводится как в рамках настоящего методического пособия, так и в соответствующих подразделах раздела "Комплекс программ по линейной алгебре для вычислений на распределенной памяти" научно - образовательного Интернет - ресурса НИВЦ МГУ по численному анализу (http://www.srcc.msu.su/num.anal/). Там же приводится Систематический каталог целевых программ Комплекса в виде таблиц, содержащих, в частности, гипер - ссылки на описания программ.

Описания программ составлялись во многом по аналогии с тем, как это было ранее разработано и реализовано в Библиотеке фортранных программ по численному анализу НИВЦ МГУ [3], которая состоит из обычных последовательных алгоритмов.

Такая четкая форма документации, состоящая из нескольких обязательных смысловых разделов, заслужила широкое одобрение среди многочисленных пользователей Библиотеки численного анализа, в течение многих лет эксплуатировавших ее в разных организациях и на разных вычислительных системах.

Одним из самых важных разделов в описании каждой целевой программы является его последний раздел под названием "Пример использования". Содержание этого раздела на примере матриц небольшого размера наглядно демонстрирует пользователю, как будут распределены их элементы по параллельным процессам, и как такое распределение можно реализовать средствами языка ФОРТРАН и служебных подпрограмм. А именно: приводится фрагмент головной фортранной программы (теста), с подпрограммой рассылки элементов конкретной матрицы по параллельным процессам одним из трех способов, рассматриваемых в настоящем пособии. Указанные подпрограммы рассылки имеют в примерах либо имя MATINIT, либо - PDMATINIT.

Три способа реализации на языке ФОРТРАН рассылки элементов исходных матриц по параллельным процессам рассматриваются в настоящем пособии (см. п.6.3.).

8.3. Обозначения и упрощения в примерах по использованию подпрограмм Комплекса.

В тестовых примерах и примерах по использованию подпрограмм комплекса приняты следующие стандартные обозначения величин, задающих параметры исходной задачи и выбранный способ распараллеливания (указаны в алфавитном порядке).

Опишем далее некоторые упрощения и ограничения, которые были сделаны при подготовке примеров использования подпрограмм комплекса, для того чтобы упростить пользователю освоение правил работы с этими подпрограммами.

1. В примерах предполагается, что RSRC = CSRC = 0, что означает, что исходные матрицы  A (и  B) распределяются по решетке процессов, начиная с процесса (0, 0). На самом деле, любой из процессов решетки может быть выбран в качестве начального при распределении матриц.

2. В примерах предполагается, что задача решается при использовании всей исходной распределенной матрицы  A (хотя подпрограммы допускают, чтобы задачи решались с матрицей, являющейся подматрицей sub (A) исходной матрицы  A). При указанном предположении параметры, задающие первый элемент подматрицы  A, полагаются равными 1, т.е.  IA = JA = IB = JB = 1. См. п.5.3.

3. При распределении исходных матриц  A по решетке процессов используется подпрограмма MATINIT (см. конец Приложения 2_1), которая заносит с помощью операторов присваивания в соответствующие локальные массивы на каждом из процессов решетки распределенные на него элементы исходных матриц. Упрощает эту процедуру использование служебной подпрограммы PDELSET (см. п.6.3 и конец Приложения 2_2).

4. В примерах предполагается, что ведущая локальная размерность локальных частей матрицы  A и ведущая локальная размерность локальных частей матрицы (вектора)  B являются теми же самыми (одинаковыми) для всех процессов, принадлежащих к одним и тем же строкам решетки процессов (т.е. имеющих одинаковые координаты строк решетки). Переменная MXLLDA равна максимальной ведущей локальной размерности для матрицы  A (обозначаемой LLD_A) из всех строк решетки процессов. Точно так же переменная MXLLDB равна максимальной локальной ведущей размерности для матрицы  B (обозначаемой LLD_B) из всех строк решетки процессов. Однако в общем случае локальные ведущие размерности локальных частей матриц могут отличаться друг от друга для всех процессов решетки.

5. В примерах рассматриваются исходные матрицы  A и  B небольших размеров. При этом размеры блоков, на которые разбиваются эти матрицы, выбираются небольшими. Например, в тесте к подпрограмме, решающей систему уравнений с плотной матрицей (PDGESV.f ),  MB = NB = 2. Однако это не является самым лучшим размером блоков для практических задач. Для достижения лучшей производительности более подходящим размером блоков будет  MB = NB = 32 или  MB = NB = 64.