# What's New

## 3.2.0 (April 9, 2026)

* Now validates geojson geometries to have the correct number of dimensions and coordinates.
* Updated docs.
* Updated environment files to point to the commit for changes to `OpenDrift` that support `LarvalFish` and `Phytoplankton` models.
* Removed references to "legacy" in `LarvalFish` and now points to `LarvalFishExtended` in `OpenDrift` instead of the original `LarvalFish` model.

## 3.1.0 (March 26, 2026)

* Fixed bug so that `seed_floor` can be used. Now if `seed_seafloor` is selected, `z` is automatically set to `None` which activates `seed_seafloor` in `OpenDrift`.

## 3.0.0 (March 12, 2026)

* Fixed bug so that horizontal diffusivity is now properly applied to model output.
* Added `wind_drift` parameter which when False makes sure that `wind_drift_factor=0` so that wind drift is not on.
* If `do3D==False`, vertical_mixing is now also turned to False. Otherwise it is easy to run 2D with vertical mixing on.
* Made sure the `vertical_mixing_at_surface` is consistent with `vertical_mixing` and `vertical_advection_at_surface` is consistent with `do3D`.

## 2.5.0 (March 9, 2026)

* Change to NWGOA config to fix issue with wet/dry sims not running with NWGOA.
* Fixed change to "all" plots to add depth and mean depth in time.

## 2.4.2 (March 6, 2026)

* changed some defaults in new work
* updated tests accordingly
* do not use land_binary_mask to plot in animation when plotting after the simulation has been run previously

## v2.4.0 (March 5, 2026)

* Changed default value of `use_static_masks` to False from True, so that wet/dry masks from ocean models are used by default.
* Added `time_step_output_integer` to the schema which is a multiplier on `time_step` to calculate `time_step_output`. `time_step_output` is calculated in a field and input to the `OpenDrift` model.
* If global land mask was not used in simulation, plot the model land mask in animations and not the global land mask. This is especially helpful for a wet/dry landmask to see how it changes in time.
* "all" plots option now includes two more plots: depth of all particles in time and mean depth of particles in time.
* Changed to mp4 instead of gif for built in animations default.
* Deprecated `HarmfulAlgalBloom` drift model in favor of `Phytoplankton` drift model:
  * Removed biomass tracking and temperature/salinity response parameters
  * Removed `species_type` presets (PN, AX, DP)
  * Renamed parameters: `swim_speed` → `w_active`, `band_center_depth` → `z_pref`, `diel_day_depth`/`diel_night_depth` → `z_day`/`z_night`
  * Changed `vertical_behavior` → `vertical_behavior_mode` with new options: `none`, `depth`, `dvm`
  * Phytoplankton requires `do3D=True` and `vertical_mixing=True`
* Enhanced `LarvalFish` drift model with new vertical behavior modes and hatching methods:
  * Added `vertical_behavior_mode` parameter: `none`, `depth`, `dvm`, or `legacy` (preserves original behavior)
  * Added new depth-targeting parameters: `z_pref`, `z_day`, `z_night`, `w_active`
  * Added band expansion parameters: `dz_min`, `dz_rel`, `dz_max`
  * Added `hatching_method` parameter: `temperature` (default, legacy) or `fixed_time`
  * Added `hatch_time_days` parameter for fixed-time hatching method
* Updated test suite to use `Phytoplankton` instead of `HarmfulAlgalBloom` and added comprehensive tests for new `LarvalFish` features

## v2.3.0 (January 15, 2026)

* The depths required for `HarmfulAlgalBloom` species types are now calculated for the 3 available species from the mixed layer depth.

## v2.2.4 (January 12, 2026)

* add new `OpenDrift` parameter `vertical_advection_at_surface` which is necessary to have vertical advection at the very surface. These new parameters are in all 3D scenarios except oil.

## v2.2.3 (January 12, 2026)

* added new `OpenDrift` parameter `vertical_mixing_at_surface` without which particles will stick to the surface

## v2.2.2 (January 12, 2026)

* No longer requiring `z==None` when `seed_seabed==True`; also `z` can no longer have the value `None`.
* Max value of `wind_drift_depth` is now 1 instead of 10.
* Max value of `wind_drift_factor` is now 0.1 instead of 1.


## v2.2.1 (January 9, 2026)

* Added parameters `do3D=True` and `vertical_mixing=True` for the HarmfulAlgalBloom scenario
* Change so that when `hatched==1`, `stage_fraction` needs to be a number that will be ignored instead of `None`


## v2.2.0 (January 7, 2026)

* Changes to `HarmfulAlgalBloom` to support updates in `OpenDrift` model:
  * Added and renamed some parameters.
  * Added another test, to test growth in the HAB scenario since that has now been added.
* Added vertical behavior
* Added two new species
* Fixed `mixed_layer_depth` so it is actually used now
* unpinned `OpenDrift`

## v2.1.2 (December 19, 2025)

* Fixed bug so that CIOFSOP `end_time` is updated before the simulation run `end_time` gets validated
  against it.


## v2.1.1 (December 17, 2025)

