View source for Reaction File (RCT) Text Format

[[Category:Reactions]]
{{Navigation|[[User Guide]]|[[Editors and Utilities]]|[[Reaction Editor]]}}
<!--{{Reactions Head Tabs |currentpage=2}}-->

'''Related Links:''' [[Reaction Editor]]
----

{{TOC}}
== Editing SysCAD Reactions ==

* Chemical reactions used in SysCAD are defined in a text file. 
* The user may use the SysCAD [[Reaction Editor]] (this is highly Recommended) or any text editor to edit these reactions.
* You do not need to run SysCAD to use the Reaction Editor, so you can view and/or edit reaction files without loading a project.  
* You may open the reaction files with a text editor, such as Notepad, Notepad++, Textpad, etc., outside of SysCAD, if required.  
* The reaction filename must have the extension ''.rct''.
* The reaction file must contain at least one reaction, i.e. sources, sinks and heat exchange cannot be used in isolation without at least one reaction.
* Any line in the file starting with a ''';''' is a comment and is ignored.
* When the manually edited reaction text file is upgraded by the [[Reaction Editor]] some formatting on the file will be changed. '''Caution''': In some cases where there are simultaneous reactions and they are listed in an unusual order, then the reaction editor may renumber the reactions when the file is first upgraded.

== Example of a Reaction File ==
An example reaction file is given below. Note the inclusion of '''format:4''', required for Build 137 and later.

  <font color="red">format:4</font>
  
  <font color="red">SourceList: Source,Recycle</font> O2(g)
 
  <font color="red">Reactions:</font>
  
  1 FeCO3(s) <font color="red">+</font> 1 H2SO4(aq) <font color="red">-></font> 1 FeSO4(aq) <font color="red">+</font> 1 H2O(l) <font color="red">+</font> 1 CO2(g)
  <font color="blue">Extent</font>: <font color=#F57EBA>Fraction</font> FeCO3(s) <font color="red">=</font> 0.44
 
  4 FeSO4(aq) <font color="red">+</font> 2 H2SO4(aq) <font color="red">+</font> O2(g) <font color="red">=</font> 2 Fe2[SO4]3(aq) <font color="red">+</font> 2 H2O(l)
  <font color="blue">Extent</font>: <font color=#F57EBA>msFinalConc</font> Fe2[SO4]3(aq) in Liq <font color="red">=</font> 0.05
  <font color="blue">HeatOfReaction</font>: <font color=#F57EBA>msFixed</font> <font color="red">=</font> 10 / FeSO4(aq) <font color=#F57EBA>At</font> 25, 101.325
 
  <font color="blue">HeatExchange</font>: <font color=#F57EBA>FinalT</font> <font color="red">=</font> 60
 
  <font color="red">Sink</font>: CO2(g)
 
  <font color="red">End</font>

'''Notes:'''
# The tokens ''"Reactions"'': and ''"End"'' are compulsory as they mark the start and end of the reactions block. 
# At least one reaction must be defined between these two tokens.
# The phase of the reactant and product species '''must''' be given, e.g. FeCO3(s) and CO2(g).
# The species and phases must be exactly as defined in SysCAD.

== Reaction File Template ==

There is the flexibility to allow a template rct file to be used. This template must be called template.rct and can be placed in either the CfgFiles folder of the project or the BaseFiles folder of the SysCAD installation. The user may edit this file to suit. SysCAD will look in the CfgFiles folder first for a template and then the BaseFiles folder if one is not found in the CfgFiles folder.

'''Note:''' This is NOT required if the SysCAD Reaction Editor is used.

== Reaction Directions ==

'''-&gt; Forward Reaction'''
:{|
|-
|'''Format ''' || Reactant_1(s) + Reactant_2(l) '''-&gt;''' Product_1(g) + Product_2(s) + Product_3(s)
|}

''' &lt;-&gt; or = Reversible Reaction'''
:{|
|-
|'''Format ''' || Reactant_1(s) + Reactant_2(l) '''&lt;-&gt;''' Product_1(g) + Product_2(s) + Product_3(s)
|-
| &nbsp; || Reactant_1(s)'' + ''Reactant_2(l)'' '''=''' ''Product_1(g) + Product_2(s) + Product_3(s)
|}

