4. Fortran API
本文档介绍NECP-X的Fortran API，包括建模功能，固定源求解功能，特征值求解功能，燃耗求解功能，瞬态 求解功能，并给出使用指南和使用样例。
4.1. API模块概述
API共有五个模块对外开放，由Fortran语言编制
| Modules |
Functions |
| model_api |
建模 |
| fsp_solver_api |
固定源求解器 |
| eigenvalue_solver_api |
特征值求解器 |
| multiState_solver_api |
多状态点求解器 |
transient_solver_api |
瞬态求解器 |
4.2. 各个模块具体功能介绍
每个模块均包含 主体函数，set系列函数 和 get系列函数。
主体函数 为实现模块功能的必需函数; set系列函数 主要功能为重新设置计算参数; get系列函数 主要功能为获得计算结果。 以下函数介绍格式为:
function(*args)
功能描述
arg: |
s (dimension), datetype(attribute) s 参数详细介绍 |
注: API所有浮点数均为 双精度，下面不再赘述。 推荐函数的参数均用 显式指定。
下文出现的数组维度变量含义:
| 维度变量 |
含义 |
| ig |
能群编号 |
| igg |
散射接收能群编号 |
| iamt |
材料区编号 |
| ipin |
径向栅元编号 |
| iasy |
径向组件编号 |
| iz |
轴向层编号 |
| i_trans_step |
某一扰动中瞬态时间步编号 |
dg |
缓发中子组数编号 |
4.2.1. model_api 模块
本模块主要功能为 建模与画图，具体包含以下几个函数：
Init(only_plot)
建模初始化
only_plot: |
s logical(in, optional) s 指定是否只进行画图功能。若only_plot=.true.，只进行几何初始化，仅能使 用plot和clear函数；若only_plot=.false.，进行几何、材料、网格等的初 始化，可以同时进行画图和计算 s 缺省默认为.false. |
Plot(plot_type)
模型画图
plot_type： |
s character(in) s 指定画图类型，有’2d’, ‘3d’, ‘ppm’三种 |
Set_xs(ng, xs_tr, xs_sc, xs_nf, xs_nf, xs_ch)
自定义材料区的宏观截面
ng： |
s integer(in) s 能群数 |
xs_tr(:,:) |
s (ig, imat), real(in) s 输运截面 |
xs_sc(:,:,:) |
s (ig -> iig, imat), real(in, optional) s 散射矩阵 s 缺省为零 |
xs_nf(:,:) |
s (ig, imat), real(in, optional) s 中子产生截面 s 缺省为零 |
xs_kf(:,:) |
s (ig, imat), real(in, optional) s 能量产生截面 s 缺省为零 |
xs_ch(:,:) |
s (ig, imat), real(in, optional) s 能谱χ s 缺省为零 |
Clear()
清除建模信息和内存
Get_matreg_num(n_matreg)
获得材料区总数
n_matreg |
s integer(out) s 材料区数，并行时，每个cpu各自输出 |
Get_matreg_vol(matreg_vol)
获得每个材料区体积
matreg_vol(:) |
s integer(out) s 材料区数，并行时，每个cpu各自输出 |
4.2.2. fsp_solver_api 模块
本模块主要功能为 固定源问题 求解，具体包含以下几个函数：
Init()
固定源求解器初始化
Set_q(q_ext)
设置固定源项
q_ext(:,:) |
s (ig, imat), real(in) s 每个材料区的源项 |
Set_option(phi_criteria, max_iter)
设置固定源问题计算条件
phi_criteria |
s real(in, optional) s 迭代收敛限 s 缺省为1e-03 |
max_iter |
s integer(in, optional) s 最大迭代次数 s 缺省为500 |
Solve()
固定源问题求解
Clear()
清除此固定源问题
Get_flux(phi_s)
获得各能群各材料区的标通量
phi_s(:,:) |
s (ig, imat), real(out) s 每个材料区的标通量，并行时每个cpu各自输出 |
4.2.3. eigenvalue_solver_api 模块
本模块主要功能为 特征值问题 求解，具体包含以下几个函数：
Init()
特征值求解器初始化
Set_option(k_criteria, max_outer...)
重新设置特征值问题计算条件
args |
s integer/real(in, optional) s 与输入卡 option block 中的 iteration card 意义相同 s 缺省即为输入卡值 |
Solve()
特征值问题求解
Clear()
清除此特征值问题
Get_keff(keff)
获得特征值
Get_flux(phi_s)
获得各能群各材料区的标通量
phi_s(:,:) |
s (ig, imat), real(out) s 标通量，并行时每个cpu各自输出 |
Get_pinPower(pinPower)
获得各pin的功率
pinPower(:,:,:) |
s (ipin, iasy, iz)，real(out) s 每个pin的功率。空间区域分解时， iz为全局层高编号，iasy为当前cpu径向负责的组件中的局 部编号，ipin为组件中的局部pin编号 s 注: 要求用户知晓每个cpu负责哪一部分组件 s 注: 四分之一组件模块化时，会出现在一个CPU中包括不同大小的组件（如下图CPU0和CPU3）， 这时ipin为1到最大组件中的pin数量。四分之一或二分之一pin，即为其四分之一或二分之一功率 |
例: 空间区域分解时：四分之一堆芯，四分之一组件模块化，径向3个CPU，轴向2个CPU，共6个CPU，不同CPU负责的区域如下：
轴向(上图)与径向(下图)CPU分解
pinPower(ipin, iasy, iz):
CPU0: iz=1~2 iasy=1~2 ipin=1~153(9*17)
CPU1: iz=1~2 iasy=1 ipin=1~153(9*17)
CPU2: iz=1~2 iasy=1 ipin=1~289(17*17)
CPU3: iz= 3 iasy=1~2 ipin=1~153(9*17)
CPU4: iz= 3 iasy=1 ipin=1~153(9*17)
CPU5: iz= 3 iasy=1 ipin=1~289(17*17)
Get_pinPower_density(pinPower_density)
获得各pin的功率密度
pinPower_density(:,:,:) |
s (ipin, iasy, iz)，real(out) s 每个pin的功率密度。并行时各维度意义同上 |
Get_asyPower(asyPower)
获得各组件的功率
asyPower(:,:) |
s (iasy, iz), real(out) s 每个组件的功率。并行时各维度意义同上 s 注：四分之一组件模块化时，在四分之一或二分之一组件上，即为其四分之一或二分之一功率 |
Get_asyPower_density(asyPower_density)
获得各组件的功率密度
asyPower_density(:,:) |
s (iasy, iz), real(out) s 每个组件的功率密度。并行时各维度意义同上 |
4.2.4. multistate_solver_api 模块
本模块主要功能为 多状态点问题 求解，具体包含以下几个函数：
Init()
多状态求解器初始化
Set_depletion_optional(power_density, power_history, burn_step...)
重新设置燃耗计算参数
args |
s integer/real(in, optional) s 与输入卡 option block 中的 depletion card 意义相同 s 缺省即为输入卡值 |
Set_multicyle_optional(upd_th_frqcy, upd_xe_frqcy, upd_cb_frqcy, max_outer)
重新设置热工，氙平衡，临界硼搜索计算参数
args |
s integer/real(in, optional) s 与输入卡 option block 中的 multi_cycle card 意义相同 s 缺省即为输入卡值 |
Set_transport_option(k_criteria, max_outer...)
重新设置特征值问题计算条件
args |
s integer/real(in, optional) s 与输入卡 option block 中的 iteration card 意义相同 s 缺省即为输入卡值 |
preprocess()
多状态点计算之前的预处理，包括调取参数等
deal_burnup(burn_count)
处理burn_count这一步的燃耗点，设置一些参数
burn_count |
s integer(in) s 燃耗点编号 |
steady_step()
进行一步稳态计算（中子学或多循环计算，视卡片而定）
neutronics_step()
仅进行一步中子学计算
multicycle_step()
仅进行一步多循环计算
calc_write_power()
计算功率，并输出到文件
depletion_step()
更新截面并进行一步燃耗计算
clear()
清除此多状态点问题
Judge_correct_step(correct_step)
判断是否为校正步，用于判断是否进行燃耗步的递进
correct_step |
s logical(out) s 是否为校正步，若为校正步，则为.ture. |
Get_coupling_method(coupling_method)
获得耦合方法，用于判断是否进行燃耗步的递进
coupling_method |
s integer(out) s 耦合方法，如果为1，不进行预估校正，燃耗点将会步进 |
Get_burnstep_num(burnstep_num)
获得一共多少燃耗点
burnstep_num |
s integer(out) s 燃耗点个数 |
Get_burnup(burnup)
获得这一步的燃耗
burnup |
s integer(out) s 这一步的燃耗 |
Get_keff(keff)
获得这一状态点的特征值
Get_flux(phi_s)
获得这一状态的标通量
phi_s(:) |
s 同 eigenvalue_solver_api 模块 |
Get_pinPower(pinPower)
获得这一状态点的pin功率
pinPower(:,:,:) |
s 同 eigenvalue_solver_api 模块 |
Get_pinPower_density(pinPower_density)
获得这一状态点的pin功率密度
pinPower_density(:,:,:) |
s 同 eigenvalue_solver_api 模块 |
Get_asyPower(asyPower)
获得这一状态点的组件功率
asyPower(:,:) |
s 同 eigenvalue_solver_api 模块 |
Get_asyPower_density(asyPower_density)
获得这一状态点的组件功率密度
asyPower_density(:,:) |
s 同 eigenvalue_solver_api 模块 |
Get_matBurn(imat, mat_burnup)
获得这一状态点的指定材料区的燃耗
imat |
s integer(in) s 材料区编号 s 注: 空间区域分解的时候，需要用户知道不同CPU的材料区编号 |
mat_burnup |
s real(out) s 此材料区的燃耗。若此材料区不为燃耗材料，则输出为零 |
Get_b(imat, n_nuclide, nucl_id, nucl_dens)
获得这一状态点的指定材料区的核素密度
imat |
s integer(in) s 材料区编号 s 注: 空间区域分解的时候，需要用户知道不同CPU的材料区编号 |
n_nuclide |
s real(out) s 核素数量 |
| nucl_id(:) |
s (i_nuclide), real(out) s 核素id |
| nucl_dens(:) |
s (i_nuclide), real(out) s 核子密度 |
4.2.5. transient_solver_api 模块
本模块主要功能为 瞬态问题 求解，具体包含以下几个函数：
init()
瞬态求解器初始化
steady_presolve()
进入瞬态前的稳态计算，CMFD共轭通量等
set_deltaT(iperb, deltaT)
自定义某一扰动的瞬态时间步
iperb |
s integer(in) s 输入卡中的扰动编号 |
deltaT(:) |
s (i_trans_step), real(in) s 这一扰动的瞬态时间步 s 注：时间步之和必须等于此扰动的时间跨度 |
Set_transport_option(k_criteria, max_outer...)
重新设置输运问题计算条件
args |
s integer/real(in, optional) s 与输入卡 option block 中的 iteration card 意义相同 s 缺省即为输入卡值 |
deal_perb(iperb)
处理这一步扰动信息
iperb |
s integer(in) s 扰动编号 |
neutronics_step(i_trans_step)
进行一步中子学计算
i_trans_step |
s integer(in) s 某一扰动的瞬态时间步编号，从1开始 |
feed_back()
进行一步热工计算
clear()
清除此瞬态问题
Get_nPerb(n_perb)
获得总的扰动个数
n_perb |
s integer(out) s 扰动总数 |
Get_nTransStep(i_perb, n_trans_step)
获得某个扰动的瞬态时间步个数
i_perb |
s integer(in) s 扰动编号 |
n_trans_step |
s integer(out) s 瞬态时间步个数 |
Get_init_power(init_power)
获得初始绝对功率
init_power |
s real(out) s 初始绝对功率 |
Get_rela_power(rela_power)
获得每个瞬态步对于初始的相对功率
rela_power |
s real(out) s 相对功率 |
Get_reactivity(reactivity)
获得初始稳态或每个瞬态步的反应性
reactivity |
s real(out) s 反应性 |
Get_total_beta(total_beta)
获得初始稳态或每个瞬态步的所有缓发中子的总份额
total_beta |
s real(out) s 所有缓发中子的总份额 |
Get_partial_lamda(partial_lamda)
获得初始稳态或每个瞬态步各组缓发中子的衰变常数
partial_lamda(:) |
s (dg), real(out) s 各组缓发中子先驱核的衰变常数 |
Get_generation_time(generation_time)
获得初始稳态或每个瞬态步的中子代时间
generation_time |
s real(out) s 中子代时间 |
Get_keff(keff)
获得 steady_presolve 后的特征值
Get_flux(phi_s)
获得这一瞬态步的标通量
phi_s(:) |
s 同 eigenvalue_solver_api 模块 |
Get_pinPower(pinPower)
获得这一瞬态步的pin功率
pinPower(:,:,:) |
s 同 eigenvalue_solver_api 模块 |
Get_pinPower_density(pinPower_density)
获得这一瞬态步的pin功率密度
pinPower_density(:,:,:) |
s 同 eigenvalue_solver_api 模块 |
Get_asyPower(asyPower)
获得这一瞬态步的组件功率
asyPower(:,:) |
s 同 eigenvalue_solver_api 模块 |
Get_asyPower_density(asyPower_density)
获得这一瞬态步的组件功率密度
asyPower_density(:,:) |
s 同 eigenvalue_solver_api 模块 |
4.3. 使用指南与样例
所有功能均在 api_function 模块中。在调用necpx功能前请引用这一模块， 并 实例化 一个necpx对象:
use api_functions
TYPE(necpx_api_functions_type) :: necpx
4.3.1. 建模与画图
计算任何问题的开始，必须进行 建模初始化，以生成问题的几何，网格，材料，特征线等信息。若 不再使用necpx的功能，必须释放模型的内存。模型初始化后，可以进行画图等操作
例:
program necpx_main
use api_functions
! 实例化
TYPE(necpx_api_functions_type) :: necpx
integer :: n_matreg
! 建模初始化
call necpx%model_api%init()
! 画图
call necpx%model_api%plot('2d')
call necpx%model_api%plot('ppm')
! 获得材料区总数
call necpx%model_api%get_matreg_num(n_matreg)
! 清除内存
call necpx%model_api%clear()
end program necpx_main
4.3.2. 固定源问题
若自定义宏观截面，不论卡片中的library类型，问题都会转化为宏观问题。必须指定 输运截面xs_tr，若其他 截面缺省，将会设为零。固定源问题的开始需要进行固定源求解器的初始化，然后设置源，设置迭代参数（若不设置则为缺省值）进行求解。
支持同一张卡片几何下 多次求解固定源问题 . 在清除求解器内存后，重新设置截面，初始化求解器，设置源进行计算。计算结束后需释放求解器和模型的内存。
注：设置材料截面必须在初始化求解器之前
例:
program necpx_main
use api_functions
! 实例化
TYPE(necpx_api_functions_type) :: necpx
integer :: n_matreg
integer :: ng = 1968
integer :: imat, ig
real(8), allocatable :: q_tol(:,:), xs_tr(:,:), flux(:,:)
real(8), allocatable :: matreg_vol(:)
! 读取外源和截面
OPEN(unit=150, file='/root/necp-x-api/fsp_case/fort.150', &
status='old', action='read', iostat=ierror)
OPEN(unit=151, file='/root/necp-x-api/fsp_case/fort.151', &
status='old', action='read', iostat=ierror)
call necpx%model_api%init()
call necpx%model_api%get_matreg_num(n_matreg)
ALLOCATE(q_tol(ng, n_matreg))
ALLOCATE(xs_tr(ng, n_matreg))
do imat = 1, n_matreg
do ig = 1, ng
read(150, *) xs_tr(ig, imat)
read(151, *) q_tol(ig, imat)
enddo
enddo
! 设置截面
call necpx%model_api%set_xs(ng=ng, xs_tr=xs_tr)
! 固定源求解器初始化
call necpx%fsp_solver_api%init()
! 设置外源和迭代参数
call necpx%fsp_solver_api%set_q(q_tol)
call necpx%fsp_solver_api%set_option(phi_criteria=1d-03, max_iter=100)
! 固定源求解
call necpx%fsp_solver_api%solve()
! 获得计算结果
call necpx%fsp_solver_api%get_flux(flux)
! 清除求解器内存
call necpx%fsp_solver_api%clear()
! 重新读取一套截面
OPEN(unit=250, file='/root/necp-x-api/fsp_case/fort.250', &
status='old', action='read', iostat=ierror)
OPEN(unit=251, file='/root/necp-x-api/fsp_case/fort.251', &
status='old', action='read', iostat=ierror)
ALLOCATE(q_tol(ng, n_matreg))
ALLOCATE(xs_tr(ng, n_matreg))
do imat = 1, n_matreg
do ig = 1, ng
read(250, *) xs_tr(ig, imat)
read(251, *) q_tol(ig, imat)
enddo
enddo
! 再次求解
call necpx%model_api%set_xs(ng=ng, xs_tr=xs_tr)
call necpx%fsp_solver_api%init()
call necpx%fsp_solver_api%set_q(q_tol)
call necpx%fsp_solver_api%solve()
! 获得计算结果
call necpx%fsp_solver_api%get_flux(flux)
! 清除求解器内存
call necpx%fsp_solver_api%clear()
! 退出API
call necpx%model_api%clear()
end program necpx_main
4.3.3. 特征值问题
特征值问题与固定源问题类似，支持 自定义截面，设置迭代条件 （若不 设置则为卡片值），同一张卡片下特征值问题 多次计算
例:
program necpx_main
use api_functions
! 实例化
TYPE(necpx_api_functions_type) :: necpx
real(8) :: keff
real(8), allocatable :: flux(:,:)
real(8), allocatable :: pinPower(:,:,:), pinPower_density(:,:,:)
real(8), allocatable :: asyPower(:,:), asyPower_density(:,:)
! 初始化
call necpx%model_api%init()
call necpx%model_api%plot('2d')
call necpx%eigenvalue_solver_api%init()
! 特征值问题求解
call necpx%eigenvalue_solver_api%set_option(max_outer=200, max_inner=1)
call necpx%eigenvalue_solver_api%solve()
! 获得计算结果
call necpx%eigenvalue_solver_api%get_keff(keff)
call necpx%eigenvalue_solver_api%get_flux(flux)
call necpx%eigenvalue_solver_api%get_pinPower(pinPower)
call necpx%eigenvalue_solver_api%get_pinPower_density(pinPower_density)
call necpx%eigenvalue_solver_api%get_asyPower(asyPower)
call necpx%eigenvalue_solver_api%get_asyPower_density(asyPower_density)
! 释放内存
call necpx%eigenvalue_solver_api%clear()
call necpx%model_api%clear()
end program necpx_main
4.3.4. 燃耗问题
燃耗问题初始化后，必须进行 预处理，以获得一些计算参数。 然后设置输运迭代条件和燃耗计算参数（若不设置则为卡片值）。
进入燃耗遍历，每一步燃料点中，必须进行 燃耗点处理，稳态步 （包括中子学和热 工反馈）, 燃耗步。 燃耗点的步进是由 校正步 判断，每次校正步后燃耗点都会递进一步。 此外，若使用的耦合方法 coupling_method=npc, 不会进行预估校正计算，求解一次燃耗点后步进。
例:
program necpx_main
use api_functions
! 实例化
TYPE(necpx_api_functions_type) :: necpx
logical :: is_depletion = .true.
logical :: correct_step = .true.
integer :: burn_count, burnstep_num, coupling_method, n_nuclide
character(len=20), allocatable :: nucl_id(:)
real(8) :: keff, burnup, mat_burnup
real(8), allocatable :: nucl_dens(:)
real(8), allocatable :: burn_step(:)
allocate(burn_step(5))
burn_step = (/0.01d0, 0.25d0, 0.5d0, 1.0d0, 2.0d0/)
! 初始化
call necpx%model_api%init()
call necpx%multiState_solver_api%init()
! 预处理
call necpx%multiState_solver_api%preprocess()
! 设置计算参数
call necpx%multiState_solver_api%set_transport_option(max_outer=2)
call necpx%multiState_solver_api%set_depletion_option(burn_step=burn_step)
! 开始燃耗遍历
burn_count = 1
call necpx%multiState_solver_api%get_burnstep_num(burnstep_num)
do while (is_depletion)
if (burn_count <= burnstep_num) then
! 处理这一状态点的燃耗
call necpx%multiState_solver_api%deal_burnup(burn_count)
! 多状态点计算
call necpx%multiState_solver_api%steadystate_step()
call necpx%multiState_solver_api%calc_write_power()
call necpx%multiState_solver_api%depletion_step()
! 获得计算结果
call necpx%multiState_solver_api%get_burnup(burnup)
call necpx%multiState_solver_api%get_keff(keff)
call necpx%multiState_solver_api%get_matBurn(1, mat_burnup)
call necpx%multiState_solver_api%get_nucDens(1, n_nuclide, nucl_id, nucl_dens)
! 判断是否进行燃耗步进
call necpx%multiState_solver_api%get_coupling_method(coupling_method)
call necpx%multiState_solver_api%judge_correct_step(correct_step)
if (coupling_method == 1 .or. correct_step) then
burn_count = burn_count + 1
endif
else
is_depletion = .false.
endif
enddo
! 清除内存
call necpx%multiState_solver_api%clear()
call necpx%model_api%clear()
end program necpx_main
4.3.5. 瞬态问题
初始化后，首先进行初始的 稳态计算，然后进入 扰动遍历。在扰动中 ，可 自定义瞬态时间步，但必须要求时间步之和等于扰动的时间跨度。 每个扰动都要进行 扰动信息处理，时间步进，中子学计算，热工计算。
例:
program necpx_main
use api_functions
! 实例化
TYPE(necpx_api_functions_type) :: necpx
integer :: i_perb, n_perb, i_trans_step, n_trans_step
real(8) :: relaPower, initPower
real(8) :: reactivity, total_beta, generation_time
real(8), allocatable :: deltaT(:)
real(8), allocatable :: partial_lamda(:)
! 初始化
call necpx%model_api%init()
call necpx%transient_solver_api%init()
! 初始稳态计算
call necpx%transient_solver_api%steady_presolve()
! 获得稳态计算结果
call necpx%transient_solver_api%get_init_Power(initPower)
call necpx%transient_solver_api%get_reactivity(reactivity)
call necpx%transient_solver_api%get_total_beta(total_beta)
call necpx%transient_solver_api%get_partial_lambda(partial_lamda)
call necpx%transient_solver_api%get_generation_time(generation_time)
! 扰动遍历
call necpx%transient_solver_api%get_nPerb(n_perb)
do i_perb = 1, n_perb
! 重新设置第一个扰动的时间步
if (i_perb == 1) then
allocate(deltaT(3))
deltaT = (/0.0001d0, 0.0002d0, 0.0003d0/)
call necpx%transient_solver_api%set_deltaT(i_perb, deltaT)
endif
! 处理这一步的扰动信息
call necpx%transient_solver_api%deal_perb(i_perb)
! 瞬态时间步递进
call necpx%transient_solver_api%get_nTransStep(i_perb, n_trans_step)
do i_trans_step = 1, n_trans_step
! 中子学计算
call necpx%transient_solver_api%neutronics_step(i_trans_step)
! 热工反馈计算
call necpx%transient_solver_api%feedback_step()
! 获得瞬态步计算结果
call necpx%transient_solver_api%get_rela_Power(relaPower)
call necpx%transient_solver_api%get_reactivity(reactivity)
call necpx%transient_solver_api%get_total_beta(total_beta)
call necpx%transient_solver_api%get_partial_lambda(partial_lamda)
call necpx%transient_solver_api%get_generation_time(generation_time)
enddo
enddo
! 清除内存
call necpx%transient_solver_api%clear()
call necpx%model_api%clear()
end program necpx_main
|