* Fixed bug when using geojson particle seeding. Now `PTM` will properly assign `radius` and `radius_type` when using a geojson `Point`, `LineString`, or `Polygon`.

## v2.1.0 (December 15, 2025)

* Fixed bug so now CIOFSOP `end_time` is updated each time a new instance of `OpenDriftModel` is created.
* fixed logging issue so `OpenDrift` logs show up more fully again.
* `seed_flag` is no longer in the schema and whether to input particle locations is determined by whether `lon` and `lat` are input or a `geojson` input is input. If neither are input, default lon/lat are available that work with the default ocean model.

## v2.0.6 (December 11, 2025)

* `output_format="parquet"` is still present and will work with the newest version of `OpenDrift` once a PR is merged.
* A new option has been added: `output_format="both"`. This saves `OpenDrift` output to a netCDF file but then after the simulation is over also saves a parquet file, not using `OpenDrift` for that step. This allows PTM to produce both a netCDF file and parquet file for the same `OpenDrift` simulation, which is helpful because the same metadata is not currently available in an output parquet file as is a netCDF file, so you can't go between without losing information.

## v2.0.5 (December 10, 2025)

* Changed the schema for `HarmfulAlgalBloom` so that "PN", for example, is input, though a nice label is also provided through "title" in the schema.

## v2.0.4 (Decemeber 9, 2025)

* Fixed a log file path bug where the log file path was just the filename only.
  Because of that it would get created in the current working directory and not
  in the outputs directory next to the simulation output.
* Refactored the `SetupOutputFiles` model to simplify things a bit and update tests.


## v2.0.3 (Decemeber 5, 2025)

* Fixed docs.

## v2.0.2 (Decemeber 5, 2025)

* Changed "name" of `HarmfulAlgalBloom` `species_type` enum to be an abbreviation "PN" and the value for the initial species to be "Pseudo nitzschia" instead of "Pseudo_nitzschia".
* Added to the `HarmfulAlgalBloom` schema to have a "oneOf" output containing the preset values associated with a `species_type` in the description.


## v2.0.0 (December 4, 2025)

* Added a new model scenario: `HarmfalAlgalBloom`.
* Fix a bug for running backward in time.
* Ocean model configuration files now need to include `chunks`


## v0.13.2 (November 20, 2025)

* If timezone-aware `start_time`, `start_time_end`, or `end_time` is input, the timezone is now removed and it is assumed they are in the same timezone as the model times.


## v0.13.1 (November 19, 2025)

* Fixed kerchunk JSON file filtering.
* Added CIOFS3 as ocean model option.
* Refactored `OilTypeEnum` so that it's value is only the oil ID. Also add the
  "oneOf" json schema mapping directly to the field's `json_schema_extra` so that
  it is part of the schema by default.


## v0.12.2 (April 15, 2025)

* fixed issue when setting `vertical_mixing` False for `OpenOil` was not passed through correctly
* now `do3d=False` and `vertical_mixing=True` can be set at the same time.
* updated some config descriptions
* found error in `OilTypeEnum` leading to oil_types with duplicate labels not being separated out in the Enum. This is fixed. Now oil should be input with either the ID from ADIOS or with the syntax `(ID, label)`. Once in the configuration, it will be presented as only `label` since that is how `OpenDrift` accepts `oil_type`.
* `OilTypeEnum` was reordered so the first 5 oils are most relevant to Alaska work.
* Reverted `time_step` units back to seconds from minutes. It was being mapped unexpectedly in `OpenDrift` so using seconds is better.
* Updated list of options for `object_type` and it is now fully consistent with that in `OpenDrift`.
* Now enforce that for Leeway model if `hatched==1` then `stage_fraction=None`, for seeding.
* Updated descriptions in a lot of parameters in `config_the_manager.py` and `config_opendrift.py`.
* Updated defaults in config classes.


## v0.12.1 (April 8, 2025)

* Correction to `interpolator_filename` handling and improvement in testing.


## v0.12.0 (April 9, 2025)

* Major refactoring:
    * Removed `surface_only` flag.
    * Changed default value for `vertical_mixing` to False to match `do3D` default of False.
    * Moved some configuration parameters between configuration objects.
    * Major improvements of log handling.
    * `time_step` and `time_step_output` changed to minutes from seconds.
    * ocean_model_registry for known and user-input models
    * changed some logger statement from "info" to "debug"
    * now pinned to `opendrift` v1.13.0 and `kerchunk` v0.2.7 because not ready for zarr v3
    * can run plots from a parquet or netcdf output file now
    * can't run idealized simulations using `OpenDrift` directly in PTM anymore but this could be added back in if needed
    * updated docs
    * property plot now requires keyword "variable" instead of "prop" (this change is from `OpenDrift`)
    * most configuration parameters are under `m.config` now instead of just `m`, if `m` represents a Manager instance.
    * a geojson dict can be input but it is not fully working at the moment
    * `oil_type` can be input as the name or the id from the adios database.
    * `.model_json_schema()` is overridden in `OpenDriftConfig` to include a bit of custom code to modify the `oil_type` output in the JSON schema "properties" area. This shouldn't affect anything other than it being available if people want that.