== Reaction Extents ==

There are a number of methods for expressing the extent of a reaction in a reaction block.  The format for all of these will be described here.  <!--For more information on the actual extent methods, refer to [[Reaction Block - Extents]].-->

=== Fraction ===

:{|
|-
|''Format'' || '''Extent: Fraction''' Species(phase) = fraction
|-
| valign="top"| ''Description'' || The species specified must be one of the reactants.
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''Fraction'''</font> Na2CO3(s) <font color="red">=</font> 0.50
|}

=== Final Fraction ===

'''Mass Fraction'''

:{|
|''Format '' || '''Extent: msFinalFraction''' '''Phase''' Species(phase) = fraction 
|}

:{|
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''msFinalFraction Phase'''</font> CaS(s) = 0.1 
|}

:OR

:{|
|''Format'' || '''Extent: msFinalFraction''' '''Total''' Species(phase) = fraction 
|}

:{|
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''msFinalFraction Total'''</font> CaS(s) = 0.1 
|}

'''Mole Fraction'''
:{|
|-
|''Format'' || '''Extent: mlFinalFraction''' '''Phase''' Species(phase) = fraction 
|}

:{|
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''mlFinalFraction Phase'''</font> CaS(s) = 0.1 
|}

:OR

:{|
|''Format'' || '''Extent: mlFinalFraction''' '''Total''' Species(phase) = fraction 
|}

:{|
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''mlFinalFraction Total'''</font> CaS(s) = 0.1 
|}

'''Note:''' 
The '''Phase/Total''' keywords are optional. If neither is specified, the default is by '''Phase'''.

=== Final Elemental Fraction ===

{{Available139|32925}}

'''Mass Fraction'''

:{|
|''Format '' || '''Extent: msFinalElemFraction''' Element in Phase = fraction 
|}

:{|
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''msFinalElemFraction'''</font> S in Liq = 0.05 
|}

'''Mole Fraction'''
:{|
|-
|''Format'' || '''Extent: mlFinalElemFraction''' Element in Phase = fraction 
|}

:{|
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''mlFinalElemFraction'''</font> S in aq = 0.05 
|}

=== Final Concentration ===

'''Mass Concentration'''
:{|
|-
|''Format '' || '''Extent: msFinalConc''' Species(phase) in Phase = conc '''At''' temperature
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''msFinalConc'''</font> H<sub>2</sub>SO<sub>4</sub>(aq) in Liq = 5.5 At 25
|}

:'''Notes:''' 
:# The concentration is specified in g/L.
:# The Phase can be total liquid phase (Liq) or any of the individual liquid phases (e.g. aq).
:# 'At temperature' is optional. If not specified, concentration will be calculated at the product temperature.
:# The temperature is specified in °C

'''Mole Concentration'''
:{|
|-
|''Format '' || '''Extent: mlFinalConc''' Species(phase) in Phase = conc '''At''' temperature
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''mlFinalConc'''</font> H<sub>2</sub>SO<sub>4</sub>(aq) in Liq = 5.5 At 25
|}

:'''Notes:''' 
:# The concentration is specified in mol/L.
:# The Phase can be total liquid phase (Liq) or any of the individual liquid phases (e.g. aq).
:# 'At temperature' is optional. If not specified, concentration will be calculated at the product temperature.
:# The temperature is specified in °C

=== Final Elemental Concentration ===

'''Elemental Mass Concentration'''
:{|
|-
|''Format '' || '''Extent: msFinalElemConc''' Element As Phase1 In Phase2 = conc '''At''' temperature
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''msFinalElemConc'''</font> Fe As aq in Liq = 5.5 At 25
|}

:'''Notes:''' 
:# The concentration is specified in g/L.
:# Phase1 can be Total, total phase (Liq, Gas or Sol) or any of the individual phases (e.g. aq).
:# Phase2 can be total liquid phase (Liq) or any of the individual liquid phases (e.g. aq).
:# 'At temperature' is optional. If not specified, concentration will be calculated at the product temperature.
:# The temperature is specified in °C

