Add value normalization range to s3d file

[rjokonski]

Is your feature request related to a problem? Please describe.
In our Results application for PyroSim and Pathfinder we read the s3d files in order to render smoke/fire and perform visibility calculations for occupants. In FDS 6.11.1, the soot density s3d file changed so that it includes per-frame normalized density values.

This is a great change; however, in order to determine the normalization range of soot density (i.e. the per-frame max value), we now also have to read the accompanying sz file. This causes a few issues:

• In the past, I've noticed that the sz file can become out of sync with the s3d file, perhaps because of different FDS runs, restarts, file corruption, etc. This can lead to incorrect de-normalization. In addition, a customer may need to share results. If they omit this file, we'll have incomplete data.
• The s3d file is binary while the sz file is text. This can create issues with lining up times between the two files because a parsed text time may end up slightly different than the binary time. We can build in a tolerance, but it's difficult to know what the tolerance should be.
• If we try to visualize while a simulation is running, the s3d file may get ahead of the sz file (perhaps because of internal buffer sizes or just that we end up reading them at slightly different times), so we can't just assume a one-to-one correspondence between frames.

Describe the solution you'd like
In the s3d file, in addition to writing NCHARS_IN and NCHARS_OUT for each frame, also write the normalization range for the values in that frame (e.g. 0 -> max_density for soot density or TEMP_MAX_SMV -> TEMP_MIN_SMV for flame temperature).

This would also require incrementing the file version (second parameter written in the file) so parsers can tell the files apart.

[optional] If a normalization range hasn't been specified in the FDS file (e.g. HRRPUV_MAX_SMV, TEMP_MAX_SMV, etc.), automatically calculate a normalization range for each frame based on the values in the mesh. This could provide a nice boost in precision.

[mcgratta]

I'll take a look at this.

[gforney]

whatever we do, don't think we want to change the format of the .s3d file - the last time we did this when use started using smoke density instead of smoke opacity caused a lot of head aches

[bwklein]

They were just changed, and while it might have caused some head aches, it didn't stop causing others.

I was talking to Richard today about this issue and the requirement to read two different files in two different formats to parse s3d data. It seems that reducing redundancy and complexity, while increasing precision, would be worth the effort for a new s3d format for FDS 7.

[mcgratta]

This commit does not change the current Smoke3d format, which we call SMOKE3D_VERSION=1. Version 0 would have been the original format. Setting SMOKE3D_VERSION on the DUMP line affects this code in smvv.f90

OPEN(LU_SMOKE3D(SMOKE3D_INDEX,NM),FILE=FN_SMOKE3D(SMOKE3D_INDEX,NM),FORM='UNFORMATTED',STATUS='OLD',POSITION='APPEND')
WRITE(LU_SMOKE3D(SMOKE3D_INDEX,NM)) TIME
SELECT CASE(SMOKE3D_VERSION)
   CASE(1) ; WRITE(LU_SMOKE3D(SMOKE3D_INDEX,NM)) NCHARS_IN,NCHARS_OUT
   CASE(2) ; WRITE(LU_SMOKE3D(SMOKE3D_INDEX,NM)) NCHARS_IN,NCHARS_OUT,MAX_VAL
END SELECT
WRITE(LU_SMOKE3D(SMOKE3D_INDEX,NM)) (BUFFER_OUT(I),I=1,NCHARS_OUT)
CLOSE(LU_SMOKE3D(SMOKE3D_INDEX,NM))

SMOKE3D_VERSION=1 by default for the moment while we test this.

Question for Glenn or Richard -- would it be better, from the standpoint of file parsing, to add the MAX_VAL after the TIME?

[rjokonski]

Kevin, from our perspective we would want the MAX_VAL after TIME and before the data, just like you have it.

Just to clarify, is MAX_VAL the value against which the values are normalized (i.e. BUFFER_IN[j]/MAX_VAL*254) or is it the maximum value in the buffer? From my understanding of HRRPUV and FLAME TEMPERATURE in 6.11.1, values are not necessarily normalized against their maximum value in the frame. For instance, by default HRRPUV is normalized against 1200 kW/m^3, but the maximum value in a particular frame might correspond with 600 kW/m^3.

For us, we would want MAX_VAL to be the former - the normalization value so we can de-normalize.

[gforney]

this value is already in the .sz file . why can't you get the value there? you mentioned syncing problems before. your code should be robust enough to ensure that you are reading consistent values between the .sz and .s3d files

…