## v0.11.2 (February 6, 2025)

* Suffix for parquet file format is now ".parquet" instead of ".parq".
* Added a method to run plots from saved OpenDrift output file; also available in CLI. Updated docs.


## v0.11.1 (February 4, 2025)

* Move known model hard-wired model times into the class so they are refreshed each time the library is read.
* Add dockerfile for running PTM in a container.

## v0.10.1 (January 30, 2025)

* Added built-in way to create plots for simulation using OpenDrift. Details available in {ref}`plots`.
* User can now input a location to both save and read the interpolator, which avoids using the built-in cache location.

## v0.9.6 (November 15, 2024)

* made caching directory creation and saving to cache optional with input option `use_cache`.

## v0.9.5 (November 14, 2024)

* fixed error in output file

## v0.9.4 (November 14, 2024)

* Updated locations for local model output.

## v0.9.3 (November 13, 2024)

* Moved `output_format` parameter to manager config from model config
* Changed source location for CIOFSOP local model output

## v0.9.2 (November 11, 2024)

* Added ability to save output files as parquet instead of netcdf.
* Partially updated docs

## v0.9.1 (October 25, 2024)

* Added local model option of CIOFS Fresh for which kerchunk files also can be generated on the fly.

## v0.9.0 (July 26, 2024)

* Added utilities to generate kerchunk files on the fly for the time period of the simulation length for CIOFS and NWGOA. This has majorly sped up CIOFS simulations and modestly sped up NWGOA simulations.
* depth z should be negative! Fixed this in tests.
* added `start_time_end`, which adds OpenDrift capability for starting drifters over linear time frame
* fixed so unique log file is output for each simulation even if run in a script, and has the same name as `output_file`.
* small fix to histogram plot

## v0.8.4 (April 24, 2024)

* updated the `ptm_level` of a bunch of config parameters

## v0.8.3 (April 23, 2024)

* removed `Dcrit` because realized it is not necessary
* improved log handling for CLI
* changed `OpenDrift` default handling so they are now changed to None

## v0.8.2 (April 10, 2024)

* updated docs
* improved `drift_model_config()`
* updated tests
* now include PTM metadata with output file

## v0.8.1 (April 5, 2024)

* updated docs

## v0.8.0 (April 2, 2024)

* `time_step_output` behavior has changed — 1 hour by default
* `time_step` is now 5 min by default
* added `Dcrit` parameter for accurately finding where drifters are stranded in tidal flats
* `vertical_mixing` is True by default now
* added seafloor_action option
* fixed some Leeway/3D handling and log messaging
* export_variables are specific to drift_model as needed
* do not drop zeta anymore since used in opendrift
* output_file is now an option


## v0.7.1 (February 21, 2024)

* Small fix to some attributes to be less verbose
* Fix setup.cfg to have correct config path since name changed


## v0.7.0 (February 21, 2024)

* Now initialize all class attributes with None and removed usage of `hasattr` which simplifies and clarifies some code.
* Improved handling of `start_time`, `end_time`, `duration`, and `steps` in `manager.py` which fixed a bug in which users couldn't input `start_time` and have the simulation run successfully.
* simplified handling of `horizontal_diffusivity` in `opendrift` model.
* user can change `end_time`, `duration`, and `steps` and have the others update accordingly. Tests added to check this.
* changed known model "CIOFS_now" to "CIOFSOP" to avoid upper/lower issues and include "OP" for "operational".
* many more tests and improved behavior for attribute checks and updates


## v0.6.0 (February 15, 2024)

* is set up to tell `opendrift` ROMS reader to save the interpolator to a cache that is set up the first time it is run. This only works with the newest dev version of `opendrift` at the moment, and the files saved are hundreds of MB, but it speeds up the simulations pretty well (12 to 30 seconds).
* reworked which variables are dropped in which scenarios for `opendrift` and integrated with using wetdry vs static masks.
* added package `appdirs` to manage the cache for storing interpolator pickles.
* fix to CLI so duration input is formatted correctly.
* can now input `name` to accompany user-input `xarray Dataset` for `ocean_model`.
* added `ocean_model` "CIOFS_now" local and remote links.


## v0.5.0 (February 12, 2024)

* updated to using version of `opendrift` in which you can input an xarray Dataset directly
* added new parameter for built-in ocean_models to specify whether to look locally or remote for the output (`ocean_model_local`)
* added local model output information for known models using parquet files for kerchunk access to model output
* changed `max_speed` parameter, which controls buffer size in `opendrift`, to 2 from 5.
* improved handling of "steps", "duration", and "end_time" parameters.
* improved reader interaction and speed with `opendrift` by dropping unnecessary variables from ocean_model Dataset, separating out the `standard_name` mapping input to the ROMS reader in `opendrift`, added option for whether or not to use wet/dry masks in ocean_model output if available


## v0.4.0 (January 25, 2024)

* modified level of surfacing for some configuration parameters
* made `ptm` an entry point
* finished removing WKT code, which hadn't been working
* added “excludestring” as an option for filtering configuration parameters
* updated checks for necessary `drift_model=="Leeway"` and parameter combinations.
* updated docs according to software updates