'''Elemental Mole Concentration'''
:{|
|-
|''Format '' || '''Extent: mlFinalElemConc''' Element As Phase1 in Phase2 = conc '''At''' temperature
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''mlFinalElemConc'''</font> Fe As aq in Liq = 5.5 At 25
|}

:'''Notes:''' 
:# The concentration is specified in mol/L.
:# Phase1 can be Total, total phase (Liq, Gas or Sol) or any of the individual phases (e.g. aq).
:# Phase2 can be total liquid phase (Liq) or any of the individual liquid phases (e.g. aq).
:# 'At temperature' is optional. If not specified, concentration will be calculated at the product temperature.
:# The temperature is specified in °C

=== Amount Reacted ===

'''Mass Reacted'''
:{|
|-
|''Format '' || '''Extent: msFlow''' Species(phase) = flow
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''msFlow'''</font> H<sub>2</sub>SO<sub>4</sub>(aq) = 10
|}

:'''Note:''' The flow is specified in kg/s.

'''Moles Reacted'''
:{|
|-
|''Format '' || '''Extent: mlFlow''' Species(phase) = flow
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''mlFlow'''</font> H<sub>2</sub>SO<sub>4</sub>(aq) = 10
|}

:'''Note:''' The flow is specified in kmol/s.

=== Final Flow ===

'''Final Mass Flow'''
:{|
|-
|''Format '' || '''Extent: msFinalFlow''' Species(phase) = flow
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''msFinalFlow'''</font> H<sub>2</sub>SO<sub>4</sub>(aq) = 10
|}

:'''Note:''' The flow is specified in kg/s.

'''Final Mole Flow'''
:{|
|-
|''Format '' || '''Extent: mlFinalFlow''' Species(phase) = flow
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''mlFinalFlow'''</font> H<sub>2</sub>SO<sub>4</sub>(aq) = 10
|}

:'''Note:''' The flow is specified in kmol/s.

=== Ratio ===

'''Mass Ratio'''
:{|
|-
|''Format'' || '''Extent: msRatio''' Reactant Species(phase) : Product Species(phase) = 1:a
|-
|''Example'' || <font color="blue">Extent</font>: <font color=#F57EBA>'''msRatio'''</font> Na2CO3(s):Na2SO4(s) = 1:500
|}

'''Molar Ratio'''
:{|
|-
|''Format'' || '''Extent: mlRatio''' Reactant Species(phase) : Product Species(phase) = 1:a
|-
|''Example'' || <font color="blue">Extent</font>: <font color=#F57EBA>'''mlRatio'''</font> Na2CO3(s):Na2SO4(s) = 1:500
|}

=== Equilibrium ===
:{|
|-
|''Format'' || '''Extent: Equilibrium''' number
|-
|''Example'' || <font color="blue">Extent</font>: <font color=#F57EBA>'''Equilibrium'''</font> 2.5
|}

=== User Calculation ===

:{|
|-
|''Format '' || '''Extent: UserCalc''' CalcX = value
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''UserCalc'''</font> Fe2+ = 10
|}

:'''Note:''' The units of the value will depend on the units of the user calculation.

=== Species Calculation ===