On Wed, Sep 9, 2026 at 2:31 PM rjokonski ***@***.***> wrote: *rjokonski* left a comment (firemodels/fds#16546) <#16546 (comment)> Kevin, from our perspective we would want the MAX_VAL *after* TIME and before the data, just like you have it. Just to clarify, is MAX_VAL the value against which the values are normalized (i.e. BUFFER_IN[j]/MAX_VAL*254) or is it the maximum value in the buffer? From my understanding of HRRPUV and FLAME TEMPERATURE in 6.11.1, values are not necessarily normalized against their maximum value in the frame. For instance, by default HRRPUV is normalized against 1200 kW/m^3, but the maximum value in a particular frame might correspond with 600 kW/m^3. For us, we would want MAX_VAL to be the former - the normalization value so we can de-normalize. — Reply to this email directly, view it on GitHub <#16546?email_source=notifications&email_token=AC6UCRX6AGR3C63L7BBHUAL5OGOXTA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKNRQGY4DCMBWHEZ2M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5606810693>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AC6UCRVEF7AKXEE2J2CNJGT5OGOXTAVCNFSNUABEKJSXA33TNF2G64TZHMZTOMJUGY3DEMR3JFZXG5LFHM2TGOJRGY3DCMJYHCQXMAQ> . You are receiving this because you commented.Message ID: ***@***.***>

-- Glenn Forney

[bwklein]

There are 3 bullets in the initial post as to why having values in different files, in different formats, with time sync issues, is something that can be resolved by adding the information to the same file, with the same format, at the same point in time.
I am not sure why the .sz file is a necessary requirement for parsing s3d files. It seems to only add unnecessary complexity. I could be missing a key component to the system that requires it and I am open to understanding this more clearly.

[gforney]

memory allocation. I need to allocate memory for storing s3d data. the sizing information (hence the name of the file extension) I need to allocate this memory is in both the .sz and .s3d files but the .sz file can be read much faster than the .s3d file.

…

On Wed, Sep 9, 2026 at 2:42 PM Bryan Klein ***@***.***> wrote: *bwklein* left a comment (firemodels/fds#16546) <#16546 (comment)> There are 3 bullets in the initial post as to why having values in different files, in different formats, with time sync issues, is something that can be resolved by adding the information to the same file, with the same format, at the same point in time. I am not sure why the .sz file is a necessary requirement for parsing s3d files. It seems to only add unnecessary complexity. I could be missing a key component to the system that requires it and I am open to understanding this more clearly. — Reply to this email directly, view it on GitHub <#16546?email_source=notifications&email_token=AC6UCRWE7QDXVF727CIC3XD5OGQCFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKNRQGY4TKMJUHAZ2M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5606951483>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AC6UCRWWWTAEYFMAWD3QICD5OGQCFAVCNFSNUABEKJSXA33TNF2G64TZHMZTOMJUGY3DEMR3JFZXG5LFHM2TGOJRGY3DCMJYHCQXMAQ> . You are receiving this because you commented.Message ID: ***@***.***>

-- Glenn Forney

[rjokonski]

Glenn,

We can get it from there, and at the moment we do. I have written it to be as robust as I can, but I had to make some assumptions to get there, and there are certain cases where it can't be perfect. Here are a couple cases:

• In order to find a corresponding time in the sz file, we perform a binary search to find the nearest times and choose the nearest. This only works robustly as long as the sz file hasn't become partially corrupt. In the past, I believe this happened to me because of a restart, which caused earlier times to be written after later times, with times possibly becoming slightly different maybe because of a different time step calculation?
• If a simulation is still running and I load the sz file times and then parse the s3d file, the s3d file is often ahead of the sz file (i.e. has more times). If I perform a binary search, it just finds the last sz time. At this point, I need to perform a comparison of the times to make sure I'm not reading an incorrect sz time for the s3d time. Because of the different formats (binary vs text), however, I cannot just do an == comparison. I have to build in some tolerance. The best I can do is to create a tolerance that's a fraction of the difference between the times of the last two frames. I'm sure this will work in the vast majority of cases, but it isn't perfect, and if we're reading the wrong max density because I didn't match frames up perfectly, this could be a problem for our visualization.

[rjokonski]

I really didn't intend to create controversy with this request. I had run into complications parsing the new s3d format, and I thought this might be a nice way to avoid the issues I ran into that wouldn't require a huge change in FDS.

I understand that changing file formats can create headaches, and it looks like Kevin has come up with a way to alleviate that. In PyroSim, we could simply write all our FDS input files using the new version flag and then we'll get the easier parsing in our Results that we would like and everyone else can leave it out for their own needs.

I'm more than happy to back off of this, however, if there's too much discomfort.

[rjokonski]

Kevin,

If you do continue with this request, it looks like we'll need the minimum normalization value as well, since FLAME TEMPERATURE is normalized against the min->max range.

From section 27.14 of the FDS user guide:

[mcgratta]

This is the code in smvv.f90 just before the print out

MAX_VAL = 0._FB

IF (S3%DISPLAY_TYPE=='GAS') THEN

   MAX_VAL = MAXVAL(VALS(1:NVALS))
   DO I=1,NVALS
      VAL_SMV = MAX(0._FB,254.0_FB*(VALS(I)/MAX(1E-10_FB,MAX_VAL)))
      BUFFER_IN(I) = CHAR(NINT(VAL_SMV))
   ENDDO

ELSEIF (S3%DISPLAY_TYPE=='FIRE') THEN

   DO I=1,NVALS
      VAL_FDS = MIN(HRRPUV_MAX_SMV,MAX(0._FB,VALS(I)))
      VAL_SMV = 254*(VAL_FDS/HRRPUV_MAX_SMV)
      BUFFER_IN(I) = CHAR(NINT(VAL_SMV))
      MAX_VAL = MAX(VAL_FDS,MAX_VAL)
   ENDDO

ELSEIF (S3%DISPLAY_TYPE=='TEMPERATURE') THEN

   DO I=1,NVALS
      VAL_FDS = MIN(TEMP_MAX_SMV,MAX(TEMP_MIN_SMV,VALS(I)))
      VAL_SMV = 254*((VAL_FDS-TEMP_MIN_SMV)/(TEMP_MAX_SMV-TEMP_MIN_SMV))
      BUFFER_IN(I) = CHAR(NINT(VAL_SMV))
      MAX_VAL = MAX(VAL_FDS,MAX_VAL)
   ENDDO

ENDIF

[rjokonski]

So for fire and temperature it looks like MAX_VAL is the maximum of the buffer data rather than the normalization range. So instead of MAX_VAL, we would need these two values for each display type in the s3d file:

• GAS: 0, MAX_VAL
• FIRE: 0, HRRPUV_MAX_SMV
• TEMPERATURE: TEMP_MIN_SMV, TEMP_MAX_SMV

[mcgratta]

Let me look to see how these values are conveyed to Smokeview from FDS. These two programs typically share information via the .smv file, the data files themselves, and these sizing (sz) files.