:{|
|-
|''Format '' || '''Extent: SpCalc''' CalcY as View in Basis = value
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''SpCalc'''</font> Fe2+ as QM in Phase  = 10
|}

:'''Notes:''' 
:# The units of the value will depend on the chosen View.
:# View can be M (Mass), QM (Mass Flow), MF (Mass Fraction), Ml (Moles), QMl (Molar Flow), MlF (Mole Fraction), Vl (Volume), QVl (Volume Flow), VlF (Volume Fraction), NVl (Normal Volume), NQVl (Normal Volume Flow), NVlF (Normal Volume Fraction), Cnc (Concentration), Cnc25 (Concentration @ 25°C), CncMl (Molar Concentration), CncMl25 (Molar Concentration @ 25°C), CncEq (Equivalent Concentration), CncEq25 (Equivalent Concentration @ 25°C) or Mll (Molality).
:# Basis can be All, Phase or IPhase.

=== Species Model Property ===

:{|
|-
|''Format '' || '''Extent: SpModelProp''' SpModel PropZ  = value
|}

:{|
|-
|''Example '' || <font color="blue">Extent</font>: <font color=#F57EBA>'''SpModelProp'''</font> Standard SolidConc  = 10
|}

:'''Notes:''' 
:# The units of the value will depend on the chosen property.
:# SpModel can be can be '''Standard''' and any other species model used in the project such as '''Bayer3''' or '''Potash'''.

=== Dynamic Rate ===

:{|
|-
|''Format 1'' || '''Extent: Fraction''' Species(phase) = fraction '''Rate''' = rate
|-
|''Example'' || <font color="blue">Extent</font>: <font color=#F57EBA>'''Fraction'''</font> FeS2(s) = 0.5 <font color=#F57EBA>'''Rate'''</font> = 0.0001
|}

:{|
|-
|''Format 2'' || '''Extent: Fraction''' Species(phase) = fraction '''Rate''' = rate '''Stabilised'''
|-
|''Example'' || <font color="blue">Extent</font>: <font color=#F57EBA>'''Fraction'''</font> FeS2(s) = 0.5 <font color=#F57EBA>'''Rate'''</font> = 0.0001 <font color=#F57EBA>'''Stabilised'''</font>
|}

:'''Notes:'''
:# The rate is specified as a fraction per second.
:# The value for fraction is optional. If not specified, the default is 1.

=== Dynamic Fraction ===

:{|
|-
|''Format'' || '''Extent: Fraction''' Species(phase) = fraction '''TimePeriod''' = time
|}

:{|
|''Example'' || <font color="blue">Extent</font>: <font color=#F57EBA>'''Fraction'''</font> FeS2(s) = 0.5 <font color=#F57EBA>'''TimePeriod'''</font> = 10
|}

:'''Note:''' The time period is specified in seconds.

== Sequence (Sequential or Simultaneous) ==

By default, reactions will solve in a '''SEQUENTIAL''' order, the order is defined by how they appear in the reaction file.  However, the user can change the sequence order by inserting a sequence number per reaction or reaction set. The reactions with the same sequence number will be solved '''SIMULTANEOUSLY'''. The sequence number must be an integer equal to or greater than zero.  Reactions with the lowest sequence are solved first.

Please see [[Reaction Block - Solving Reactions]] for more information.


{|style="width:70%"
|-
|''Format''  ||   Reaction Extent  ||   '''Sequence:''' number
|}

Example:

:{| 
|-
|Rxn1: || A + B || -> || C + D || Extent: Fraction A = 0.5 Sequence: 1
|-
|Rxn2: || E + F || -> || G + H || Extent: Fraction E = 0.1 Sequence: 0
|-
|Rxn3: || C || -> || J + K || Extent: Fraction C = 0.9 Sequence: 2
|}

'''Notes:'''
# When specifying the sequence number for any reaction in the list, the user MUST make sure the first reaction also has a sequence number defined. If not, SysCAD will generate an error message and will not proceed.
# It is not necessary to specify the sequence number for each reaction.  Once a sequence number has been specified, all the following reactions are assumed to be at the same sequence unless a new sequence number is found.
#: For example:
:{|
|-
|Rxn1: || A + B || -> || C + D || Extent: Fraction A = 0.5  Sequence: 0
|-
|Rxn2: || E + F || -> || G + H || Extent: Fraction E = 0.1
|-
|Rxn3: || C || -> || J + K || Extent: Fraction C = 0.9
|}

== Heat of Reaction Override  ==

'''Molar Basis'''

:{|
|-
|''Format'' || '''HeatOfReaction: MlFixed''' = number / Species(phase) At condition
|}

:{|
|''Example 1'' || HeatOfReaction: MlFixed = 0 / CaS(s) At Feed
|-
|''Example 2'' || HeatOfReaction: MlFixed = 0 / CaS(s) At 15, 100
|}


'''Mass Basis'''

:{|
|-
|''Format'' || '''HeatOfReaction: MsFixed''' = number / Species(phase) At condition
|}

:{|
|''Example 1'' || HeatOfReaction: MsFixed = 0 / CaS(s) At Prod
|-
|''Example 2'' || HeatOfReaction: MsFixed = 0 / CaS(s) At 15, 100
|}

'''Notes:'''
# The heat of reaction is specified in kJ/kmol for the Molar basis and kJ/kg for the Mass basis.
# The options for condition are: ''Feed'', ''Prod'', ''Std'' or custom (user specified temperature and pressure).
# If the custom condition is used, the temperature is specified in °C, and the pressure is specified in kPa.
# The '''At condition''' is optional. If not specified, the default is Std.

Examples of user Heat of Reaction override in a test file is shown below:

:[[Image:HOR_override_Example.png]]

== Source and Sink ==

# SysCAD allows the user to define any number of localised sources of reactants and/or sink of components.
# Please see [[Reaction Block - Other|Sources and Sinks]] for more information.

=== Source ===

3 options:
:{|
|-
|''Format '' || '''SourceList: Source''' Species_1, Species_2
|-
|''Example '' || SourceList: Source O2(g), H2SO4(aq)
|}

:{|
|-
|''Format '' || '''SourceList: Recycle''' Species_1, Species_2
|-
|''Example '' || SourceList: Recycle O2(g), H2SO4(aq)
|}

:{|
|-
|''Format '' || '''SourceList: Source,Recycle''' Species_1, Species_2
|-
|''Example '' || SourceList: Source,Recycle O2(g), H2SO4(aq)
|}

'''Notes:''' (applicable to all versions)
# The Source has to appear before the '''Reactions''' token at the beginning of the file.
# There can only be a single Source defined in a file.
# The Source may have any number of species.
# There must be at least one reaction defined in the file.

=== Sink ===
:{|
|-
|''Format'' || '''Sink:''' Species_1, Species_2
|-
|''Example'' || Sink: CO2(g)
|}
'''Notes:'''
# The sink option must be defined before the '''End''' token.
# There can only be a single Sink defined in a file.
# The Sink may have any number of species.
# There must be at least one reaction defined in the file.

== Heat Exchange ==

# The Heat Exchange options can be used only once in a reaction block.
# It and must occur after the definition of the last reaction.
# There must be at least one reaction in the file for Heat Exchange to work.
# Please see [[Reaction Block - Other|Heat Exchange]] for more information.

=== FinalT ===
:{|
|-
|''Format''|| '''HeatExchange: FinalT''' = temperature
|-
| valign="top" rowspan="3" |''Examples '' || HeatExchange: FinalT = FeedT
|-
|HeatExchange: FinalT = 200
|}

:'''Notes:'''
:# The options for temperature are ''FeedT'' or custom (user specified temperature).
:# If a custom temperature is used then it is specified in °C.
:# The default temperature is atmospheric temperature.

=== Power ===
:{|
|-
|''Format '' || '''HeatExchange: Power''' = power
|-
| valign="top" rowspan="3" |''Examples '' || HeatExchange: Power = 60
|-
|HeatExchange: Power = -60
|}

:'''Notes:'''
:# The power is specified in kJ/s.
:# A positive power indicates energy is being added to the unit.
:# A negative power indicates energy is being lost from the unit.
:# The default power is 0.

=== Approach ===

:{|
|-
|''Format '' || '''HeatExchange: Target''' = temperature, '''Approach''' = fraction, '''Basis''' = basis
|-
| valign="top" |''Examples '' || HeatExchange:  Target = 25, Approach = 1, Basis = Product

HeatExchange: Target = EnvironmentT, Approach = 0.5, Basis = Feed 
|}

:'''Notes:'''
:# The options for temperature are ''EnvironmentT'' or custom (user specified temperature).
:# If the custom target temperature is used then it is specified in °C.
:# The default for target temperature is 25 °C.
:# The default for approach fraction is 1.
:# The options for basis are ''Feed'' or ''Product''.
:# The default for basis is Product.

=== Electrolysis ===
:{|
|-
|''Format '' || '''HeatExchange: Electrolysis''' = fraction 
|-
| valign="top" |''Example'' || HeatExchange: Electrolysis = 0.90
|}

:'''Note:''' The default for fraction is 1.